Skip to content
SHC Docs

Mesh Architecture Diagrams

Layer 1. Mesh. Mesh

Detailed architecture diagrams for the SHC cluster mesh.

interactive: drag/click to explore
planewhatport
mesh0node plane (raft, internal API, VIPs):4244
shc0container fabric:4243
raft / internal apiride mesh0 on next:4002 / :4003

See Two WireGuard tunnels.

graph TB
subgraph EXTERNAL["External Network"]
INTERNET[Internet Traffic]
DNS[DNS Provider]
end
subgraph MESH0["mesh0 (10.192.0.0/10)"]
subgraph NODE1["Node 1"]
direction TB
TRAEFIK1["Traefik<br/>:443/:80"]
SHC1["SHC Server<br/>:8000 (public)<br/>:4003 (internal)"]
RQLITE1["rqlited<br/>:4002"]
M1["mesh0<br/>UDP :4244"]
APPS1["User Containers"]
end
subgraph NODE2["Node 2"]
direction TB
TRAEFIK2["Traefik<br/>:443/:80"]
SHC2["SHC Server<br/>:8000 (public)<br/>:4003 (internal)"]
RQLITE2["rqlited<br/>:4002"]
M2["mesh0<br/>UDP :4244"]
APPS2["User Containers"]
end
subgraph NODE3["Node 3"]
direction TB
SHC3["SHC Server<br/>:8000 (public)<br/>:4003 (internal)"]
RQLITE3["rqlited<br/>:4002"]
M3["mesh0<br/>UDP :4244"]
APPS3["User Containers"]
end
end
INTERNET --> TRAEFIK1
INTERNET --> TRAEFIK2
DNS <-.-> TRAEFIK1
DNS <-.-> TRAEFIK2
M1 <--> M2
M2 <--> M3
M1 <--> M3
RQLITE1 <--> RQLITE2
RQLITE1 <--> RQLITE3
SHC1 <-->|"Internal API"| SHC2
SHC2 <-->|"Internal API"| SHC3
SHC1 <-->|"Internal API"| SHC3
classDef external fill:#ffebee,stroke:#c62828
classDef mesh fill:#e1f5fe,stroke:#01579b
classDef node fill:#fff3e0,stroke:#e65100
class EXTERNAL external
class MESH0 mesh
class NODE1,NODE2,NODE3 node
flowchart LR
P443["443/tcp: HTTPS ingress and enrolment"] --> PUBLIC["Public entrypoint through Traefik"]
P80["80/tcp: HTTP redirect"] --> PUBLIC
P4244["4244/udp: mesh0"] --> UNDERLAY["Between node underlay addresses"]
P4243["4243/udp: shc0"] --> UNDERLAY
P4001["4001/tcp: rqlite API"] --> MESH["Node mesh0 addresses"]
P4002["4002/tcp: rqlite raft"] --> MESH
P4003["4003/tcp: internal API, mTLS"] --> MESH

Source: Two WireGuard tunnels, sections 2, 7 and 13. Each tunnel dials the underlay independently.

sequenceDiagram
participant CLI as CLI/API Client
participant API as SHC API
participant QM as Quorum Middleware
participant DB as rqlite Cluster
participant RAFT as Raft Consensus
CLI->>API: Write Request
API->>QM: Check quorum
alt Quorum Lost
QM-->>API: 503 Quorum Lost
API-->>CLI: Error: Cluster degraded
else Quorum OK
QM-->>API: Proceed
API->>DB: Execute write
DB->>RAFT: Replicate to voters
RAFT-->>DB: Consensus achieved
DB-->>API: Success
API-->>CLI: 200 OK
end
flowchart LR
subgraph CLIENT
CLI[CLI/Browser]
end
subgraph NODE["Any Node"]
API[SHC API]
LOCAL_DB[Local rqlited]
end
CLI -->|request| API
API -->|read| LOCAL_DB
LOCAL_DB -->|data| API
API -->|response| CLI
style NODE fill:#e3f2fd,stroke:#1565c0
flowchart TB
subgraph SOURCES["Event Sources"]
DOCKER[Docker Events]
AUDIT[Audit Log]
DEPLOY[Deployments]
end
subgraph BROKER["SSE Broker"]
CHANNELS["Channels<br/>events:{tenant}<br/>errors:{tenant}<br/>operation:{tenant}:{id}"]
BUFFER["Ring Buffer<br/>(1000 events/channel)"]
DEDUP["Deduplication<br/>(MD5 hash)"]
end
subgraph CROSS_NODE["Cross-Node Broadcast"]
BROADCASTER[NodeBroadcaster]
INTERNAL_API[Internal API :4003]
end
subgraph CLIENTS["Subscribers"]
WEB[Web Dashboard]
CLI[CLI --follow]
TRACKER[DeploymentTracker]
end
DOCKER --> DEDUP
AUDIT --> DEDUP
DEPLOY --> DEDUP
DEDUP --> CHANNELS
CHANNELS --> BUFFER
CHANNELS --> BROADCASTER
BROADCASTER --> INTERNAL_API
INTERNAL_API --> CHANNELS
BUFFER --> WEB
BUFFER --> CLI
BUFFER --> TRACKER
classDef source fill:#fff3e0,stroke:#e65100
classDef broker fill:#e8f5e9,stroke:#2e7d32
classDef crossnode fill:#f3e5f5,stroke:#7b1fa2
classDef client fill:#e3f2fd,stroke:#1565c0
class SOURCES source
class BROKER broker
class CROSS_NODE crossnode
class CLIENTS client

