Architecture Documentation

Generate an architecture doc (diagram + data flow + decisions) from the codebase.

Docs & RefactorAdvanced

Why

GitHub's 2024 survey found 81% of developers expect AI tools to become more integrated in documenting code over the next year, the highest of any workflow. An architecture doc with a diagram, data flow, and key decisions onboards fast and preserves intent.

Generating it from the codebase (entry points, boundaries, data flow) keeps it grounded, not aspirational.

When

Use when onboarding is slow or the architecture is undocumented. Refresh on major changes.

How

1. Identify entry points (main, routes, workers). 2. Map module boundaries and dependencies. 3. Trace data flow for the main use case. 4. Prompt: "architecture doc: diagram (mermaid), data flow, key decisions, boundaries". 5. Add the doc to /docs; reference it from the README.

Example

```mermaid flowchart LR Client --> Router[API Router] Router --> Auth[middleware/auth] Router --> Books[api/books] Books --> DB[(Postgres)] Books --> Cache[(Redis)] ``` Data flow: request → auth → route → zod validate → service → DB → response. Key decisions: zod for validation; Redis for rate limit; no ORM (raw SQL via pg).

Common Problems

⚠Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.
⚠Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.
⚠Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift.

Best Practices

✓Generate the diagram from real entry points and boundaries.
✓Document key decisions (why, not just what) in an ADR-linked section.
✓Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved.

FAQ

What is Architecture Documentation?

Generate an architecture doc (diagram + data flow + decisions) from the codebase. It helps developers quickly grasp the core value and use cases of Architecture Documentation.

How do I get started with Architecture Documentation?

To get started with Architecture Documentation, focus on these points first: Identify entry points (main, routes, workers).

What are common mistakes with Architecture Documentation?

Common mistakes when using Architecture Documentation include: Error: Cannot find module 'xxx' after refactor → re-run `npm install` and `npx tsc --noEmit`; refactors often drop or rename imports.; Error: "Cannot read properties of undefined" after refactor → run the test suite (`npm test`) to catch behavior changes; refactor must be behavior-preserving.; Error: Docs drift: example no longer runs → execute examples in CI (`npm run docs:check`); tested examples never drift..

What are the best practices for Architecture Documentation?

Best practices for Architecture Documentation include: Generate the diagram from real entry points and boundaries.; Document key decisions (why, not just what) in an ADR-linked section.; Measure the outcome with a concrete metric (time saved, defect rate, test coverage) so the practice can be justified and improved..

How do I learn more about Architecture Documentation?

Start with the official docs, then search real-world examples on GitHub. Validate patterns in a small scratch repo before applying them to production code.