Mermaid Diagrams Reference

Use mermaid +render on a fenced code block. Requires mermaid-cli (mmdc).

Flowchart

```mermaid +render
flowchart LR
    A[Producer] -->|send| B[(Kafka Broker)]
    B -->|poll| C[Consumer]
    B -->|replicate| D[(Broker 2)]
```

Directions: LR (left-right), TD/TB (top-down), BT, RL.

Node shapes: A[Rectangle], B(Rounded), C([Stadium]), D[(Cylinder)], E((Circle)), F{Diamond}, G{{Hexagon}}, H[/Parallelogram/].

Edge types: --> arrow, --- line, -.-> dotted, ==> thick, <--> bidirectional. Labels: -->|text| or -- text -->.

Subgraphs group nodes:

```mermaid +render
flowchart TD
    subgraph Producers
        P1[App 1]
        P2[App 2]
    end
    subgraph Kafka Cluster
        B1[(Broker 1)]
        B2[(Broker 2)]
    end
    P1 --> B1
    P2 --> B2
```

Sequence Diagram

```mermaid +render
sequenceDiagram
    participant C as Client
    participant G as API Gateway
    participant S as Service
    participant DB as Database
    C->>G: HTTP Request
    G->>S: Forward
    activate S
    S->>DB: Query
    DB-->>S: Results
    deactivate S
    S-->>G: Response
    G-->>C: HTTP Response
```

Arrows: ->> solid, -->> dotted, -x cross, -) async open. Blocks: loop, alt/else, opt, par/and, critical, break. Use activate/deactivate or +/- suffixes for activation boxes. autonumber adds sequence numbers. Note right of X: text adds notes.

Class Diagram

```mermaid +render
classDiagram
    class KafkaProducer {
        +Properties config
        +send(ProducerRecord) Future
        +close() void
    }
    class ProducerRecord {
        +String topic
        +K key
        +V value
    }
    KafkaProducer --> ProducerRecord : creates
```

Visibility: + public, - private, # protected, ~ package. Relationships: <|-- inheritance, *-- composition, o-- aggregation, --> association, ..> dependency, ..|> realization.

State Diagram

```mermaid +render
stateDiagram-v2
    [*] --> Created
    Created --> Running : start()
    Running --> Paused : pause()
    Paused --> Running : resume()
    Running --> Stopped : stop()
    Stopped --> [*]
```

Composite states: state Active { ... }. Choice: <<choice>>. Fork/join: <<fork>>, <<join>>.

Entity-Relationship Diagram

```mermaid +render
erDiagram
    TOPIC ||--o{ PARTITION : contains
    PARTITION ||--o{ MESSAGE : stores
    CONSUMER_GROUP ||--o{ CONSUMER : has
    CONSUMER ||--o{ PARTITION : "assigned to"
    TOPIC {
        string name PK
        int partitions
        int replication_factor
    }
```

Cardinality: || exactly one, o| zero or one, }| one or more, o{ zero or more. Line: -- identifying, .. non-identifying.

Other Mermaid Types

Gantt chart: gantt with dateFormat, section, and task declarations. Pie chart: pie title "Title" with "Label" : value entries. Mindmap: mindmap with indentation-based hierarchy. Git graph: gitGraph with commit, branch, merge commands. Journey map: journey with section and tasks scored 1-5.

Theming

Apply via init directive at the top of the block:

```mermaid +render
%%{init: {'theme': 'dark'}}%%
flowchart LR
    A --> B --> C
```

Built-in themes: default, neutral, dark, forest, base. The base theme supports themeVariables for full color customization (hex colors only — color names are silently ignored).

Pitfalls

• The word end as a node name breaks flowcharts — wrap it: e[end]
• No space between node ID and bracket: A[text] not A [text]
• Parentheses in labels need HTML entities: #40; and #41;
• Theme engine only accepts hex colors, not color names
• Use meaningful node IDs (DATABASE not A) for readability