Diagram Knowledge Base

Quick reference for technical diagrams, Mermaid syntax, and C4 model.

Diagram Types Overview

| Type | Use Case | When to Use | |------|----------|-------------| | C4 Context | System boundaries | External actors, systems | | C4 Container | Deployable units | Apps, databases, services | | C4 Component | Internal structure | Classes, modules in container | | Sequence | Interactions | Request flows, protocols | | Class | Structure | Domain model, relationships | | ER | Data | Database schema | | Flowchart | Process | Algorithms, decisions | | State | Lifecycle | Entity states, transitions |

Mermaid Basics

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

Syntax:

flowchart TD|TB|BT|LR|RL
    id[Rectangle]
    id(Rounded)
    id{Diamond}
    id([Stadium])
    id[[Subroutine]]
    id[(Database)]
    id((Circle))

Sequence Diagram

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database

    C->>A: POST /users
    A->>D: INSERT user
    D-->>A: user_id
    A-->>C: 201 Created

Syntax:

->>   Solid arrow (sync)
-->>  Dashed arrow (async/response)
-)    Open arrow
--)   Dashed open arrow
Note right of A: Note text
loop Loop name
    actions
end
alt Condition
    actions
else Other
    actions
end

Class Diagram

classDiagram
    class Order {
        -OrderId id
        -OrderStatus status
        +confirm() void
        +cancel() void
    }
    class OrderItem {
        -ProductId productId
        -int quantity
    }
    Order "1" *-- "*" OrderItem : contains

Relationships:

<|-- Inheritance
*--  Composition
o--  Aggregation
-->  Association
--   Link
..>  Dependency
..|> Implementation

State Diagram

stateDiagram-v2
    [*] --> Pending
    Pending --> Confirmed : confirm()
    Pending --> Cancelled : cancel()
    Confirmed --> Shipped : ship()
    Confirmed --> Cancelled : cancel()
    Shipped --> Delivered : deliver()
    Delivered --> [*]
    Cancelled --> [*]

ER Diagram

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    ORDER_ITEM }o--|| PRODUCT : references

    USER {
        uuid id PK
        string email UK
        string name
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        string status
    }

Cardinality:

