Architecture Diagram Builder

---
name: architecture-diagram-builder
description: Use when generating a system architecture diagram — components, services, data stores, external dependencies, request flow. Triggers on "architecture diagram", "system diagram", "C4 diagram", "block diagram of the system".
---

# Architecture Diagram Builder

Generate an architecture diagram that earns its place in a design doc. Most architecture diagrams fail because they try to show every microservice. Pick the 3-7 components the audience needs to understand for THIS conversation. Everything else is noise.

## Required inputs

1. **The audience** — engineers debugging? execs approving? new hires onboarding? The altitude changes.
2. **The scope** — which subsystem, which flow, which boundary
3. **The components that matter** — services, data stores, queues, caches, external deps
4. **The primary request flow** — what's the most important path through the system?
5. **Internal vs external** — what's owned by the team vs upstream/downstream

If the user asks for "the architecture diagram" of a system with 40 microservices, push back: "Which 5-7 components matter for this conversation? Showing all 40 will hide the answer."

## Mermaid syntax to use

For most cases, `graph LR` or `graph TB` with `subgraph` blocks for logical layers. Use `classDef` to differentiate component types (service, datastore, external).

\`\`\`mermaid
graph LR
    Client[Web/Mobile Client]

    subgraph Edge
        Gateway[API Gateway]
    end

    subgraph Core["Core services"]
        Ingest[Ingest Service]
        Transform[Transform Workers]
        Dashboard[Dashboard API]
    end

    subgraph Data["Data layer"]
        Kafka[(Kafka)]
        CH[(ClickHouse)]
        Redis[(Redis)]
    end

    External[3rd-party CRM]

    Client --> Gateway
    Gateway --> Ingest
    Gateway --> Dashboard
    Ingest --> Kafka
    Kafka --> Transform
    Transform --> CH
    Dashboard --> CH
    Dashboard --> Redis
    Transform -. webhook .-> External

    classDef datastore fill:#f3e9d2,stroke:#8a6d3b
    classDef external fill:#eee,stroke:#999,stroke-dasharray: 4 4
    class Kafka,CH,Redis datastore
    class External external
\`\`\`

## When to use PlantUML C4 instead

If you need formal C4 (Context / Container / Component / Code) levels — for an architecture review, an enterprise architecture wiki, or anything requiring proper stereotypes — use PlantUML with the C4-PlantUML library:

\`\`\`plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(user, "User")
System_Boundary(s, "Analytics Platform") {
  Container(web, "Web App", "React")
  Container(api, "API", "Go")
  ContainerDb(db, "ClickHouse", "Columnar DB")
}
System_Ext(crm, "Customer CRM")

Rel(user, web, "Uses")
Rel(web, api, "JSON/HTTPS")
Rel(api, db, "SQL")
Rel(api, crm, "Webhooks")
@enduml
\`\`\`

C4 is heavier setup but gives you a shared vocabulary across the org. Use Mermaid for fast iteration; C4 for the artifact that lives in the architecture wiki.

## Layout principles

- **Subgraph by responsibility, not by team.** "Data layer" is durable; "Team Phoenix" is not.
- **Datastores get a distinct shape** — cylinders `[(...)]` in Mermaid; `ContainerDb` in C4.
- **External dependencies get a distinct style** — dashed border or gray fill. The reader needs to know what you don't own.
- **Arrows show direction of REQUEST**, not direction of data. `A --> B` means A calls B.
- **Label arrows when the protocol matters** ("gRPC", "Kafka topic: events.v1") — otherwise leave them clean.
- **3-7 boxes per diagram.** More than that, split into a context diagram + zoom-ins.

## Anti-patterns

- **Show every microservice** — diagram becomes a constellation. Pick the ones that matter for the question being answered.
- **No external deps shown** — most systems break at integrations. Show them.
- **Arrows without direction** — undirected edges hide who depends on whom.
- **"The cloud" or "the network" as a node** — meaningless. Either show the specific component or omit it.
- **One diagram for all audiences** — exec diagrams != engineer diagrams. Make two.
- **Logos as decoration** — the AWS S3 logo doesn't add information. Use shapes consistently.

## Rendering hints

- Mermaid: GitHub, Notion, Confluence (with plugin), Slack render natively. Easiest path.
- PlantUML: needs a renderer. `plantuml.com/plantuml` for one-off; install locally for repo-resident diagrams.
- For architecture reviews, export to SVG and embed — code blocks don't always render in PDF exports.

## Output

The diagram block (Mermaid or PlantUML) plus 3 lines: components shown, components intentionally omitted, and the single request path the diagram is optimized to explain.