Architecture · LikeC4
Cross-Repo Invariant Verifier
Loads declarative invariants, verifies them fleet-wide via Sourcegraph, emits a strict-JSON report, exit-code gated
The whole picture
System landscape
The system in context, then opened up into its containers.
Invariant Verifier — system landscape
index
Verifier — containers (Node CLI + config + CI harness)
verifierSystemLoads declarative invariants, verifies them fleet-wide via Sourcegraph, emits a strict-JSON report, exit-code gated
Risks & open questions
risks
Opt-in & superseded paths
plannedInside each box
Containers & components
Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.
Verifier (Node CLI, src/) — components
appContainersrc/ — entrypoint → engine → Sourcegraph client → JSON report; modes cli/ci are behaviorally identical
InvariantEngine — isolation, assertions, canary guard
engineViewLoads + Zod-validates invariants, runs each with per-invariant isolation at bounded concurrency (4); one failure never blocks the others
CI harness — workflows, trust boundary, notify
ciContainer.github/workflows/ + scripts/ — wraps the Node CLI with triggers, the trust boundary, the gate, and the notification sinks
How it runs
Walkthrough flows
Dynamic views — the narrative spine of the system, step by step.
Walkthrough — PR invariant check
prCheckFlowThe trust boundary pins invariants.json + CLAUDE.md to the base branch FIRST, so a PR cannot weaken its own checks; the verifier exit code is the authoritative gate, and the bot comment is upserted in place (one per PR).
Walkthrough — verifying one invariant
verifyOneFlowEach invariant runs in isolation. A search that hits the 500-result cap, or a canary that finds nothing, throws — surfacing as status:error so an incomplete run can never masquerade as a clean pass.
Walkthrough — opt-in MCP / agent backend
mcpFlowOPT-IN (--mcp), exercised by no workflow. A Claude agent calls the Sourcegraph MCP tools and returns a JSON array; a mumbled or unparseable response throws rather than reporting "no matches". Note it cannot detect truncation today.
Where it runs
Deployment
What runs where, and the process & data boundaries between the pieces.
Deployment — where each piece runs
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.