architecture-doc-generator

name

architecture-doc-generator

description

Generates a high-quality architecture.md file for any codebase using spec-driven development and Mermaid diagrams. Use this skill whenever the user wants to document system architecture, generate an architecture.md, create a codebase map, explain how their project is structured, produce technical documentation for new contributors, or visualize component relationships. Also trigger when the user says "document the architecture", "create architecture docs", "write an architecture overview", "add diagrams to the docs", "explain the codebase structure", or "generate system diagrams". This skill produces benchmark-quality output modeled after the rust-analyzer architecture.md — with Bird's Eye View, Code Map, Architecture Invariants, API Boundaries, Mermaid diagrams, and Cross-Cutting Concerns sections.

Architecture Doc Generator

You are generating a high-quality architecture.md file that serves as the definitive guide for new contributors and maintainers. The benchmark is the rust-analyzer architecture.md: clear, opinionated, rich with invariants and component boundaries.

Phase 1 — Spec-Driven Exploration

Before writing a single word of documentation, understand the system deeply. The architecture doc must reflect reality, not generic patterns.

1.1 Read existing specs and docs first

Look for these in order:

• CLAUDE.md, CONTRIBUTING.md, README.md — stated goals and conventions
• docs/, spec/, .claude/ — any existing specs or design notes
• package.json, Cargo.toml, pyproject.toml, go.mod — declared dependencies reveal architecture

1.2 Map the codebase structure

Run a structural survey:

# Top-level shape
find . -maxdepth 2 -type d | grep -v node_modules | grep -v .git | sort

# Entry points
find . -name "main.*" -o -name "index.*" -o -name "app.*" | grep -v node_modules | grep -v .git | head -20

# Key interfaces and boundaries
grep -r "export\|pub mod\|module\|interface\|class\|def " --include="*.ts" --include="*.rs" --include="*.py" --include="*.go" -l | head -30

1.3 Identify the key abstractions

For each major directory/module, answer:

• What is its single responsibility?
• What does it accept as input and produce as output?
• What does it deliberately NOT know about? (these become Architecture Invariants)
• Is it an API Boundary — a place where consumers talk to internals?
• What would break silently if someone violated the intended design?

Do not skip this phase. A surface-level architecture doc is worse than none.

---

Phase 2 — Document Structure

Write architecture.md with exactly these sections, in this order.

Section 1: Introduction

A 2–3 sentence orientation paragraph. What does this system do at the highest level? Include links to:

• The main README or getting-started guide
• Any video walkthroughs or design blog posts (if they exist)
• The primary entry point file

Section 2: Bird's Eye View

Write this section as if explaining to a smart engineer on their first day.

• 1–2 paragraphs describing: what goes in, what comes out, what the system fundamentally is
• Describe the ground state (inputs the system must receive) vs. derived state (what it computes)
• Describe the client/consumer relationship — how does a caller interact with the system?

Then generate a Mermaid diagram using the Mermaid MCP tool (validate_and_render_mermaid_diagram). Use a graph TD or graph LR showing the top-level data flow: inputs → core system → outputs. Label edges with what flows between components.

Example shape (adapt to the actual system):

graph TD
    Client["Client / Caller"]
    Input["Input: Source Files + Config"]
    Core["Core Engine"]
    Model["Semantic Model"]
    Features["IDE Features / API"]

    Client -->|"submit delta"| Core
    Input --> Core
    Core -->|"compute on demand"| Model
    Model --> Features
    Features -->|"responses"| Client

Section 3: Code Map

This is the heart of the document. Systematically document every top-level module/package/crate. For each one:

### `path/to/module`

One paragraph: what this module does, its core data structures, and how it
fits into the overall flow.

**Architecture Invariant:** [state something this module deliberately ignores,
avoids, or guarantees — the things that would surprise a reader if violated]

(Add more invariants if the module has multiple important constraints.)

Rules for Architecture Invariants:

