opencode-workflow/skills/generate_mermaid_diagram/SKILL.md

---
name: generate_mermaid_diagram
description: "Produce Mermaid diagrams for system architecture, sequence flows, data flows, event flows, and state machines. A deliverable skill referenced by design-architecture."
---

This skill provides guidance and format requirements for producing Mermaid diagrams within the architecture document.

This is a deliverable skill, not a workflow skill. It is referenced by `design-architecture` when producing visual architecture artifacts.

## Purpose

The Architect must produce Mermaid diagrams to visualize the system architecture. Diagrams are embedded directly in the architecture document within the `## Mermaid Diagrams` section.

## Required Diagrams

The architecture document must contain at minimum:

### 1. System Architecture Diagram

Shows all services, databases, queues, caches, and external integrations and how they connect.

```mermaid
graph TD
    Client[Client App] --> Gateway[API Gateway]
    Gateway --> AuthService[Auth Service]
    Gateway --> OrderService[Order Service]
    OrderService --> OrderDB[(Order DB)]
    OrderService --> EventBus[Event Bus]
    EventBus --> NotificationService[Notification Service]
    NotificationService --> NotificationDB[(Notification DB)]
    AuthService --> AuthDB[(Auth DB)]
    AuthService --> Cache[(Redis Cache)]
```

### 2. Sequence Diagram

Shows the primary happy-path interaction flow between components.

```mermaid
sequenceDiagram
    participant C as Client
    participant GW as API Gateway
    participant Auth as Auth Service
    participant Order as Order Service
    participant DB as Order DB
    participant EventBus as Event Bus

    C->>GW: POST /orders
    GW->>Auth: Validate Token
    Auth-->>GW: Token Valid
    GW->>Order: Create Order
    Order->>DB: Insert Order
    DB-->>Order: Order Created
    Order->>EventBus: Publish OrderCreated
    Order-->>GW: 201 Created
    GW-->>C: Order Response
```

### 3. Data Flow Diagram

Shows how data moves through the system, including transformations and storage points.

```mermaid
graph LR
    A[User Input] --> B[Validation]
    B --> C[Command Handler]
    C --> D[(Write DB)]
    C --> E[Event Publisher]
    E --> F[Event Bus]
    F --> G[Projection Handler]
    G --> H[(Read DB)]
    H --> I[Query API]
```

## Optional Diagrams

Produce these additional diagrams when the architecture requires them:

### Event Flow Diagram

Shows how events propagate through the system.

```mermaid
graph TD
    A[Order Created] --> B[Event Bus]
    B --> C[Inventory Update]
    B --> D[Notification Sent]
    B --> E[Analytics Recorded]
    C --> F[(Inventory DB)]
    D --> G[Email Service]
    E --> H[(Analytics DB)]
```

### State Machine Diagram

Shows entity lifecycle and state transitions.

```mermaid
stateDiagram-v2
    [*] --> Pending: Order Created
    Pending --> Confirmed: Payment Received
    Pending --> Cancelled: Cancel Request
    Confirmed --> Processing: Process Start
    Processing --> Completed: Process Done
    Processing --> Failed: Process Error
    Failed --> Processing: Retry
    Completed --> [*]
    Cancelled --> [*]
```

## Diagram Guidelines

### General Rules
- Use consistent naming conventions across all diagrams
- All components in diagrams must be described in the architecture document text
- No orphan components: every diagram element must appear in the document text
- Use meaningful labels, not abbreviations (unless abbreviation is defined in the document)
- Include external systems when they are part of the data flow

### Component Naming
- Services: PascalCase (e.g., `OrderService`, `AuthService`)
- Databases: PascalCase with DB suffix (e.g., `OrderDB`)
- Queues/Topics: PascalCase descriptive name (e.g., `OrderEventBus`)
- External systems: Descriptive name (e.g., `PaymentGateway`)

### Relationship Labels
- Label all edges/connections with the interaction type
- Use `-->` for synchronous calls
- Use `-.->` for asynchronous messages/events
- Include the protocol or verb when relevant (HTTP, gRPC, AMQP)

## Embedding in Architecture Document

All diagrams must be embedded within the `## Mermaid Diagrams` section of `docs/architecture/{feature}.md` using:

````
```mermaid
graph TD
    ...
```
````

Do NOT produce separate diagram files. All diagrams must be within the single architecture document.