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.
How to read a row
Section titled “How to read a row”- 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
cein front is in the ce repo at the commitgo.modpins. Every other path is in this repo. - Lane is the batch of the 2026-11 architecture sweep (
AS01toAS64, FZ-10491) that removes the departure, or the decision (D1toD12) it waits on.nonemeans 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.nonemeans nothing holds it.
Keeping it live
Section titled “Keeping it live”- 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.
| Id | Rule | Evidence | Lane | Exit | Check |
|---|---|---|---|---|---|
| O-01 | One 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:32 | AS29, AS30 | RefuseWhole has no caller and render-once.md describes one model. | none |
| O-02 | Backups 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:67 | AS22, AS23 | ce has no fallback archive path and no backup.yaml hides a failed step. | none |
| O-03 | The 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:109 | AS09, AS10 | Tenant create makes no network and the ensure_tenant route is gone. | none |
| O-04 | The 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:1627 | AS10, AS37 | Dead passes are deleted and each live pass belongs to its module or its app package. | none |
| O-05 | The 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:50 | AS47, AS48 | The issuer is in shc and ce keeps only what verifies a grant. | none |
| O-07 | Estate 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:7 | D6, then AS58 | D6 is ruled. The forks leave the catalog, or this row moves to Accepted exceptions. | none |
| O-08 | The 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:357 | AS01 | The canonical package trusts only the edge. | none |
| O-10 | Relocation 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:123 | AS31, AS32 | The journal is in the store, and drain and rebalance move replicas through one path. | none |
| O-11 | Springboard 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:10 | AS38, AS39, AS40 | The embed spine, the grid launcher and the launcher.panel key are gone. | none |
| O-12 | The 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.ts | AS41, AS42 | Each copy is replaced by a call and deleted. | none |
| O-13 | Estate records do not live in ce. ce still carries an operations log. | ce docs/ops/migration-intervention-log.md | AS02, AS56 | ce docs/ops holds no estate record. | none |
| O-14 | A 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:44 | AS03, AS28 | A raised ceiling fails CI unless the same change names the ruling. | none |
| O-15 | CI 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:20 | AS28 | A CI lane installs and runs an app on a real engine. | none |
| O-16 | forward-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:243 | AS18, AS20 | An absent section is an error. | none |
| O-17 | The 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:603 | AS19, AS20 | authGate and the old forward-auth contract are deleted. | none |
| O-18 | The 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:290 | AS45 | The dead routes and their client methods are gone. | none |
| O-19 | One 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.go | AS35 | One fleet is left and it installs through the app path. | none |
| O-20 | The 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:27 | AS36 | The overlay holds only its additions. | none |
| O-21 | System 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:60 | AS33 | Every list reads SystemAppSpecs. | none |
| O-22 | Core 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:139 | AS33 | A role comes from the registry, never from a name. | tests/_ce/modules/app_neutral_test.go |
| O-23 | Core 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.go | AS37 | Each internal moves into its app package. | tests/_ce/modules/app_neutral_test.go |
| O-24 | Core 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:47 | AS33, AS35 | No app name is left in shc runtime Go outside the guard’s allow-list. | tests/unit/ci/app_neutral_test.go |
| O-25 | An 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:720 | AS46 | The marketplace and the portal have their own packages and the bake is gone. | none |
| O-26 | A 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:227 | none | Each sold feature has a gate that refuses, or it stops being sold. | none |
| O-27 | Public 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:7 | AS63 | No landing page cites a path that does not exist. | none |
| O-28 | The testing standard describes the test backend. It never mentions dbtestreg. | docs/contributing/standards/testing.md:6; testsupport/dbtestreg/register_sqlite.go | AS60 | testing.md describes the cluster-parity driver. | none |
| O-29 | The 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:3 | D5 | D5 is ruled and the decision page says so. | none |
| O-30 | The 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:137 | D2, then AS52 to AS55 | D2 is ruled and the types, routes and text follow it. | none |
| O-31 | ce runs a linter. Its lint target runs no golangci config. | ce Makefile:58 | AS05 | ce has a golangci config and CI runs it. | none |
| O-32 | No 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:12 | D3, then AS27 | D3 is ruled. The refusals get an end date or are deleted. | none |
| O-33 | ce’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:148 | D4, then AS49 | D4 is ruled. Each gate is sanctioned or removed. | none |
| O-34 | No 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:8 | AS14, AS15, AS16 | The census is done and every family it finds is deleted. | none |
| O-35 | Locators 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:2277 | AS12 | Package-level locators are gone, or a ceiling that only falls pins them. | ce-di-singletons, ce-di-runtime-families |
| O-36 | shc 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:14 | AS03 for the setters, none for the manifests | The four manifests are generated from one list or checked against each other. | di-singletons, di-runtime-families |
| O-37 | Doctrine 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:48 | AS07 | The standards page uses the ADR’s wording. | none |
| O-38 | ce’s public import path is unruled (D8). ce’s module path names the bitspur group and shc imports it by that path. | go.mod:8 | D8, then AS56, AS57 | D8 is ruled and both repos use the public path. | none |
| O-39 | Old-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:214 | AS24 | The stub, the bash script and the old-line entries are gone. | none |
| O-40 | A 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:364 | none | Each site logs a coded warning. | none |
| O-41 | One 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:800 | none | Both ceilings reach zero. | ce-slog-default, ce-corelog-import-alias |
| O-42 | A 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:58 | none | Both routers resolve per request. | none |
| O-43 | One route, one method. Backup registers shc.backup.schedule.list as GET and as POST. | ce modules/backup/router.go:383 | none | One method is left. | none |
| O-44 | Subsystem 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:113 | none | Order comes from deps alone, or a check proves the two agree. | none |
| O-45 | Modules 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:1 | none | The layout rules in O-48 are wired and pass. | none |
| O-46 | Shared 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:12 | none | One shared parser and one installer helper are left. | ce-dup-socket-candidates |
| O-47 | Migration prose goes when the migration is done. composition.go still describes waves. | ce daemon/composition.go:65 | none | The wave comments are deleted. | none |
| O-48 | A 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:615 | AS03, AS04 | Each rule is a check id in scripts/arch-fitness.sh or is struck with a reason. | none |
| O-49 | A 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:90 | none | The setter is deleted or a module calls it. | none |
| O-50 | Shared 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:2 | none, after AS42 | The daemon client and sign-in are their own package. | none |
| O-51 | An 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.toml | none | Each source sits under the app that uses it. | none |
| O-52 | Python 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.toml | none | Each satellite has the tool config and a lock file. | none |
| O-53 | Every 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:3 | none, after D10 | D10 is ruled and the module that stays is linted. | none |
| O-54 | One 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:6 | none | The capability trees of one cloud share one client. | none |
| O-55 | Scheduling 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-35 | FZ-10622 to FZ-10628 | Requests 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 |
Accepted exceptions
Section titled “Accepted exceptions”| Id | Exception | Evidence | Why it stays | Check |
|---|---|---|---|---|
| A-01 | The 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:65 | Core 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-02 | The seat cap. ce counts seats for the edition. | ce modules/user/seat_limit.go:79 | Sanctioned by the ce and ee split doctrine. | none |
| A-03 | The system-image gate. | ce modules/app/system_image_gate.go:129 | Sanctioned by the ce and ee split doctrine. | none |
| A-04 | Fence 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:25 | An internal name is not vocabulary an operator sees. | none |
| A-05 | Swarm vocabulary in a compose file is translated. The deploy keys are read and mapped to the runtime. | ce core/composegpu/gpu.go:25 | Translate, don’t refuse. | none |
| A-06 | Old-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:521 | One estate is still on the old line and needs it to move. Lane AS64 deletes it afterwards. | none |
| A-07 | Layers 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:42 | Ruled 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 |
Closed
Section titled “Closed”| Id | Row | Why it is closed |
|---|---|---|
| C-01 | Legacy 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-02 | Legacy record 6: SCIM was sold in TIERS.md and did not exist. | The claim was struck from TIERS.md by FZ-8730 (d66cdddea9). |
| C-03 | Legacy 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-04 | App-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-05 | The “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-06 | Drift record: the header counted 67 open rows and the body had 64. | The record is frozen. This page is counted by its rows. |
| C-07 | Drift 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-08 | Drift 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-09 | Drift record row 817: swap headroom for the Proxmox rig. | tests/proxmox is gone. |
| C-10 | Drift 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-11 | Next-waves record: move ce’s tests out of ce. | Done. They live in tests/_ce. |
| C-12 | Drift 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-13 | Every other row of the five records. | Not found again by the 2026-11 sweep. The records keep them. |
| C-14 | O-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. |
Not registered
Section titled “Not registered”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.
Records
Section titled “Records”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
shc@docs:~$