Architecture

How SHC works internally. Audience: anyone who wants to understand the design — new contributors, operators debugging production, or app authors building against SHC’s contracts.

For the coding bar applied to these internals, see ../contributing/. For a flat reference, see ../reference/.

---

The whole product, mapped.

• Feature graph — every feature × every surface (CLI/API/HUD/daemon/db/events/config/app-schema/errors/docs); generated from feature-graph.yaml, the machine-checkable source of truth, hand-refreshed directly against HEAD

The backbone of the system.

• Overview — top-level architecture at a glance
• Tech stack — Go, chi, SQLite/rqlite, Atlas, Docker, etc.
• Data model — tenant, environment, stack, deployment, service, container
• Deployment identity — composite keys and identity resolution
• Networking — Docker networks, Traefik, ingress
• Daemon manager — subsystem lifecycle, leader election, fail-fast

• Security model — authentication, authorization, tenant isolation, mTLS, secrets

Step-by-step traces of multi-stage pipelines. Each page cites source files and line numbers so it stays grounded as the code evolves.

• install — 16-step install with rollback contract
• upgrade — snapshot → apply → revert-on-failure
• uninstall — best-effort forward pass + ordered multi-stack
• backup-restore — restic / local .bak / restore pipeline
• clone-move — shared 8-phase pipeline + rename fast path
• cluster-join — token bootstrap → mesh membership
• event-lifecycle — Docker / audit event → SSE subscriber

See the flows index for the full list.

Each domain-owned subsystem lives under modules/ in the pinned ce module, with the ee-only modules (and ee overlays of shared ones) under this repo’s modules/.

Core subsystems:

• app, stack, job, task
• events, audit, logs
• cluster, repo, clone
• backup, node, vault
• quota, schedule, storage, notification

Supporting subsystems:

• config, ctx, tenant
• dns, docker, nebula, network
• export, search, retention
• leader, health

Tooling subsystems:

• completion, doctor, forward
• hud, inspect, metrics
• shell

The real-time layer.

• Event bus — internal pub/sub
• Live service tracking — real-time deployment progress
• Job registration — how jobs surface to the UI

Multi-node topology.

• Cluster overview — mesh, roles, membership
• Cluster diagrams — detailed Mermaid diagrams
• DNS + HTTPS — how services are exposed
• DNS provider sync — external DNS integration
• Network fabric (design) — proposed routed-WireGuard cross-node fabric; multi-node Podman + swarm-less Docker

• Telemetry fabric (design) — proposed per-node collector fabric: container logs, app traces and metrics, scope enrichment, always-on scrub, operator filtering, scoped provider routing, and the support bundle it enables

Cross-cutting design patterns.

• Communication patterns — the six CLI↔server patterns
• Cross-module interactions — how modules talk to each other
• Import DAG — avoiding import cycles
• Docker file operations — safe cp/mv inside containers

• Status states — derivation at each layer, reconciliation decisions
• Diagrams — rendered Mermaid / SVG for status, events, topology