architecture-diagramslisted

# Architecture diagrams A diagram's job is to build an accurate mental model fast. Most fail by mixing altitudes (a load balancer beside a class), going stale the week after they are drawn, or showing the aspirational architecture instead of the real one. Pick a level, generate from truth, and label what is real versus planned. ## Method 1. **Choose one altitude per diagram (C4 as the ladder).** Context (the system as one box, its users and external systems), Container (deployable units: services, databases, and how they talk), Component (inside one container), Code (rarely worth drawing: the IDE shows it). Each diagram stays at one level; the classic failure is a single picture mixing a whole-system view with one class's methods, useful to nobody. 2. **Match the diagram to the audience and question.** Executives and new joiners want Context (what is this, what does it touch); engineers designing an integration want Container; someone modifying a service wants Component (see technical-vision, exec-briefing for the altitude-per-audience rule). Draw the diagram that answers the reader's actual question, not the one that looks most complete. 3. **Diagram as code, versioned with the system.** Mermaid, PlantUML, or Structurizr in the repo (see markdown-mermaid-writing, docs-as-code): text diffs in pull requests, rendered in docs, updated in the same change that alters the architecture. Diagrams drawn in a GUI tool and pas