Mesh Architecture Diagrams
Layer 1. Mesh. Mesh
Detailed architecture diagrams for the SHC cluster mesh.
What rides where
Section titled “What rides where”| plane | what | port |
|---|---|---|
| mesh0 | node plane (raft, internal API, VIPs) | :4244 |
| shc0 | container fabric | :4243 |
| raft / internal api | ride mesh0 on next | :4002 / :4003 |
System Overview
Section titled “System Overview”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 nodeComponent Communication Matrix
Section titled “Component Communication Matrix”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"] --> MESHSource: Two WireGuard tunnels, sections 2, 7 and 13. Each tunnel dials the underlay independently.
Data Flow Patterns
Section titled “Data Flow Patterns”Write Operations
Section titled “Write Operations”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 endRead Operations
Section titled “Read Operations”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:#1565c0SSE Event Architecture
Section titled “SSE Event Architecture”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 clientMesh identity
Section titled “Mesh identity”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 --> ROWrqlite Cluster Topology
Section titled “rqlite Cluster Topology”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 requestSecurity Boundaries
Section titled “Security Boundaries”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 internalshc@docs:~$