Svarupa: Verified Architecture Diagrams from Real Code

At a Glance

The Problem

Architecture documentation describes what someone meant to build. The code describes what exists. Between the two sits drift: the layer that was bypassed "just this once", the dependency added under deadline, the service that quietly grew a second database.

AI-assisted codegen accelerates this. When an agent lands a dozen commits a day, the architecture diagram from last quarter is not stale — it is fiction. And a plausible-but-wrong diagram is worse than none at all, because it gets believed. Reviewers reason from it, onboarding engineers trust it, and agents read it back as ground truth.

The alternative I wanted was boring and strict: a diagram that only shows what it can prove, points at the proof, and says out loud what it left out.

The Evidence Contract

Svarupa's central invariant: every node and every edge in every diagram carries file:line evidence, or it does not render. There is no "probably connected to" box. When a module cannot be drawn because there is no extractable source behind it, the report says so — diagnostic SVA-R-004 names the omission and the reason.

Explore it live: adaptive-rag — diagram report · graph · document-extraction-pipeline — diagram report · graph

This is what separates it from AI-generated architecture diagrams. A language model looks at a repository and produces a plausible picture of what the code probably does. Svarupa parses the code with pinned tree-sitter grammars (Python 0.25.0, TypeScript/JavaScript 0.23.2), builds a knowledge graph in which every fact is anchored to a source line, and renders only from that graph. The viewer lets you click any box through to the line that justifies it.

What It Produces

Running svarupa . in a repository writes a .svarupa/ directory: a self-contained index.html viewer (no server needed), the full knowledge graph as graph.json, a human-readable REPORT.md, and per-diagram layout data.

Explore it live: adaptive-rag — diagram report · graph · document-extraction-pipeline — diagram report · graph

Six diagram types come out of the same graph: architecture, module dependencies, data flow, request flow, deploy topology, and ERD. Each is drawn only where evidence exists. On one public demo repository, the ERD, lifecycle, and workflow views were simply not generated — the code contained no SQL-schema, state-transition, or process evidence to back them. That absence is the product working as designed.

The viewer handles scale honestly. When a view would be unreadable, it draws the 12 most significant boxes and states the remainder ("N more not drawn; all of them are in graph.json"). Every box supports recursive drill-down and a #tab/<box-id> deep link you can paste to a teammate. The same seven query functions behind the viewer are also exposed as a CLI (svarupa query) and as an MCP server over stdio or streamable-http, so an AI agent can answer architecture questions against the verified graph instead of guessing.

The Lockfile and the CI Diff Loop

Diagrams you cannot diff are documentation. Diagrams you can diff are governance. svarupa . --lock writes architecture.lock: a compact, canonically ordered, byte-deterministic text file (schema version 1.7) designed to be committed. Environment records are name-only and ordering is canonical, so the lockfile does not churn — measured over 15 commits of real project history, the median change is 0 lines per commit.

Explore it live: adaptive-rag — diagram report · graph · document-extraction-pipeline — diagram report · graph

On every PR, CI regenerates the report and runs --diff against the committed lock: added and removed modules, changed edges, grammar-version changes. --drift-base solves the stale-base problem by regenerating the base lockfile from the base branch's actual code first, so a PR's delta is not polluted by other people's merged changes. svarupa setup ci_github (or ci_gitlab) installs the workflow in one command, pinned to the exact svarupa version for reproducibility.

Measured Numbers

All figures below are from the project's own test suite and validation runs. No comparative benchmark against other tools is claimed.

The demo numbers are live, not illustrative: both interactive reports are hosted on this site, generated with the released svarupa 0.2.1, and correspond to the repositories at generation time.

Known Limits

• Alpha software. The CLI is at 0.2.1; interfaces can still change.
• Two extraction languages. Python and TypeScript/JavaScript, with pinned grammars. Other files are counted and honestly reported as not extractable.
• Artifact weight on huge repos. index.html can still be tens of MB because all views are pre-rendered for offline use, and some views are withheld on very large repositories with an explicit note — the data is always complete in graph.json.
• Modest call-pinning in framework-heavy code. On the framework-heavy adaptive-rag demo, 29.3% of Python call sites pinned to a definitive target (import- and reference-based edges pin at 77–97%). Svarupa prints these numbers rather than inflating them.

Links

Svarupa is on PyPI (uv tool install svarupa). The two live demo reports — adaptive-rag and document-extraction-pipeline — are the fastest way to judge the output before installing anything. The project page has the feature summary, and the blog series walks through the thesis, the workflow, and the CI story. If you want this kind of evidence-backed architecture governance in your own codebase, get in touch.