architecture-mermaid
Architecture Mermaid
Overview
An architecture diagram reads as senior work when its visual structure mirrors the system's logical structure, not because it has more colors or fancier syntax. Amateurs lay every element flat, color randomly, and connect everything to everything. Architects encode meaning: layers become regions, categories become colors, importance becomes visual weight, and the main data flow is unmistakable.
Core principle: information layering + consistent semantic encoding. Every visual choice (color, shape, line style, direction) must carry meaning. If a choice carries no meaning, remove it.
Layout constraint (aligns with global CLAUDE.md): prefer a balanced, roughly square aspect ratio with flowchart TB. Use LR only as a last resort when a balanced layout is genuinely unachievable — not by default, even for "pipeline" or "architecture" diagrams.
When to Use
- Drawing system architecture: services, components, queues, stores, external deps, deployment/trust boundaries.
- Drawing a framework or library's internal structure: abstraction layers, module dependencies.
- An existing architecture diagram is flat, colorless, a tangle of crossing arrows, or you can't tell the main flow at a glance.
When NOT to use: call chains / message passing → sequenceDiagram; state transitions → stateDiagram; pure data relationships → erDiagram. This skill is for architecture/framework/module structure.