Architecture · LikeC4
gas-city-dashboard
Single-operator ambient cockpit over one Gas City — calm by default, raises its voice only when something is wrong
The whole picture
System landscape
The system in context, then opened up into its containers.
gas-city-dashboard — system landscape
index
gas-city-dashboard — containers (backend / frontend / shared)
dashboardSystemSingle-operator ambient cockpit over one Gas City — calm by default, raises its voice only when something is wrong
Risks & open questions
risks
Opt-in & planned work — the Maintainer (Triage) module
plannedInside each box
Containers & components
Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.
Backend (Node/Express) — components
backendContainerBinds 127.0.0.1 only. Owns local host capabilities + a transport-only supervisor relay; never a GC data facade.
Frontend (React/Vite) — components
frontendContainerfrontend/ — React 19 + Vite + Tailwind. Reads GC data directly from the supervisor; the calm "Reading Room" register is the binding visual contract (DESIGN.md)
shared — the wire-shape SSOT contract
sharedContainershared/ — dashboard-owned /api DTOs + the generated gc-supervisor OpenAPI client; the single contract both halves import
How it runs
Walkthrough flows
Dynamic views — the narrative spine of the system, step by step.
Walkthrough — SPA bootstrap to first paint
bootThe SPA loads from the same origin, reads /api/config for operator identity + enabled modules + read-only posture, then reads GC data straight from the supervisor through the transport relay.
Walkthrough — live update over SSE
liveUpdateThe SPA holds an EventSource directly on the supervisor stream. A burst of bead/session events is coalesced (leading + trailing) into at most one refresh per window, which re-reads through the cache so the connection pool stays free.
Walkthrough — an operator write (bead / mail)
operatorWriteMutations carry the X-GC-Request header and clear the Origin check + CSRF gate. Mail sends always go from the operator identity even while "Reading as" another agent — impersonation is read-only.
Walkthrough — run git diff (local evidence)
runDiffRun-detail git diffs are a dashboard-owned local capability, not GC data. The execution-folder cwd comes from untrusted supervisor run metadata, so it is confined to the RUN_CWD_ALLOWED_ROOTS prefix allowlist before git -C runs.
Where it runs
Deployment
What runs where, and the process & data boundaries between the pieces.
Deployment — where each piece runs (loopback-only backend)
deploymentExplore it live
The figures above are static exports. The interactive explorer lets you pan, zoom, follow relationships, and jump from any box to the source.