86 lines
2.4 KiB
Markdown
86 lines
2.4 KiB
Markdown
# DOCS — Architecture diagrams (Mermaid)
|
|
|
|
Diagrams live beside the prose they describe. Mermaid renders natively on
|
|
GitHub / Forgejo / Gitea / Obsidian — no extra tooling needed to view.
|
|
|
|
## When to include
|
|
|
|
- Any agent/skill that scaffolds documentation for a multi-component system
|
|
- Any repo with ≥ 3 services / layers / subsystems
|
|
|
|
## Four diagram patterns (use the right one)
|
|
|
|
### 1. System context (C4 level 1) — `flowchart LR`
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
U[User] -->|HTTP| API[API Gateway]
|
|
API -->|gRPC| SVC[Service]
|
|
SVC -->|SQL| DB[(PostgreSQL)]
|
|
SVC -->|publish| Q[[Queue]]
|
|
```
|
|
|
|
Use for: one-page overview, onboarding, README architecture section.
|
|
|
|
### 2. Sequence — `sequenceDiagram`
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
Client->>API: POST /orders
|
|
API->>DB: INSERT
|
|
DB-->>API: id
|
|
API-->>Client: 201 Created
|
|
```
|
|
|
|
Use for: request flow, auth handshake, error recovery sequence.
|
|
|
|
### 3. State machine — `stateDiagram-v2`
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Pending
|
|
Pending --> Running: start
|
|
Running --> Done: success
|
|
Running --> Failed: error
|
|
Failed --> Pending: retry
|
|
```
|
|
|
|
Use for: job lifecycle, FSM-driven features, connection state.
|
|
|
|
### 4. ER / data model — `erDiagram`
|
|
|
|
```mermaid
|
|
erDiagram
|
|
USER ||--o{ ORDER : places
|
|
ORDER ||--|{ LINE_ITEM : contains
|
|
```
|
|
|
|
Use for: DB schema summary. Keep ≤ 10 entities per diagram.
|
|
|
|
## Rules
|
|
|
|
- **Diagram-as-code, no binary exports.** `.mmd` or fenced block, never `.png`
|
|
- **≤ 15 nodes / 20 edges per diagram.** Over that → split
|
|
- **Labels are nouns.** Edges are verbs. No prose inside nodes
|
|
- **One diagram = one concern.** Don't mix system context + sequence in one chart
|
|
- **Preview locally** with `mmdc` before commit: `mmdc -i diagram.mmd -o /tmp/preview.svg`
|
|
- **Link to source in caption** — "See `docs/diagrams/orders.mmd` for source"
|
|
|
|
## Forbidden
|
|
|
|
- ASCII art for multi-node graphs (use Mermaid — renders everywhere)
|
|
- Diagrams that contradict the code (stale → delete or fix)
|
|
- Secrets / real hostnames / IPs in diagrams (use placeholders)
|
|
|
|
## Install `mmdc` (preview tool)
|
|
|
|
```
|
|
npm install -g @mermaid-js/mermaid-cli # one-time
|
|
mmdc -i docs/diagrams/context.mmd -o /tmp/preview.svg
|
|
```
|
|
|
|
## References
|
|
|
|
- Mermaid syntax — https://mermaid.js.org/intro/ [VERIFIED: https://mermaid.js.org/intro/]
|
|
- C4 model — https://c4model.com/ [VERIFIED: https://c4model.com/]
|
|
- `~/.claude/rules/doc-conventions.md`
|