Architecture Diagrams

Patterns for expressing architectural ideas visually.

Diagram Selection

Quick Syntax Reference

Mermaid Flowchart: flowchart TD → A[Node] --> B[Node]

Mermaid Sequence: sequenceDiagram → A->>B: Message

C4 Model: C4Context or C4Container → Person(), System(), Container()

ASCII Box: ┌───┐ │ │ └───┘ with ───▶ arrows

Best Practices

1. Start simple - ASCII first, Mermaid if complexity warrants
2. Label everything - Unlabeled arrows are ambiguous
3. Show data flow - Arrows indicate who initiates
4. Group related - Use subgraphs for logical boundaries

Hybrid ASCII + Mermaid

Use ASCII art for spatial layouts (UI wireframes, page structure) and Mermaid for sequential flows (user journeys, data flow). Each tool applied to its strength — ASCII shows position, Mermaid shows order.

See reference.md for complete syntax, examples, and advanced patterns.

Table Patterns for Multi-Command Workflow Docs

Tables are a distinct visualization tool from diagrams, and picking the right shape changes how fast cold readers parse a system.

Sequenced tables disambiguate better than taxonomic ones when commands or concepts feel interchangeable. Reframing three ambiguous options as "session → weekly review → housekeeping" clicks faster than a flat category list.

Artifacts tables (3 columns: artifact / producer / consumers) make it explicit when skipping one step silently degrades downstream steps. For workflow docs where commands hand state off to each other, this is often the single most useful table in the document — it surfaces failure modes that prose buries. Pair with a sequence diagram (Mermaid) when the temporal order also matters.