Each node generates its own mesh0 WireGuard key pair. Only the public key leaves the node. The leader signs the peer table, and shcd reconciles mesh0 from membership (CE modules/mesh/mesh.go, snapshot_sign.go and repo.go).

flowchart TB
NODE["Node: local WireGuard key pair"]
ROW["mesh_peer: node id, public key, mesh address"]
LEADER["Leader signs peer table"]
TABLE["Signed membership snapshot"]
DEVICE["shcd reconciles mesh0 peers"]
LEAVE["Leave: tombstone mesh_peer row"]
NODE -->|public key at enrol| ROW
ROW --> LEADER
LEADER --> TABLE
TABLE --> DEVICE
LEAVE --> ROW

Only joiners with the voter host capability and control-plane membership can receive voter slots. A Mac joins as a non-voter. Members are keyed by the string node id in {state}/node.id; this diagram shows the voters:

flowchart TB
subgraph RQLITE["rqlite Cluster"]
subgraph VOTERS["Voting Nodes"]
V1["rqlited-1<br/>(Leader)"]
V2["rqlited-2"]
V3["rqlited-3"]
end
end
V1 <-->|"Raft :4002"| V2
V2 <-->|"Raft :4002"| V3
V1 <-->|"Raft :4002"| V3
WRITE[Write Request] --> V1
READ1[Read Request] --> V2
READ2[Read Request] --> V3
classDef leader fill:#c8e6c9,stroke:#2e7d32,stroke-width:3px
classDef voter fill:#e3f2fd,stroke:#1565c0
classDef request fill:#ffebee,stroke:#c62828
class V1 leader
class V2,V3 voter
class WRITE,READ1,READ2 request
flowchart TB
subgraph INTERNET["Internet (Untrusted)"]
ATTACKER[External Traffic]
end
subgraph FIREWALL["Firewall / Cloud Security Group"]
ALLOWED["Allowed:<br/>443/tcp (HTTPS)<br/>80/tcp (HTTP)<br/>4244/udp (mesh0)<br/>4243/udp (shc0)"]
end
subgraph MESH["mesh0: node plane"]
MESH_AUTH["WireGuard public key in mesh_peer"]
RQLITE["rqlite :4001/:4002"]
INTERNAL["Internal API :4003 (mTLS)"]
MESH_AUTH --> RQLITE
MESH_AUTH --> INTERNAL
end
subgraph FABRIC["shc0: container fabric"]
APPS["User Applications"]
end
DOCKER["Docker Socket: local only"]
ATTACKER -->|blocked| RQLITE
ATTACKER -->|blocked| INTERNAL
ATTACKER -->|blocked| DOCKER
ATTACKER -->|443, 80| ALLOWED
ATTACKER -->|4244/udp, 4243/udp| ALLOWED
ALLOWED -->|4244/udp| MESH
ALLOWED -->|4243/udp| FABRIC
classDef untrusted fill:#ffcdd2,stroke:#c62828
classDef firewall fill:#fff9c4,stroke:#f57f17
classDef trusted fill:#c8e6c9,stroke:#2e7d32
classDef internal fill:#e3f2fd,stroke:#1565c0
class INTERNET untrusted
class FIREWALL firewall
class MESH trusted
class MESH_AUTH,RQLITE,INTERNAL,APPS internal