---
name: the-system-mermaid
description: Use when modeling structure, decisions, interactions, states, entities, or relationships with Mermaid.
---

# Mermaid

Use one model per `mermaid` fence and introduce its claim in prose.

## Select the narrowest model

- `flowchart` for bounded structure, dependencies, or decisions.
- `sequenceDiagram` for interactions ordered over time.
- `stateDiagram-v2` for domain states and transitions.
- `erDiagram` for conceptual entities and cardinality.
- `classDiagram` for conceptual static type relationships.

### Flowchart

Use `LR` for a short chain and `TB` for hierarchy or branching.
Separate stable identifiers from quoted human labels.

```mermaid
flowchart LR
  request["Request"] --> policy{"Valid?"}
  policy -->|yes| result["Result"]
  policy -->|no| rejection["Rejection"]
```

### Sequence

Declare participants when their order matters.
Use solid arrows for calls and dashed arrows for replies.
Use `alt` only for a material branch.

```mermaid
sequenceDiagram
  participant C as Client
  participant S as Service
  C->>S: Request
  alt accepted
    S-->>C: Result
  else rejected
    S-->>C: Error
  end
```

### State

Use `[*]` for start or terminal state and label meaningful transitions.
Model domain behavior.

```mermaid
stateDiagram-v2
  [*] --> Draft
  Draft --> Published: approve
  Published --> [*]: retire
```

### Entity relationship

Use singular conceptual entities and label relationships from the first entity's perspective.
Cardinality markers are `o|` zero-or-one, `||` exactly-one, `o{` zero-or-more, and `|{` one-or-more.
Omit storage fields and keys unless the diagram explicitly defines a physical schema.

```mermaid
erDiagram
  ACCOUNT ||--o{ INVOICE : receives
```

### Class

Show conceptual types and relationships only.
Omit members, methods, visibility, generics, and implementation types.

```mermaid
classDiagram
  Client --> Service : uses
```

## Portability

Keep identifiers short, stable, and ASCII; labels may contain human text.
Do not use bare lowercase `end` as a flowchart node or label because Mermaid reserves it.
Split dense diagrams instead of styling around poor structure.

Do not add Mermaid directives, configuration, themes, custom styles, HTML labels, callbacks, clickable nodes, icons, images, or remote assets.