147 lines
4.5 KiB
Markdown
147 lines
4.5 KiB
Markdown
---
|
|
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)
|
|
|
|
## Anti-Placeholder Rule
|
|
|
|
Examples in this skill are illustrative only. Do not reuse placeholder components, services, databases, or relationships unless explicitly required by the PRD. Every element in a Mermaid diagram must be grounded in actual requirements and match the architecture document's content.
|
|
|
|
## 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. |