Project
Svarupa
Architecture diagrams that carry their own evidence
A Python CLI that reads a codebase with tree-sitter (pinned Python and TypeScript/JavaScript grammars) and produces verified architecture diagrams plus a queryable knowledge graph. Every node and edge carries file:line evidence or it does not render; omissions are stated as diagnostics, never fabricated. Published on PyPI under the MIT license.
- Python
- tree-sitter
- NetworkX
- PyYAML
- MCP
- GitHub Actions OIDC
Key Features
The evidence contract
Every rendered node and edge carries file:line evidence from the source. When nothing extractable exists, no box is drawn; the SVA-R-004 diagnostic states the omission instead.
Six diagram types in one report
Architecture, module dependencies, data flow, request flow, deploy topology and ERD render into a single self-contained interactive HTML report with recursive drill-down and #tab/<box-id> deep links.
Knowledge-graph query CLI
Seven query functions — graph_stats, get_node, get_neighbors, shortest_path, affected, god_nodes and query_graph — run against the same graph.json the renderers use.
MCP server
The same graph is exposed over stdio or streamable-http, so an agent can query the codebase map as tools instead of re-reading the repository.
Lockfile and per-PR CI diffing
A byte-deterministic architecture.lock is committed to the repo; CI regenerates it per pull request and svarupa --diff --drift-base posts the architecture delta as a review artifact.
Environment detection
Deployment views distinguish production, staging, qa and development indicators found in the codebase rather than assuming a single environment.
Architecture
- A repository walk feeds pinned tree-sitter grammars (Python and TS/JS) for extraction
- Extracted facts with file:line spans build a knowledge graph stored as graph.json
- Six renderers, the lockfile and the HTML report all read that single graph
- Output is byte-deterministic, so a lockfile diff always means the code changed
- No evidence, no box: omissions surface as SVA-R-004 diagnostics, never inventions
- The query CLI and MCP server read graph.json directly, without re-running extraction
Diagrams
A repository walk feeds pinned tree-sitter grammars, builds graph.json, and renders six views, a byte-deterministic lockfile, and a report; queries and MCP read the same graph.
Read diagram description
A repository walk feeds tree-sitter extraction with pinned Python and TypeScript grammars. Extraction builds a knowledge graph stored as graph.json with nodes, edges, and file:line evidence. From that one graph svarupa renders an interactive viewer with 6 diagram types, a byte-deterministic architecture.lock, and a REPORT.md summary. A query layer of 7 graph query functions and an MCP server both read graph.json. This is an illustrative sketch, not a deployment topology.
Every rendered node carries file:line evidence; when nothing extractable exists, no box renders and SVA-R-004 states the omission.
Read diagram description
Source code passes through tree-sitter extraction, which yields facts with file:line spans. When evidence is found, a graph node carries that file:line evidence and the renderer draws a box for it. When nothing extractable exists, no box is rendered; the SVA-R-004 diagnostic states the omission instead. The rule is one invariant: every node and edge carries evidence or it does not render. This is an illustrative sketch, not a deployment topology.
Alpha status
Alpha, and honest about it
Svarupa is v0.2.1 alpha. Extraction covers Python and TypeScript/JavaScript with pinned grammars; anything else is reported as an omission, not guessed. The public face is PyPI — install with uv tool install svarupa, pipx or pip.
Continue exploring
Install it from PyPI, click through two live reports generated from real repositories, or read the full case study and blog series.
Svarupa on PyPI
MIT licensed, Python ≥3.10. Install with uv, pipx or pip.
Live report: Adaptive RAG
The full interactive svarupa report for the Adaptive RAG repository, hosted as generated.
Live report: Document Extraction Pipeline
The full interactive svarupa report for the Document Extraction Pipeline repository, hosted as generated.
Read the case study
The evidence contract, the six views, the lockfile and CI diff loop, and the measured numbers with known limits.
Blog series, part 1
Svarupa: Architecture Diagrams That Carry Their Own Evidence — the thesis and the contract.
Measured outcomes
856 tests gate every commit. Measured over 15 commits of real project history, the median lockfile churn is 0 lines per commit, and extraction plus rendering were validated on a 592-module production backend. These numbers come from the project’s own test suite and validation runs; no comparison against other tools is claimed.
856
Tests gating every commit
0 lines
Median lockfile churn per commit
592
Modules in the validation repo
Want something like this built for you?
Tell me about it. I reply within one working day with a first take and no sales pitch.