# Common Architecture Diagramming

> Standards for creating clear, audience-appropriate C4 and UML architecture diagrams with Mermaid. Use when producing system context diagrams, container views, sequence diagrams, ERDs, or updating ARCHITECTURE.md files; defer design-session deliverables to system-design-diagramming.

- Skill: `hoangnguyen0403/common-architecture-diagramming` (Agent Skill, multi-file: 55 files)
- Install (CLI): `npx skillmds@latest add hoangnguyen0403/common-architecture-diagramming`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hoangnguyen0403/common-architecture-diagramming/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: HoangNguyen0403 (https://skillmd.com/u/hoangnguyen0403)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/hoangnguyen0403/common-architecture-diagramming

---


# 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](references/diagram-selection.md).
- **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](references/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](references/implementation.md) 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](references/diagram-selection.md)
- [Cloud Architecture](references/cloud-architecture.md)
- [C4 Model Guide](references/c4-model.md)
- [Checklist](references/checklist.md)
- [Best Practices](references/best-practices.md)