ARCHITECTURE.md Generator

Generate high-quality ARCHITECTURE.md files that give newcomers a mental map of a codebase. Based on matklad's article: the biggest contributor bottleneck is not writing code, it's figuring out where to change it. ARCHITECTURE.md bridges that gap.

Core Principles

1. Short and stable -- Only describe things unlikely to change frequently. Don't synchronize with code. Revisit a couple of times a year.
2. Bird's eye first -- Start with the problem being solved, not the solution.
3. Codemap over prose -- Answer "where's the thing that does X?" and "what does this thing do?" for every module.
4. Name, don't link -- Name important files, modules, types. Don't hyperlink (links go stale). Encourage symbol search.
5. Invariants are gold -- Explicitly call out what's deliberately absent. Important invariants are often expressed as absence, and are impossible to divine from reading code.
6. Mark boundaries -- API boundaries between layers constrain all possible implementations behind them. Finding a boundary by randomly reading code is hard.
7. Cross-cutting concerns last -- After the codemap, address things that are everywhere and nowhere (error handling, testing, config).

Workflow

Step 1: Explore the Codebase

Use tree, glob, and read tools to understand the project:

• Read README, package.json/Cargo.toml/pyproject.toml for the project's purpose
• Run tree -L 2 -d (or similar) to see directory structure
• Identify entry points (main files, index files, bin directories)
• Read key files at module boundaries to understand the layers

Step 2: Identify the Architecture

Map out:

• The problem being solved -- What does this project do? What's the input/output?
• Coarse-grained modules -- What does each top-level directory/package do?
• Data flow -- How does data move through the system? Input -> ??? -> Output
• API boundaries -- Which modules are public interfaces vs internal implementation?
• Architectural invariants -- What rules are enforced by structure? What's deliberately absent?
• Cross-cutting concerns -- Error handling, testing strategy, configuration, observability

Step 3: Write the ARCHITECTURE.md

Follow the template below. Keep the total document under ~300 lines for most projects.

Template

# Architecture

[One paragraph: what this project does at the highest level. What problem it solves.]

## Bird's Eye View

[How data flows through the system at the coarsest level.
Input -> Processing stages -> Output.
Keep this to 1-3 paragraphs.]

## Code Map

[Brief intro: "This section describes the high-level structure of the codebase.
Pay attention to **Boundary** and **Invariant** callouts."]

### `path/to/module-a/`

[What this module does in 1-3 sentences. Key types: `ImportantType`, `AnotherType`.]

**Boundary:** [If this is an API boundary, say so and what it means.]

**Invariant:** [What's deliberately absent or enforced. E.g., "This module never does I/O"
or "Nothing here depends on the HTTP layer."]

### `path/to/module-b/`

[Repeat for each significant module.]

### `path/to/module-c/`

[...]

## Cross-Cutting Concerns

### Error Handling

[How errors are handled across the codebase. Is it Result-based? Exceptions?
Do errors propagate or get caught at boundaries?]

### Testing

[Testing strategy. Where do tests live? What kinds of tests exist?
What are the important test boundaries?]

### [Other concerns as applicable]

[Configuration, observability/logging, code generation, build system, etc.
Only include sections that are genuinely cross-cutting.]

Rules

What to Include

• Directory/module purposes (1-3 sentences each)
• Names of important types, traits, interfaces, functions (for symbol search)
• API boundaries between layers
• Architectural invariants -- especially things that are deliberately absent
• Data flow at the system level
• Cross-cutting concerns that affect multiple modules

What to Omit

• Implementation details of how individual modules work (that's inline doc)
• Links to specific files or lines (they go stale)
• Anything that changes with routine PRs
• Exhaustive API documentation (that's rustdoc/typedoc/javadoc territory)
• Setup instructions (that's README)
• Contribution guidelines (that's CONTRIBUTING.md)

Style Rules

• Use ### \path/to/module/`` headers with backtick-quoted paths for the codemap
• Use Boundary: and Invariant: prefixed callouts (bold label, not blockquotes)
• Keep module descriptions to 1-3 sentences
• Name types in backticks: "Key types: FooBar, BazQux"
• Write in present tense, active voice
• Prefer concrete over abstract: "parses CLI arguments" not "handles input processing"

Quality Checklist

Before finishing, verify:

• Can a newcomer find "the thing that does X" using only this doc?
• Are API boundaries clearly marked?
• Are architectural invariants (especially absences) called out?
• Is every section stable enough to survive 6 months without update?
• Are important types/modules named (not linked)?
• Is there a bird's eye view before the codemap?
• Are cross-cutting concerns addressed?
• Does the codemap order match the data flow or dependency direction?
• Is it under ~300 lines? (Shorter = more likely to be read and maintained)

Reference Example

See references/example.md for a complete example ARCHITECTURE.md for a hypothetical TypeScript project, demonstrating all the patterns above.