Skip to content
SHC Docs

Architecture register

Layers 0 to 11. Layer map.

The one live list of where shc and ce depart from the intended architecture. It has three parts. Open rows are departures somebody still has to remove. Accepted exceptions are departures that stay on purpose. Closed rows are gone, with the reason.

This page replaces five separate registers. They are kept as dated records under ../reviews/ and are listed at the end. A record is not edited. A row that still held on 2026-11-11 was carried here with today’s path. A row that was not found again was not carried.

Measured at shc a31ba31045ae and ce 8981426e98e8 on 2026-11-11.

  • Rule is the ruling or doctrine, then how the code departs from it.
  • Evidence is a path that exists today, with a line where one line shows it. A path with ce in front is in the ce repo at the commit go.mod pins. Every other path is in this repo.
  • Lane is the batch of the 2026-11 architecture sweep (AS01 to AS64, FZ-10491) that removes the departure, or the decision (D1 to D12) it waits on. none means nobody holds it yet.
  • Exit is what must be true before the row moves to Closed.
  • Check is what stops the row getting worse: a check id in scripts/arch-fitness.sh, or a test file. none means nothing holds it.
  • A change that removes a departure moves its row to Closed in the same merge request, with the reason.
  • A new row needs evidence that exists at the commit that adds it. No path, no row.
  • A departure that is ruled to stay moves to Accepted exceptions and names the ruling.
  • Do not start a second register. Add a row here.
