opencode-workflow/skills/generate_mermaid_diagram/SKILL.md

name	description
generate_mermaid_diagram	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.

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.

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.

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.

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.

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.