• Write invariants for things that are non-obvious — not "this module parses JSON" but "this module never reads from disk; all I/O happens at the boundary above it"
• An invariant is a constraint the codebase enforces on itself, not a description of what it does
• If a module is an API Boundary, say so explicitly and explain what that means: "This is an API Boundary. Code above this line talks to the public; code below implements without exposure."

Cover every significant module. Don't lump unrelated things together.

Generate at least one additional Mermaid diagram showing module-to-module dependencies. Use graph LR with arrows showing which modules import/call which. Mark API Boundaries visually (e.g., double border or subgraph).

Section 4: Cross-Cutting Concerns

Document the topics that touch every layer. Include whichever of these apply:

Testing Strategy

• Where are the meaningful test boundaries?
• What does a typical test look like? (show a short representative example)
• What are the heavy/integration tests vs. fast unit tests?
• Any data-driven or snapshot testing patterns?

Error Handling

• Does the system use Result types, exceptions, or (T, Vec<Error>)?
• Where does the system fail gracefully vs. hard-crash?
• How are panics / unhandled errors contained?

Observability

• How do you know what's happening inside the running system?
• Logging, tracing, metrics, profiling — where do they live?

Cancellation & Lifecycle (if applicable)

• How are long-running operations cancelled?
• How is shared state protected?

Code Generation (if applicable)

• What parts of the codebase are generated?
• How do you regenerate them?
• What bootstrapping constraints exist?

Configuration

• Where does runtime config live?
• What's the boundary between config and code?

---

Phase 3 — Diagram Strategy

Use the Mermaid MCP tool (validate_and_render_mermaid_diagram) for every diagram. Never write raw Mermaid blocks in the markdown without rendering them through the MCP first — the MCP validates syntax and surfaces errors before they end up in the file.

Minimum required diagrams:

1. Bird's Eye View — graph TD/LR data flow (Phase 2, Section 2)
2. Module Dependency Map — graph LR showing imports/call graph (Phase 2, Section 3)

Optional but high-value diagrams: 3. Request lifecycle — sequenceDiagram showing a single request from client to response 4. State machine — stateDiagram-v2 if the system has meaningful lifecycle states 5. Data model — classDiagram for the core domain types

Diagram quality rules:

• Label every edge with what flows ("submits delta", "returns snapshot", "panics with Cancelled")
• Use subgraphs to group related modules
• Mark API Boundaries with a distinct style (e.g., style X stroke:#f90,stroke-width:3px)
• Keep diagrams focused — one concept per diagram, not everything at once

After the MCP renders each diagram, embed the mermaid code block in the architecture.md so the diagram is readable in any Markdown renderer:

(the diagram code here)

---

Phase 4 — Quality Bar

Before finishing, self-review against this checklist:

• Every top-level module is covered in the Code Map
• At least 2 diagrams are present and rendered via Mermaid MCP
• Architecture Invariants exist for non-trivial modules (not just descriptions)
• API Boundaries are explicitly called out
• Bird's Eye View is legible to a smart outsider with no context
• Cross-Cutting Concerns covers testing and error handling at minimum
• No generic filler — every sentence reflects the actual codebase, not a template
• The document reads as an opinionated guide, not a neutral index

---

Writing Tone

• Opinionated and direct. State design decisions as decisions, not accidents.
• Future-contributor focused. Write for the engineer who is reading this on day 1.
• Invariants over descriptions. What the system refuses to do is more valuable than what it does — it prevents future bugs.
• Short paragraphs. Dense walls of text hide the signal. One idea per paragraph.
• Use bold sparingly — reserve it for Architecture Invariants and API Boundary labels.

---

Reference: rust-analyzer benchmark

The rust-analyzer architecture.md (https://github.com/rust-lang/rust-analyzer/blob/master/docs/dev/architecture.md) is the quality target. Study its structure:

• "Bird's Eye View" section establishes ground state vs. derived state in 3 paragraphs
• Code Map covers every crate with invariants, not just descriptions
• Cross-cutting concerns (Cancellation, Testing, Error Handling, Observability) are explicit and specific to that codebase
• Architecture Invariants are opinionated constraints, not feature lists

See references/rust-analyzer-patterns.md for extracted patterns and anti-patterns to avoid.