aravhawk/arch-mmd

Architecture Diagram Generator

Create or update an ARCHITECTURE.mmd Mermaid diagram that maps out the codebase's high-level architecture. The goal is a clean, readable overview — not an exhaustive map of every file.

---

PHASE 1: EXPLORE THE CODEBASE

Scan the project to understand its architecture at a high level:

1. Identify project type — framework, language, monorepo vs single app
2. Find the entry point(s) — what kicks things off (CLI, web server, main function)
3. Identify the core modules — the 5-15 key components that form the backbone (not every file)
4. Trace the main data flow — the primary happy path from input to output
5. Find external dependencies — databases, APIs, third-party services (only the important ones)
6. Note major boundaries — client/server, package boundaries in monorepos

---

PHASE 2: BUILD THE DIAGRAM

Use graph TD (top-down) as the default direction. Use graph LR only if the architecture is clearly pipeline-shaped.

Simplicity is paramount

The diagram should be immediately readable on a single screen. Think of it as an architecture overview you'd sketch on a whiteboard — not a full system blueprint.

• Target 8-20 nodes for most projects. Small projects may have fewer, large monorepos may stretch to ~25 max. If you're exceeding 20, you're almost certainly too granular.
• Do NOT use subgraph — they add visual clutter and nesting complexity. Use color coding to group related nodes instead.
• Minimize edge crossings — structure nodes so the flow reads cleanly top-to-bottom (or left-to-right). If connections are crisscrossing everywhere, reorganize.
• One level of detail — pick a consistent abstraction level. Don't mix "the entire frontend" as one node alongside individual Python files as separate nodes.

Node labels

Include the file/module name and a brief description using <br/> for multi-line labels:

ENGINE["engine.py<br/>CodeLoader + Orchestrator"]
CLI["cli.py<br/>Arg parsing + validation"]

For simple/obvious nodes, a single-line label is fine:

DB[(PostgreSQL)]

Keep labels short — max ~5-6 words per line.

Node IDs

Use short, uppercase IDs: CLI, ENGINE, AUTH, DB, API

Connections

• Use --> for standard flow
• Label edges sparingly — only when the relationship isn't obvious from context: -->|"REST"|, -->|"WebSocket"|
• Use & fan-in syntax when multiple nodes feed into one target:

P1 & P2 & P3 --> AGENT

• Avoid excessive connections. Not every interaction needs an arrow. Show the primary architectural flow, not every function call.

Color coding with style

Color-code nodes by their role to make the diagram scannable at a glance. Pick a small, consistent palette (4-6 colors max). Always include color:#fff for readability.

Role-to-color suggestions (adapt to the project):

| Role | Color | Example | |---|---|---| | Entry point / user-facing | #e74c3c (red) | CLI, UI, API gateway | | Core engine / orchestrator | #2980b9 (blue) | Main engine, coordinator | | Agent / processor | #8e44ad (purple) | Workers, agents, handlers | | External service / API | #e67e22 (orange) | Third-party APIs, LLMs | | Output / result | #27ae60 (green) | Reports, exports, responses | | Infrastructure / runtime | #16a085 (teal) | Runners, browsers, terminals |

Example:

style ENGINE fill:#2980b9,color:#fff
style REPORT fill:#27ae60,color:#fff

Node shapes

• ["Label"] — default rectangle for most components
• [(Database)] — databases and data stores only
• (["Label"]) — stadium shape for entry points (optional, use sparingly)
• No other shapes needed; keep it uniform

---

PHASE 3: WRITE THE FILE

1. Write the diagram to ARCHITECTURE.mmd in the project root
2. If ARCHITECTURE.mmd already exists, read it first, then update it to reflect the current state — don't start from scratch unless the existing diagram is fundamentally wrong
3. The file should contain ONLY the Mermaid diagram — no markdown fences, no frontmatter, no prose

---

CONSTRAINTS

Readability over completeness — this is the #1 rule.

• Keep it simple — if the diagram looks complex, it IS too complex. Collapse groups of related files into a single node (e.g., "API Routes" instead of listing every route file). The diagram should be a clean high-level overview.
• 8-20 nodes for most projects — this is a hard guideline. Fewer is often better. Only exceed ~20 for genuinely large/complex systems, and never exceed ~25.
• No subgraphs — use color coding to visually group nodes instead.
• Map real modules, not abstractions — nodes should correspond to actual files, packages, or services, not vague concepts like "Business Logic Layer"
• Brief descriptions — use <br/> in labels so someone unfamiliar can understand each node's role
• Always color-code — a diagram without style directives is incomplete
• No orphan nodes — every node must connect to at least one other node
• Accuracy over completeness — only include components confirmed to exist; leave out anything marginal
• Update, don't recreate — when updating an existing diagram, preserve structural choices and only change what's outdated