IdRuleEvidenceLaneExitCheck
O-01One execution model: every runtime runs the stored render. Whole-project mode still runs a project with no stored render and refuses a later move by name.ce subsystems/impl/replica_projects.go:116; ce modules/pods/local.go:200; ce modules/health/reconcile/actions.go:198; docs/architecture/flows/render-once.md:32AS29, AS30RefuseWhole has no caller and render-once.md describes one model.none
O-02Backups take one source per input. Converters fall back to raw archives, and catalog backup contracts end steps with a shell or-true that hides a failure (69 lines in 15 backup.yaml files).ce modules/backup/converter.go:125; ce modules/backup/converter.go:452; ce modules/backup/archive.go:498; apps/flagship/matrix/backup.yaml:67AS22, AS23ce has no fallback archive path and no backup.yaml hides a failed step.none
O-03The deployment is the network. Tenant create still ensures a network per tenant.modules/tenant/create.go:154; ce modules/network/router.go:32; ce modules/tenant/service.go:109AS09, AS10Tenant create makes no network and the ensure_tenant route is gone.none
O-04The reconcile loop runs live passes only. It is still the Python port’s table of passes, some of them dead.ce modules/health/reconcile/actions.go:29; ce modules/health/reconcile/actions.go:464; ce modules/health/reconcile/actions.go:1457; ce core/config/default.yaml:1627AS10, AS37Dead passes are deleted and each live pass belongs to its module or its app package.none
O-05The enrol issuer belongs in shc. It lives in ce.ce modules/mesh/grant.go:86; ce modules/mesh/grant.go:154; ce modules/cluster/join_signer.go; daemon/wiring/wire_mesh.go:50AS47, AS48The issuer is in shc and ce keeps only what verifies a grant.none
O-07Estate forks in the catalog are unruled (D6). Hidden forks of ciso-assistant and Keycloak are published.apps/integrated/ciso/app.yaml:151; apps/integrated/multiplatform-keycloak/app.yaml:7D6, then AS58D6 is ruled. The forks leave the catalog, or this row moves to Accepted exceptions.none
O-08The canonical ciso-assistant package carries the trusted-proxies gap the sweep found. Its Caddy trusts every private range.apps/integrated/ciso-assistant/compose.yaml:357; apps/integrated/ciso/compose.yaml:357AS01The canonical package trusts only the edge.none
O-10Relocation is per replica, with no state on one node. The move journal is node-local.ce modules/clone/move_journal.go:18; ce modules/clone/replica_move.go:123AS31, AS32The journal is in the store, and drain and rebalance move replicas through one path.none
O-11Springboard is the only launcher. The menu-embed spine and the grid launcher still ship.modules/console/embed.go:62; traefik/plugin/menu_embed.go; traefik/plugin/menu_layout.go:68; ce modules/app/launcher_panel.go:10AS38, AS39, AS40The embed spine, the grid launcher and the launcher.panel key are gone.none
O-12The console calls the daemon; it does not copy its logic. Role vocabulary, backup timelines and launcher precedence are computed again in TypeScript.features/console/src/settings/sections/people/roleVocabulary.ts:6; features/console/src/stack/backups/timeline.ts:444; packages/apps-menu/src/launcher/precedence.ts:32; features/console/src/manage/catalog/ceEnums.tsAS41, AS42Each copy is replaced by a call and deleted.none
O-13Estate records do not live in ce. ce still carries an operations log.ce docs/ops/migration-intervention-log.mdAS02, AS56ce docs/ops holds no estate record.none
O-14A ratchet only tightens. Ceilings have been raised, and nothing stops the next raise.scripts/arch-fitness.sh:46; tests/unit/ci/go_skip_semantics_test.go:44AS03, AS28A raised ceiling fails CI unless the same change names the ruling.none
O-15CI runs an engine. No pipeline lane starts a container runtime, so engine paths are covered by unit tests alone..gitlab/ci/next-known-failures.txt:13; .gitlab/ci/next-test-inventory.txt:6; tests/collector/e2e_test.go:20AS28A CI lane installs and runs an app on a real engine.none
O-16forward-auth and the plugin read only their own sections. An absent section still selects a mode.forward-auth/cmd/forward-auth/section.go:11; traefik/plugin/authsection.go:9; forward-auth/cmd/forward-auth/main.go:243AS18, AS20An absent section is an error.none
O-17The plugin’s authGate is retired. The code is still there.traefik/plugin/auth.go:15; traefik/plugin/shcinject.go:163; ce modules/auth/forward_auth_gate.go:3; ce modules/traefik/compose.yaml:603AS19, AS20authGate and the old forward-auth contract are deleted.none
O-18The licence broker serves only live routes. The sweep found dead routes and the client methods behind them.license-broker/brokerd/server.go:18; license-broker/brokerd/server.go:48; modules/license/broker.go:161; modules/license/broker.go:290AS45The dead routes and their client methods are gone.none
O-19One collector fleet, installed like any app. Two collectors register as subsystems.subsystems/register.go:70; subsystems/collector_deployment.go:32; subsystems/collector_node.go; modules/collector/doc.goAS35One fleet is left and it installs through the app path.none
O-20The Keycloak overlay adds to ce’s package. Today it is a fork of it.Makefile:194; modules-overlay/keycloak/compose.yaml; tests/unit/catalog/keycloak_ldap_overlay_test.go:27AS36The overlay holds only its additions.none
O-21System apps come from one registry. Six lists name them.ce modules/app/system_apps.go:79; ce modules/app/system_plan.go:39; ce modules/health/reconcile/system_first.go:76; ce modules/capabilities/types.go:53; ce modules/app/system_image_gate.go:129; ce modules/app/commands/system_scheduler.go:60AS33Every list reads SystemAppSpecs.none
O-22Core holds no app knowledge. The engine finds system roles by app name.ce modules/fabric/policyinput.go:60; ce modules/fabric/ingress_pin.go:49; ce core/nodeports/edge.go:16; ce modules/containerbroker/observer.go:23; ce core/executor/prestart.go:139AS33A role comes from the registry, never from a name.tests/_ce/modules/app_neutral_test.go
O-23Core holds no app knowledge. Internals of Keycloak, OpenObserve and Traefik live in ce modules.ce modules/app/keycloak_basepath_reconcile.go; ce modules/app/openobserve_basepath_reconcile.go; ce modules/app/keycloak_admin_password.go; ce modules/auth/keycloak_admin.go; ce modules/app/inject_traefik.goAS37Each internal moves into its app package.tests/_ce/modules/app_neutral_test.go
O-24Core holds no app knowledge. shc runtime Go names system apps.subsystems/collector_deployment.go:32; modules/collector/desired.go:1393; modules/launcher/tiles.go:85; modules/supportbundle/certs.go:83; traefik/render/render.go:47AS33, AS35No app name is left in shc runtime Go outside the guard’s allow-list.tests/unit/ci/app_neutral_test.go
O-25An app’s image is built from its own package. The frappe image bakes the marketplace and billing URLs.frappe/docker/Dockerfile:584; frappe/docker/Dockerfile:676; apps/flagship/frappe/vars.yaml:720AS46The marketplace and the portal have their own packages and the bake is gone.none
O-26A licence feature that is sold is enforced. multi_provider is sold and nothing enforces it, and the quota and fleet gates are latent.modules/license/feature_kind.go:118; modules/license/feature_kind.go:227noneEach sold feature has a gate that refuses, or it stops being sold.none
O-27Public pages cite paths that exist. Landing pages still cite source paths from before the repo split.website/landing/arch/incident-replay/index.html:417; website/landing/arch/cert-rotation/index.html:342; website/landing/arch/event-river/index.html:7AS63No landing page cites a path that does not exist.none
O-28The testing standard describes the test backend. It never mentions dbtestreg.docs/contributing/standards/testing.md:6; testsupport/dbtestreg/register_sqlite.goAS60testing.md describes the cluster-parity driver.none
O-29The failure model for relocate and rename is unruled (D5). The durability doctrine is still a proposal.docs/decisions/2026-08-16-durability-not-sagas.md:3D5D5 is ruled and the decision page says so.none
O-30The running unit is a deployment. ce types and routes still say stack, and the vocabulary ruling’s scope over them is unruled (D2).ce modules/app/models.go:59; ce modules/stack/router.go:86; daemon/wiring/cluster_drain_placement.go:46; docs/architecture/patterns/cross-module.md:137D2, then AS52 to AS55D2 is ruled and the types, routes and text follow it.none
O-31ce runs a linter. Its lint target runs no golangci config.ce Makefile:58AS05ce has a golangci config and CI runs it.none
O-32No backwards compatibility. Retired spellings are still refused by name, and how long that lasts is unruled (D3).ce modules/fence/gone.go:35; ce core/selector/flags.go:12D3, then AS27D3 is ruled. The refusals get an end date or are deleted.none
O-33ce’s role, SSO and audit gates are unruled (D4). They gate by edition beyond the sanctioned exceptions.ce modules/user/role_gate.go:32; ce modules/app/sso_gate.go:24; ce modules/audit/router.go:148D4, then AS49D4 is ruled. Each gate is sanctioned or removed.none
O-34No backwards compatibility. Compat families for the v0.1.21 line are still in ce.ce modules/clusterfs/legacy.go:19; ce modules/app/backup_list_v0121.go; ce modules/pods/legacy_view.go; ce core/paths/registry_auth.go:8AS14, AS15, AS16The census is done and every family it finds is deleted.none
O-35Locators go through daemon.Services. ce has 597 func Set* and 42 func Current* package-level functions.ce modules/ca/register.go:32; ce modules/mesh/relay.go:288; ce modules/app/secrets_resolve.go:75; ce modules/app/dns_target.go:126; ce modules/app/inject_traefik.go:2277AS12Package-level locators are gone, or a ceiling that only falls pins them.ce-di-singletons, ce-di-runtime-families
O-36shc composes through one registry. It still uses package-level setters, and four import manifests are kept by hand.cmd/shcd/main.go:22; cmd/shc/main.go:53; scripts/docsgen_wiring_pin.go:35; scripts/apiclientgen_wiring_pin.go:14AS03 for the setters, none for the manifestsThe four manifests are generated from one list or checked against each other.di-singletons, di-runtime-families
O-37Doctrine pages match the decisions. The engineering standards call the ADR-0002 manifest a read-through cache and the ADR does not.docs/contributing/engineering-standards.md:337; docs/decisions/ADR-0002-stack-state-manifest-model.md:48AS07The standards page uses the ADR’s wording.none
O-38ce’s public import path is unruled (D8). ce’s module path names the bitspur group and shc imports it by that path.go.mod:8D8, then AS56, AS57D8 is ruled and both repos use the public path.none
O-39Old-line CI and packaging leave main. The Makefile keeps a stub for a moved target, one script is bash, and BAD_RELEASES lists old-line versions.Makefile:1672; scripts/cutover-cicd-node-vars.sh:1; BAD_RELEASES:214AS24The stub, the bash script and the old-line entries are gone.none
O-40A warning carries a code. ce logs uncoded warnings through the raw logger.ce core/config/watch.go:162; ce daemon/daemon.go:1210; ce modules/forward/router.go:116; ce cli/forward_wiring.go:211; ce modules/storage/shared_manager.go:364noneEach site logs a coded warning.none
O-41One logger entry point. ce still calls slog.Default() and imports the typed logger under more than one alias.ce daemon/services_seams_health.go:398; scripts/arch-fitness.sh:800noneBoth ceilings reach zero.ce-slog-default, ce-corelog-import-alias
O-42A router resolves its service per request. The app and backup routers bind theirs when the router is built.ce modules/app/register.go:124; ce modules/backup/register.go:58noneBoth routers resolve per request.none
O-43One route, one method. Backup registers shc.backup.schedule.list as GET and as POST.ce modules/backup/router.go:383noneOne method is left.none
O-44Subsystem order has one source. Priority and deps can disagree, and priorityGroups groups by priority alone.ce subsystems/impl/collectors.go:68; ce subsystems/lifecycle/topo.go:113noneOrder comes from deps alone, or a check proves the two agree.none
O-45Modules have one shape. Resolver helpers, router constructors, register files and core type names differ from module to module.ce modules/metrics/register.go:77; ce modules/tenant/register.go:63; ce modules/user/router.go:106; ce modules/tenant/router.go:38; ce modules/operation/router.go:23; ce modules/sysroutes/router.go:36; ce modules/backup/mount/register.go; ce modules/forward/register.go:16; ce modules/ca/store.go:159; ce modules/portforward/router.go:1noneThe layout rules in O-48 are wired and pass.none
O-46Shared parsing has one copy. The socket candidate list, the scope synonym table and the adapter installer each have more than one.ce core/daemonclient/client.go:61; ce modules/config/types.go:25; ce modules/vault/register.go:117; ce modules/config/state.go:8; ce modules/backup/state.go:12noneOne shared parser and one installer helper are left.ce-dup-socket-candidates
O-47Migration prose goes when the migration is done. composition.go still describes waves.ce daemon/composition.go:65noneThe wave comments are deleted.none
O-48A pending fitness rule is wired or struck. Sixteen rules in section C of the drift record are still prose.docs/reviews/2026-08-18-drift-register.md:721; scripts/arch-fitness.sh:615AS03, AS04Each rule is a check id in scripts/arch-fitness.sh or is struck with a reason.none
O-49A registry setter has callers or is deleted. registry.Migrations has none, and MigrationsAll is still read.ce core/registry/registry.go:40; ce core/registry/registry.go:179; ce daemon/newer_store.go:42; ce subsystems/impl/migrations.go:90noneThe setter is deleted or a module calls it.none
O-50Shared code has one home. packages/apps-menu is really the daemon client plus sign-in, and the store and the portal pull it in for that.packages/apps-menu/src/index.ts:2none, after AS42The daemon client and sign-in are their own package.none
O-51An app’s sidecar and image sources live with the app. Four sit at the repo root.mailcow-apppass/go.mod:5; mailcow-config/docker/Dockerfile; credential-broker/README.md; bridges/monica-nextcloud/pyproject.tomlnoneEach source sits under the app that uses it.none
O-52Python is formatted, typed and locked. Satellite Python has no black, no basedpyright and no uv lock.frappe/apps/marketplace/pyproject.toml; frappe/apps/portal/pyproject.toml; bridges/monica-nextcloud/pyproject.tomlnoneEach satellite has the tool config and a lock file.none
O-53Every Go module is linted and returns coded errors. The mobile/ modules sit outside golangci and return uncoded errors.mobile/hudapp/auth.go:38; mobile/hudkit/hudkit.go:79; mobile/hudapp/go.mod:3none, after D10D10 is ruled and the module that stays is linted.none
O-54One API client per cloud. Each capability tree has its own client for the same cloud.ce modules/dns/providers/hetzner/provider.go:62; ce modules/proxy/providers/hcloudlb/client.go:29; ce modules/storage/providers/hcloud/client.go:14; ce modules/proxy/providers/cloud/cloud.go:6noneThe capability trees of one cloud share one client.none
O-55Scheduling and autoscaling follow the ruled design, scheduler.md (FZ-10588): one quota per service, request and limit as percentages of it, and a replica that fits nowhere pending with its ask. None of it is built. Placement zeroes the request it derives from an app’s own limit, a limit renders at 1.5x the quota, a service that authors nothing runs uncapped, and an install with no room is held with an expiry instead.docs/architecture/scheduler.md; ce modules/app/replica_projects.go:524-531; ce modules/app/resource_quota.go:203; ce modules/app/resource_quota.go:504-506; ce modules/capacity/capacity.go:33-35FZ-10622 to FZ-10628Requests count in the fit, the percentage keys replace the ratio keys, and a replica with no room is pending with its ask and no expiry.none
IdExceptionEvidenceWhy it staysCheck
A-01The allow-lists of the two app-neutral guards. What is left names image sources and tests, not runtime code.tests/unit/ci/app_neutral_test.go:65; tests/_ce/modules/app_neutral_test.go:65Core holds no app knowledge, and the guards are how that is held. The lists can only shrink.tests/unit/ci/app_neutral_test.go, tests/_ce/modules/app_neutral_test.go
A-02The seat cap. ce counts seats for the edition.ce modules/user/seat_limit.go:79Sanctioned by the ce and ee split doctrine.none
A-03The system-image gate.ce modules/app/system_image_gate.go:129Sanctioned by the ce and ee split doctrine.none
A-04Fence is the internal name of the placement primitive. Its routes say label, constraint and selector.ce modules/fence/router.go:23; ce ent/schema/fence.go:25An internal name is not vocabulary an operator sees.none
A-05Swarm vocabulary in a compose file is translated. The deploy keys are read and mapped to the runtime.ce core/composegpu/gpu.go:25Translate, don’t refuse.none
A-06Old-line import code stays until the bitspur migration ends.ce modules/app/vdeployment_dir_migration.go; ce modules/adapter/commands/migrate_from.go:57; ce modules/adapter/adapters/shc/shc.go:521One estate is still on the old line and needs it to move. Lane AS64 deletes it afterwards.none
A-07Layers 0 and 1 wait on the edge deployment. A node that is not a member, or whose mesh is down, joins through Traefik on 443 at /api/join/, and that route serves only the functions on a list.ce modules/underlay/rpc.go:83; ce modules/mesh/peer_table_client.go:82; ce modules/internal_rpc/join.go:42Ruled by D1: the edge is the one dependency layers 0 to 4 may have on a deployment, and every node joins through it.tests/unit/ci/join_surface_test.go
IdRowWhy it is closed
C-01Legacy record 1.1: Terraform provider state upgraders for presets.The files are gone. No state_upgrade file is left under terraform/provider/internal/provider.
C-02Legacy record 6: SCIM was sold in TIERS.md and did not exist.The claim was struck from TIERS.md by FZ-8730 (d66cdddea9).
C-03Legacy record 6: shc cluster repair --force had no implementer.shc wires one at subsystems/rqlite_engine.go:1712, implemented in subsystems/rqlite_recoverer.go:38.
C-04App-specific record, section E: the mailcow exception.Removed by SHC-3507 on 2026-10-18. ce has no mailcow template code left. What is accepted today is A-01.
C-05The “Superseded by Core” pointer at the top of three registers.It pointed at a page that does not replace them. Those three records now point at this page.
C-06Drift record: the header counted 67 open rows and the body had 64.The record is frozen. This page is counted by its rows.
C-07Drift record rows 355 and 359 to 362: stale claims in the B3 and B7 decision pages.Those pages are archived under docs/handoff/archive. A dated record is not corrected. Row 354 is carried as O-49.
C-08Drift record rows 427 and 429: the generated reference was stale and the CLI reference was not reproducible.scripts/regen-check.sh regenerates the corpus, the CLI tree included, in every merge request pipeline and fails on a difference.
C-09Drift record row 817: swap headroom for the Proxmox rig.tests/proxmox is gone.
C-10Drift record row 851: the cluster_state check had landed on one side only.Both sides carry ck_node_cluster_state_valid: ce ent/schema/node.go:27 and ce ent/migrate/schema.go:3062.
C-11Next-waves record: move ce’s tests out of ce.Done. They live in tests/_ce.
C-12Drift record rows 525, 564, 590, 600, 610, 619, 620, 810 and 826.Not measured again on 2026-11-11, so not carried. Reopen one with a path that exists today if it still holds.
C-13Every other row of the five records.Not found again by the 2026-11 sweep. The records keep them.
C-14O-09: Gating is binary: public or not. Apps still declared ungated_paths, and only two carve-outs are approved (D7).Removed by AS59 (shc !6086, !6088). Only docuseal (/s/) and paperless (/accounts/login) may declare ungated_paths, and tests/unit/catalog/public_or_gated_test.go:75 fails the unit job on any other app.

The sweep looked at these and found them intended. Do not add rows for them.

  • Edition wording in ce.
  • The layout of adapters/shc.
  • website/landing-archive, the frozen landing archive.
  • Educates (SHC-2819).
  • Traefik’s global mode.
  • The store’s disarmed install dispatch.

The five registers this page replaced, as they stood on their dates.

  • Legacy register, 2026-08-18
  • Architecture drift register, 2026-08-18
  • App-specific register, 2026-08-18
  • Next-wave plans, 2026-06-22
  • Legacy and breaking changes, 2026-08-05