Explain Architecture

Explain Architecture

You are producing an architecture explainer for a vibe-coder: someone who builds with AI but cannot read code fluently. Every output must be understandable by a smart person who has never programmed. Visuals first, jargon last.

Outputs (always all four)

All output goes in docs/architecture/ inside the target repo:

| File | Audience | Purpose | |------|----------|---------| | ARCHITECTURE.md | Human (non-coder) | Plain-English walkthrough with embedded diagrams | | diagrams/*.png + architecture.pdf | Human | Shareable visuals (PDF = all diagrams + captions in one doc) | | src/*.mmd | Tooling | Editable Mermaid sources for every diagram | | AI-CONTEXT.md | AI agents | Dense, structured project brief to paste/load into any agent session |

Workflow

Phase 1 — Scan the codebase

Do NOT read every file. Read strategically:

1. Shape: file tree 2–3 levels deep (ls -R depth-limited, or Glob). Note the top-level folders and what they suggest.
2. Manifests: package.json, pyproject.toml, requirements.txt, go.mod, Cargo.toml, composer.json, Gemfile, pom.xml — dependencies reveal the stack.
3. Entry points: main.*, index.*, app.*, server.*, cli.*, Dockerfile CMD, Procfile, npm scripts.
4. Config: .env.example, config/, settings.*, docker-compose.yml, CI files, infra files (*.tf, vercel.json, netlify.toml, fly.toml).
5. Data layer: migrations, models/, schema.prisma, *.sql, ORM model files, entities/. This feeds the ERD.
6. API surface: route definitions, controllers, api/ folders, OpenAPI specs, GraphQL schemas.
7. Agent memory files: CLAUDE.md, AGENTS.md, GEMINI.md, .cursorrules, .claude/skills/, .github/copilot-instructions.md, existing README.md — these tell you what past agents were told, and MUST be summarized into AI-CONTEXT.md.
8. External services: grep for SDK imports and API base URLs (stripe, supabase, firebase, openai, anthropic, twilio, s3, redis, etc.).

For large repos (>300 source files), fan out subagents per top-level directory and merge their summaries instead of reading inline.

Phase 2 — Build the mental model

Before drawing anything, write down (internally) answers to:

• What does this app DO, in one sentence a non-coder understands?
• What are the 3–8 major parts (frontend, API, database, workers, third-party services)?
• How does data flow for the ONE most important user action? (e.g. "user posts a message")
• What data is stored, and how do the tables/collections relate?
• What external services does it depend on, and what breaks if each disappears?
• Where does the code start executing when the app boots?

If you cannot answer one of these, go back to Phase 1 for that gap.

Phase 3 — Generate diagrams

Write Mermaid sources to docs/architecture/src/. Pick diagrams by what the codebase actually contains — see references/diagram-patterns.md for the full decision table and style rules. Typical set:

| # | File | Diagram | When | |---|------|---------|------| | 1 | 01-system-overview.mmd | Flowchart: big boxes — user, frontend, backend, DB, external services | Always | | 2 | 02-module-map.mmd | Flowchart: top-level folders and what depends on what | Always | | 3 | 03-data-flow.mmd | Sequence diagram: the #1 user action end-to-end | Always | | 4 | 04-erd.mmd | ER diagram: tables/collections and relationships | If any data layer exists | | 5 | 05-request-lifecycle.mmd | Flowchart: HTTP request path through middleware/handlers | If it's a server | | 6 | 06-deployment.mmd | Flowchart: where each piece runs (Vercel, Docker, AWS…) | If infra config exists |

Rules for every diagram (details in the reference file):

• Max ~12 nodes. If more, split into two diagrams or zoom out.
• Label edges with verbs: "saves order to", "asks for prices", not bare arrows.
• Plain-English node names: "Payments (handles Stripe)" not stripe_svc.
• Every .mmd file starts with a %% caption: comment — one sentence a non-coder

understands. The renderer puts it in the PDF.

Phase 4 — Render to PNG + PDF

python3 /scripts/render_diagrams.py docs/architecture

The script renders every src/*.mmd to diagrams/*.png and bundles them with their captions into architecture.pdf. It tries mmdc, then npx @mermaid-js/mermaid-cli, then falls back to a self-contained architecture.html (open in browser → Print → PDF) if node is unavailable. Report which path it took. If only HTML fallback worked, tell the user exactly: "open docs/architecture/architecture.html and print to PDF".

Verify: list the produced files and check PNGs are non-zero size before claiming success.

Phase 5 — Write ARCHITECTURE.md (for the human)

Follow references/architecture-md-template.md. Non-negotiables:

• Open with "What is this app?" — one paragraph, zero jargon.
• Embed each PNG (``) followed by a

"What you're looking at" paragraph in plain English.

• Include a "House tour" section: each top-level folder explained with a real-world

analogy (e.g. "api/ is the reception desk — every request from the outside world arrives here first").

• Include "Where to look when…" table: symptom → folder/file (e.g. "button text wrong →

src/components/", "payment failing → api/payments.py").

• No sentence should require programming knowledge to parse. If a technical term is

unavoidable, define it inline in parentheses the first time.

Phase 6 — Write AI-CONTEXT.md (for future agents)

Follow references/ai-context-template.md. This is the opposite register: dense, structured, no prose padding. It must contain everything a fresh agent session needs:

• One-line purpose, stack list, entry points, run/build/test commands
• Directory map with one-line role per folder
• Data model summary (tables, key fields, relations) in compact form
• API surface list (method + path + purpose)
• External services + which env vars they need
• Conventions found in the code (naming, patterns, state management)
• Digest of any existing CLAUDE.md / AGENTS.md / cursor rules found in Phase 1
• Pointer to the .mmd sources so the agent can read diagrams as text

End it with: "Regenerate with the explain-architecture skill after major changes."

Phase 7 — Report

Tell the user:

1. What the app is (one sentence — proves you understood it).
2. Files produced, with the PDF path highlighted.
3. How to reuse AI-CONTEXT.md: paste it into any agent (Claude Code, Codex, Gemini

CLI) at session start, or reference it from CLAUDE.md / AGENTS.md / GEMINI.md with one line: Read docs/architecture/AI-CONTEXT.md first.

1. Offer to add that pointer line to their agent memory file now.

Guardrails

• Never invent architecture. If you didn't see it in the code, it doesn't go in a

diagram. Mark genuine uncertainty: "(likely — inferred from config)".

• Secrets: never copy values from .env or config into any output. Names of env vars

are fine; values never.

• If the repo is tiny (<10 source files), skip diagrams 2/5/6 and say why — don't pad.
• If diagrams would exceed ~12 nodes, split rather than shrink text.
• Re-runs must overwrite docs/architecture/ cleanly — it is generated output.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Wahab901278
• Source: Wahab901278/claude-explain-architecture
• License: MIT

Install and usage instructions live in the source repository linked above.