Diagram Standards

Status: Canonical
Last updated: 2026-07-05

---

Tooling

All diagrams in this knowledge base use Mermaid embedded in Markdown. No binary-only architecture images in canonical docs.

---

When to diagram

Situation	Diagram type
Request/response flow	Sequence
Ownership / dependencies	Flowchart or graph
State transitions	State diagram
Lifecycle phases	Timeline or flowchart
Data movement	Flowchart with labeled edges

---

Conventions

Naming

• Use registry IDs: PL-003, PRD-001, not repo folder names alone
• Subgraphs label the bounded context
• Edge labels describe the contract or event name

Example — platform dependency

flowchart LR
    PRD001[PRD-001] -->|contracts| PL003[PL-003]
    PL003 --> PL006[PL-006]
    PRD001 -->|adapters| PL004[PL-004]

Example — sequence

sequenceDiagram
    participant U as User
    participant A as Agent (PL-003)
    participant P as Planner
    participant T as Tool
    U->>A: Message
    A->>P: Resolve intent
    P->>T: Execute capability
    T-->>A: DTO result
    A-->>U: Structured response

---

Placement

• Section README: one ecosystem or lifecycle diagram minimum
• Platform / product pages: architecture diagram required
• ADRs: optional decision flow diagram
• Tutorials: step flow when >3 steps

---

Maintenance

Diagrams are code — update them in the same PR as architectural changes. Stale diagrams are treated as documentation defects.

---

Related

• STANDARDS/documentation-quality.md
• ARCHITECTURE/README.md

Breadcrumbs: Home → Standards → Diagrams