Diagrams
Layer 2. Core. Core
The current diagrams are the mermaid in ../flows/ and ../layers/.
Mermaid source (.mmd) for every architectural diagram, plus rendered
SVGs for the status / health / reconciliation flows where a static
image is referenced from prose pages. The numbering reflects
reading order, not file-system order.
To re-render SVGs from Mermaid source, use the Mermaid CLI:
npx --yes @mermaid-js/mermaid-cli -i 1-container-status-derivation.mmd -o 1-container-status-derivation.svgStatus & health derivation
Section titled “Status & health derivation”How SHC turns raw Docker signals into SHC-level status and health
states. Rendered SVGs are checked in because these are referenced from
../status-states.md.
- 1: Container status derivation (
.svg): Docker state / health → SHC container status. - 2: Service status derivation (
.svg): aggregate of container statuses within a service. - 3: Service health derivation (
.svg): aggregate of container health within a service. - 4: Deployment status derivation (
.svg): event inputs + service-status aggregate → deployment status. - 5: Deployment health derivation (
.svg): aggregate of service healths → deployment health. - 6: Reconciliation decision (
.svg): when the health reconciler (cemodules/health/reconcile) brings a degraded deployment up and when it leaves it alone.
Event flow
Section titled “Event flow”- 7: Event flow (
.svg): Docker events → ingest → internal fan-out → SSE subscribers. - 10: Event propagation: how a Docker event on one node reaches subscribers on peer nodes.
- 15: Runtime registration:
sequence showing
main.gowiringctx,log, the registry, event bus, queue, and per-module task handlers at startup. Related: patterns/import-dag.
Cluster & topology
Section titled “Cluster & topology”- 8: High-level architecture: the whole system at a glance: internet → mesh0 → node daemons → Docker.
- 13: Cluster topology: voting quorum vs. client nodes, leader/voter roles, overlay addressing.
Leader election is owned by Raft (the rqlite engine); SHC’s
leader_hub subsystem polls the Raft leadership status and fans out
leader-only callbacks. See
core/daemon-manager.md.
Cross-node exec
Section titled “Cross-node exec”- 12: WebSocket exec: how
shc execon node A tunnels into a container on node B.
A service name resolves to one virtual IP (modules/vip/store.go on the
pinned ce module).
Import DAG & dependency structure
Section titled “Import DAG & dependency structure”Referenced from ../patterns/import-dag.md.
When you change the dependency structure of core modules, update the
.mmd source here and re-render.
- 14: Import architecture: the
package dependency graph from
core/scope/andcore/coded/at the bottom up to the modules. - 16: Cycle elimination: before/ after comparison of each circular dependency that was unwound.