nunki
Architecture documentation generated from source code
nunki reads a repository and writes an architecture book: diagrams chosen for the question they answer, an API reference, a data model, request and background flows, and a business-requirements scaffold. Every claim links to the file and line it came from, and each citation is verified against the commit.
Example books
Generated by CI from the current main, so they are exactly what the tool produces today.
Polyglot shop →
The project's own demo repository: TypeScript, Go, Python and Rust services around Postgres, Redis and Kafka.
Spring PetClinic →
The canonical Spring sample: JPA entities, Spring Data repositories, and both Compose and Kubernetes deployments.
PiggyMetrics →
A Spring Cloud microservice system: gateway routes from config, Feign calls, MongoDB, RabbitMQ, scheduled jobs that send email.
nunki itself →
The tool documenting its own repository: the analyzer, renderer, validator and MCP server, and how a scan becomes a book.
What to look at first
- Critical flows — sequence diagrams traced from a handler through its calls, writes and events, each message linked to the line that sends it.
- API reference — parameters with their wire names and validation rules, request and response models, errors, and who calls each operation.
- Data & integrations — the entity model with keys and cardinality, plus lifecycles read from status fields and the code that changes them.
- Business requirements — what the code implements, with the intent it cannot know marked needs input rather than guessed.
Proven on real repositories
Besides its own fixtures, nunki is run against public codebases of different shapes — etcd, MinIO, Caddy, Spring PetClinic, PiggyMetrics, wild-workouts and others. Each thing it got wrong became a fix and a regression fixture, and the results are written down rather than summarised: what each repository exposed →
Run it on your own repository
curl -fsSL https://github.com/sadaramk/nunki/releases/latest/download/install.sh | sh
nunki generate /path/to/your/repo --out docs/architecture
open docs/architecture/index.html
The book is self-contained and offline: one HTML file, a Markdown mirror for GitHub, llms.txt
for agents, and the typed DiagramIR behind every figure, which you can edit by hand and keep.
Getting started covers CI checks, hand edits and the agent interface;
how it works explains why the citations can be trusted.
The name
Nunki is the star σ Sagittarii. In Sumerian cuneiform NUN.KI writes the name of
Eridu, the holy city on the Euphrates, and MUL.NUNKI — "star of the city of Eridu" —
appears in Babylonian star lists. The IAU made Nunki the star's official name in 2016.
It is widely called the oldest star name still in use. The truth is better: the name was lost, recovered from tablets by archaeologists, and popularised by R. H. Allen in 1899 — whose Mesopotamian etymologies are not considered reliable — and it is now thought the original name referred to an asterism over in Vela, not to this star at all.