||--|{  One to many
}|--|{  Many to many
||--||  One to one
||--o{  One to zero-or-many

C4 Model

Level 1: Context Diagram

Shows system and external actors.

flowchart TB
    subgraph boundary[System Boundary]
        S[("🖥️ E-Commerce System")]
    end

    U[("👤 Customer")]
    PS[("💳 Payment Service")]
    ES[("📧 Email Service")]

    U -->|"Browse, Order"| S
    S -->|"Process payment"| PS
    S -->|"Send notifications"| ES

Level 2: Container Diagram

Shows deployable units.

flowchart TB
    subgraph boundary[E-Commerce System]
        WA[("🌐 Web App\nReact")]
        API[("⚙️ API\nPHP/Symfony")]
        DB[("🗄️ Database\nPostgreSQL")]
        CACHE[("💾 Cache\nRedis")]
        MQ[("📬 Queue\nRabbitMQ")]
    end

    WA -->|"REST/JSON"| API
    API -->|"SQL"| DB
    API -->|"Cache"| CACHE
    API -->|"Publish"| MQ

Level 3: Component Diagram

Shows internal structure.

flowchart TB
    subgraph api[API Container]
        direction TB
        subgraph presentation[Presentation]
            AC[Action]
            RS[Responder]
        end
        subgraph application[Application]
            UC[UseCase]
            SV[Service]
        end
        subgraph domain[Domain]
            EN[Entity]
            VO[ValueObject]
            RP[Repository Interface]
        end
        subgraph infra[Infrastructure]
            RI[Repository Impl]
            AD[Adapter]
        end
    end

    AC --> UC
    UC --> EN
    UC --> RP
    RI -.-> RP

Best Practices

Diagram Guidelines

| Principle | Description | Example | |-----------|-------------|---------| | 7±2 Rule | Max 5-9 elements | Aggregate related items | | Clear labels | Descriptive names | "User Service" not "S1" | | Consistent style | Same shapes = same type | Rectangles for services | | Flow direction | Top-down or left-right | Pick one per diagram | | Context first | Start high-level | C4 Context → Container |

Naming Conventions

✅ Good:
- "Payment Service" (descriptive)
- "PostgreSQL Database" (specific)
- "POST /orders" (action-based)

❌ Bad:
- "Service A" (meaningless)
- "DB" (ambiguous)
- "Process" (vague)

Layout Tips

# Top-down flow (recommended for hierarchies)
flowchart TD

# Left-right (recommended for timelines)
flowchart LR

# Subgraphs for grouping
subgraph name[Label]
    content
end

# Styling
style id fill:#f9f,stroke:#333
classDef className fill:#f9f
class id1,id2 className

Common Antipatterns

| Antipattern | Problem | Fix | |-------------|---------|-----| | Spaghetti | Too many crossing lines | Reorder, use subgraphs | | Kitchen sink | Everything in one diagram | Split by level/aspect | | Mystery meat | Cryptic labels | Use full names | | Outdated | Doesn't match code | Automate from code | | No legend | Unknown symbols | Add legend/key | | Invisible boundaries | Unclear scope | Add subgraphs |

Tool Comparison

| Tool | Type | Best For | Pros | Cons | |------|------|----------|------|------| | Mermaid | Text-based | Documentation-as-code | Git-friendly, embeds in MD, live preview | Limited styling, complex layouts hard | | PlantUML | Text-based | UML diagrams | Full UML support, more diagram types | Requires Java, slower rendering | | Draw.io | GUI | Quick prototypes, business diagrams | Free, intuitive, many templates | Binary files, merge conflicts | | Excalidraw | GUI | Sketches, whiteboarding | Hand-drawn style, collaborative | Less precise, limited exports | | Lucidchart | GUI | Enterprise, presentations | Professional output, integrations | Paid, not text-based |

Tool Selection Guide

| Scenario | Recommended Tool | |----------|------------------| | Code documentation (README, docs/) | Mermaid | | Strict UML compliance required | PlantUML | | Quick whiteboard session | Excalidraw | | Stakeholder presentations | Draw.io or Lucidchart | | CI/CD pipeline diagrams | Mermaid (auto-generate) | | Living documentation (auto-update) | Mermaid + code generation |

Tool Features Matrix

| Feature | Mermaid | PlantUML | Draw.io | Excalidraw | |---------|---------|----------|---------|------------| | Version control friendly | ✅ | ✅ | ❌ | ⚠️ JSON | | GitHub/GitLab rendering | ✅ | ❌ | ❌ | ❌ | | No install required | ✅ | ❌ | ✅ | ✅ | | Offline support | ⚠️ | ✅ | ✅ | ✅ | | C4 model support | ✅ | ✅ | Manual | Manual | | Export to PNG/SVG | ✅ | ✅ | ✅ | ✅ | | Real-time collaboration | ❌ | ❌ | ✅ | ✅ |

Diagram Selection Guide

What are you documenting?
│
├─ System overview → C4 Context
│
├─ Deployment units → C4 Container
│
├─ Internal structure → C4 Component / Class
│
├─ Data flow
│  ├─ Request/Response → Sequence
│  └─ Data processing → Flowchart
│
├─ Data structure
│  ├─ Domain model → Class
│  └─ Database → ER
│
└─ Behavior
   ├─ State machine → State
   └─ Algorithm → Flowchart

PHP-Specific Diagrams

DDD Layers

flowchart TB
    subgraph presentation[Presentation Layer]
        direction LR
        A[Action]
        R[Responder]
    end

    subgraph application[Application Layer]
        direction LR
        UC[UseCase]
        DTO[DTO]
    end

    subgraph domain[Domain Layer]
        direction LR
        E[Entity]
        VO[Value Object]
        DS[Domain Service]
        RI[Repository Interface]
    end

    subgraph infrastructure[Infrastructure Layer]
        direction LR
        RImpl[Repository]
        Adapter[Adapter]
    end

    presentation --> application
    application --> domain
    infrastructure -.-> domain

CQRS Pattern

flowchart LR
    subgraph commands[Write Side]
        CMD[Command] --> CH[CommandHandler]
        CH --> AR[Aggregate]
        AR --> EV[Event]
    end

    subgraph queries[Read Side]
        Q[Query] --> QH[QueryHandler]
        QH --> RM[ReadModel]
    end

    EV -.-> RM

References

For detailed information, load these reference files:

• references/mermaid-syntax.md — Complete Mermaid syntax reference
• references/c4-model.md — C4 model detailed guide
• references/sequence-patterns.md — Common sequence diagram patterns
• references/diagram-tools.md — Tools and automation