Architecture · LikeC4

Livedocs

Extract → store → serve → verify pipeline turning source into queryable, drift-checked claims

Open the interactive explorer → View on GitHub

built evolving planned research risk

The whole picture

System landscape

The system in context, then opened up into its containers.

Livedocs — system landscape — Livedocs — system landscape
index

Livedocs — containers (built vs planned) — Livedocs — containers (built vs planned)
livedocsSystem

Extract → store → serve → verify pipeline turning source into queryable, drift-checked claims

Risks & open questions — Risks & open questions
risks

Planned & research work — Planned & research work
planned

Inside each box

Containers & components

Each part decomposed into the components that implement it. Every box links to its source in the interactive explorer.

Extractor — deep-Go / tree-sitter / tribal miners — Extractor — deep-Go / tree-sitter / tribal miners
extractorContainer

extractor/ — turns source files into structural claims and mined tribal facts

Extraction pipeline — file sources & cache — Extraction pipeline — file sources & cache
pipelineContainer

pipeline/ — orchestrates walk → extract → cache → reconcile (deletion-aware) across local and remote file sources

Claims store — schema, tribal facts, cross-repo xref — Claims store — schema, tribal facts, cross-repo xref
dbContainer

db/ — per-repo SQLite (<repo>.claims.db): symbols, structural+semantic claims, tribal facts/evidence/corrections, plus a shared cross-repo xref index

MCP server — transports, pool, routing, tools — MCP server — transports, pool, routing, tools
mcpContainer

mcpserver/ — serves claims over the Model Context Protocol (stdio + HTTP/SSE), single- or multi-repo

Drift detection — structural / cross-repo / semantic / tribal — Drift detection — structural / cross-repo / semantic / tribal
driftContainer

drift/ + anchor/ — compares stored claims against current source across four modes

Semantic claim generator — generate / verify / LLM clients — Semantic claim generator — generate / verify / LLM clients
semanticContainer

semantic/ — generates Tier-2 prose claims (package purpose, usage, rationale) via the LLM, then adversarially verifies each (second LLM pass) and gates on a 0.7 confidence floor. RISK: only validated on the Kubernetes corpus so far; hallucination is held off by the verify gate, not yet calibrated across diverse repos

Sourcegraph integration — MCP client & enrichment — Sourcegraph integration — MCP client & enrichment
sgContainer

sourcegraph/ — MCP client, remote-extraction queue, query routing, and semantic enrichment of claims

Evergreen documents — detector, store, executor, tools — Evergreen documents — detector, store, executor, tools
evergreenContainer

evergreen/ — pairs a saved deep-search prose answer with a dependency manifest, then classifies drift (hot/warm/cold/orphaned) as the cited code evolves. Interface-driven so an external (Sourcegraph) adapter can reuse the detector + tools

Supporting utilities — check / prbot / aicontext / init — Supporting utilities — check / prbot / aicontext / init
supportContainer

Cross-cutting helpers wired into the CLI flows

How it runs

Walkthrough flows

Dynamic views — the narrative spine of the system, step by step.

Walkthrough — extract a repo into claims — Walkthrough — extract a repo into claims
extractFlow

Build needs CGO (tree-sitter), so run via `make build` / CGO_ENABLED=1. The cache keys on content + extractor + grammar versions, so a second run only touches changed files.

Walkthrough — agent queries claims over MCP — Walkthrough — agent queries claims over MCP
mcpQueryFlow

describe_package returns ~30–50 tokens per claim instead of raw source — the ~50x context reduction. Staleness is checked lazily on the call, within a 5s budget.

Walkthrough — drift detection in CI — Walkthrough — drift detection in CI
driftFlow

The GitHub Action runs the fast manifest scan first (sub-2s, no DB), escalating to claim-level structural and LLM semantic checks only when docs are touched.

Walkthrough — remote extraction & enrichment (no clone) — Walkthrough — remote extraction & enrichment (no clone)
remoteFlow

Requires SRC_ACCESS_TOKEN; the Sourcegraph MCP server is spawned via npx on demand. Files are read remotely, extracted locally, then enriched with semantic properties.

Where it runs

Deployment

What runs where, and the process & data boundaries between the pieces.

Deployment — where each piece runs — Deployment — where each piece runs
deployment

Explore 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.

Open the interactive explorer →