Architecture Diagramming Standard

Priority: P1 (HIGH)

Guidelines

• Use C4 Model: Context -> Container -> Component -> Code.
• Audience-Centric: Tailor abstraction (Execs vs. Devs).
• Select Type: Sequence (Protocol), ERD (Data), State (Lifecycle), Cloud (Infra). See Selection.
• Explicit Labels: Label every arrow (e.g., "Uses", "HTTPS").
• Consistent Notation: Cylinders=DB, Rectangles=Systems, Dashed=Async.
• Metadata: Title, Date, Version, Author.
• Legend Mandatory: Define all shapes/colors/styles.
• Direction: graph LR (Flow) or graph TD (Hierarchy).
• Deployment: Map containers to infrastructure.
• Governance: CRITICAL: Review best-practices.md before starting.

Workflow

1. Name audience and the decision the diagram must support.
2. Pick one level: context for external actors, container for deployable systems, component for one container; never mix levels.
3. Pick notation: sequence for a request protocol, ERD for data ownership, state for lifecycle, deployment for infrastructure.
4. Draw only decision-relevant nodes; label every relationship with protocol or event.
5. Add title, scope/date/version, legend, and one review question for the intended audience.

See implementation examples for C4 container diagram in Mermaid.

Anti-Patterns

• Mixed Levels: DB columns in System Context.
• Unlabeled Arrows: Ambiguous relations.
• Mystery Shapes: Undefined in Legend.
• Dead Ends: Unconnected nodes.
• Clutter: >20 nodes/diagram.
• Acronyms: Undefined abbreviations.

References

• For design-session deliverables, system-design-diagramming supersedes Mermaid with the Archify typed-spec style.
• Diagram Selection
• Cloud Architecture
• C4 Model Guide
• Checklist
• Best Practices