Diagram Knowledge

Diagram Knowledge Base

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

Diagram Types Overview

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

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

Tool Comparison

Tool Selection Guide

Tool Features Matrix

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