| name | diagram-patterns |
| description | Mermaid diagram templates for solution architecture, service communication, C4 Context/Container, data flow, agent flow, deployment, and sequence diagrams. Use when generating architecture diagrams. |
Diagram Patterns
Guidelines and templates for generating consistent, readable architecture diagrams using Mermaid syntax. All diagrams in this plugin use Mermaid — never ASCII art.
Canonical Diagram Set
All diagrams live in architecture-output/diagrams/ with these exact filenames.
Every command that generates or exports diagrams reads from and writes to this single folder.
Always Generated (every project)
| Filename | Purpose | Mermaid Type |
|---|
solution-architecture.mmd | Full system topology — clients, ingress, services, queues, databases, external integrations | graph TB |
deployment.mmd | Where each component runs — cloud provider, service tier, region, network boundaries | graph TB |
sequence-auth.mmd | Authentication and session flow — login → token → API → refresh | sequenceDiagram |
Generated When Condition Is Met
| Filename | Condition | Mermaid Type |
|---|
er-diagram.mmd | System has a relational database | erDiagram |
service-communication.mmd | 2+ backend services or modular-monolith with 3+ modules | graph LR |
agent-flow.mmd | System has AI agents or LLM orchestration | graph TD |
sequence-payment.mmd | System has payment processing | sequenceDiagram |
data-flow.mmd | Complex data pipeline or ETL (not just CRUD) | graph LR |
Rules for All Diagrams
- Output folder: always
architecture-output/diagrams/<filename>.mmd
- Hard limit: max 12 nodes per diagram — split into additional files if needed, never cram more in
- Labels: ≤ 5 words per node, technology on a second line with
<br/><i>Tech</i>
- Arrows: every arrow must have a label (protocol, event name, or purpose)
- Types: use
graph TB/LR/TD, sequenceDiagram, or erDiagram only — never C4Context, C4Container, C4Component, or any other C4 Mermaid type
- No nested blocks: never write
keyword(...) { — all node declarations are flat at diagram scope
Diagram Types
| Diagram | When to Use | Mermaid Type |
|---|
| Solution Architecture | Show the full system topology: clients, API gateway, services, queues, databases, storage, external APIs | graph TB |
| Service Communication | Show how microservices/backend services connect to each other with protocols and patterns | graph LR |
| ER Diagram | Show database entities, their fields, and relationships | erDiagram |
| Data Flow | Show how data moves through the system | graph LR |
| Agent Flow | Show AI agent orchestration and tool usage | graph TD |
| Deployment | Show where components run | graph TB |
| Sequence | Show interaction between components over time | sequenceDiagram |
Color Conventions
Use consistent colors across all diagrams:
| Component Type | Color | Mermaid Style |
|---|
| User / Actor | Grey | style ... fill:#e8e8e8,stroke:#999 |
| Frontend | Blue | style ... fill:#4a90d9,stroke:#2c5ea0,color:#fff |
| Backend Service | Green | style ... fill:#5cb85c,stroke:#3d8b3d,color:#fff |
| Database | Orange | style ... fill:#f0ad4e,stroke:#c77c00,color:#fff |
| External Service | Purple | style ... fill:#9b59b6,stroke:#6c3483,color:#fff |
| AI Agent / LLM | Red/Pink | style ... fill:#e74c3c,stroke:#c0392b,color:#fff |
| Message Queue | Teal | style ... fill:#1abc9c,stroke:#16a085,color:#fff |
Solution Architecture Diagram
Shows the full system topology from clients to infrastructure. Always generated for every blueprint. This is the primary "big picture" diagram that non-technical stakeholders see first.
Include all layers: clients (web, mobile), ingress (API gateway, CDN, load balancer), application services (APIs, workers, agents), messaging (queues, event bus), data (databases, cache, search), storage (file/object storage), and external integrations.
graph TB
subgraph "Clients"
WebApp["🌐 Web App<br/><i>Next.js</i>"]
MobileApp["📱 Mobile App<br/><i>React Native / Expo</i>"]
AdminApp["🔧 Admin Dashboard<br/><i>React / Vite</i>"]
end
subgraph "Ingress"
CDN["🌍 CDN<br/><i>Cloudflare</i>"]
Gateway["🚪 API Gateway<br/><i>Kong / AWS ALB / Nginx</i>"]
end
subgraph "Application Services"
API["⚙️ API Server<br/><i>Node.js / Express</i>"]
AuthService["🔐 Auth Service<br/><i>Clerk / Auth0</i>"]
Worker["⏰ Background Worker<br/><i>BullMQ</i>"]
Agent["🤖 AI Agent<br/><i>Python / FastAPI</i>"]
end
subgraph "Messaging"
Queue["📬 Job Queue<br/><i>Redis / BullMQ</i>"]
EventBus["📡 Event Bus<br/><i>Redis Pub/Sub</i>"]
end
subgraph "Data Stores"
DB[("🗄️ Primary Database<br/><i>PostgreSQL</i>")]
Cache[("⚡ Cache<br/><i>Redis</i>")]
Search[("🔍 Search Index<br/><i>Typesense</i>")]
end
subgraph "Storage"
ObjectStore["📦 Object Storage<br/><i>Cloudflare R2</i>"]
end
subgraph "External Services"
Stripe["💳 Stripe"]
Resend["📧 Resend"]
Claude["🤖 Claude API"]
end
WebApp --> CDN
MobileApp --> Gateway
AdminApp --> CDN
CDN --> Gateway
Gateway -->|"REST / GraphQL"| API
Gateway -->|"Auth check"| AuthService
API -->|"Read/write"| DB
API -->|"Cache"| Cache
API -->|"Enqueue jobs"| Queue
API -->|"Publish events"| EventBus
API -->|"Search"| Search
API -->|"Upload/download"| ObjectStore
API -->|"Payments"| Stripe
Queue --> Worker
Worker -->|"Read/write"| DB
Worker -->|"Send emails"| Resend
EventBus --> Agent
Agent -->|"LLM calls"| Claude
Agent -->|"Read/write"| DB
style WebApp fill:#4a90d9,stroke:#2c5ea0,color:#fff
style MobileApp fill:#4a90d9,stroke:#2c5ea0,color:#fff
style AdminApp fill:#4a90d9,stroke:#2c5ea0,color:#fff
style CDN fill:#d4e6f1,stroke:#2c5ea0
style Gateway fill:#d4e6f1,stroke:#2c5ea0
style API fill:#5cb85c,stroke:#3d8b3d,color:#fff
style AuthService fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Worker fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Agent fill:#e74c3c,stroke:#c0392b,color:#fff
style Queue fill:#1abc9c,stroke:#16a085,color:#fff
style EventBus fill:#1abc9c,stroke:#16a085,color:#fff
style DB fill:#f0ad4e,stroke:#c77c00,color:#fff
style Cache fill:#f0ad4e,stroke:#c77c00,color:#fff
style Search fill:#f0ad4e,stroke:#c77c00,color:#fff
style ObjectStore fill:#f39c12,stroke:#d68910,color:#fff
style Stripe fill:#9b59b6,stroke:#6c3483,color:#fff
style Resend fill:#9b59b6,stroke:#6c3483,color:#fff
style Claude fill:#e74c3c,stroke:#c0392b,color:#fff
Adaptation rules:
- Remove layers that don't exist (e.g., no CDN for internal tools, no Agent layer if no AI)
- Add layers as needed (e.g., add "Real-time" subgraph with WebSocket server if the system has real-time features)
- If no API gateway, connect clients directly to services
- If monolith, show a single service box instead of multiple
- Always label arrows with the protocol or purpose
- For simple systems (1 frontend, 1 API, 1 database), collapse into fewer subgraphs but keep the same topology style
Additional color conventions for Solution Architecture:
| Component Type | Color | Mermaid Style |
|---|
| Ingress / Gateway / CDN | Light blue | style ... fill:#d4e6f1,stroke:#2c5ea0 |
| Object / File Storage | Dark orange | style ... fill:#f39c12,stroke:#d68910,color:#fff |
Service Communication Diagram
Shows how backend services, workers, and agents communicate with each other. Generated when the system has 2+ backend services. Focuses on inter-service protocols, sync vs async patterns, and data ownership boundaries.
graph LR
subgraph "Sync (REST/gRPC)"
API["⚙️ API Server"]
UserSvc["👤 User Service"]
OrderSvc["📦 Order Service"]
PaymentSvc["💳 Payment Service"]
NotifSvc["🔔 Notification Service"]
end
subgraph "Async (Events/Queues)"
Queue["📬 Job Queue<br/><i>Redis / BullMQ</i>"]
EventBus["📡 Event Bus<br/><i>Redis Pub/Sub</i>"]
end
subgraph "AI Services"
Agent["🤖 AI Agent"]
end
API -->|"REST: GET /users/:id"| UserSvc
API -->|"REST: POST /orders"| OrderSvc
OrderSvc -->|"REST: POST /payments/charge"| PaymentSvc
OrderSvc -->|"Publish: order.created"| EventBus
EventBus -->|"Subscribe: order.created"| NotifSvc
EventBus -->|"Subscribe: order.created"| Agent
PaymentSvc -->|"Publish: payment.completed"| EventBus
EventBus -->|"Subscribe: payment.completed"| OrderSvc
NotifSvc -->|"Enqueue: send-email"| Queue
Queue -->|"Process"| NotifSvc
style API fill:#5cb85c,stroke:#3d8b3d,color:#fff
style UserSvc fill:#5cb85c,stroke:#3d8b3d,color:#fff
style OrderSvc fill:#5cb85c,stroke:#3d8b3d,color:#fff
style PaymentSvc fill:#5cb85c,stroke:#3d8b3d,color:#fff
style NotifSvc fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Queue fill:#1abc9c,stroke:#16a085,color:#fff
style EventBus fill:#1abc9c,stroke:#16a085,color:#fff
style Agent fill:#e74c3c,stroke:#c0392b,color:#fff
Adaptation rules:
- Show ALL backend services from the manifest, not just core ones
- Label every arrow with the protocol AND the specific endpoint or event name
- Separate sync calls (solid arrows) from async events (dotted arrows where Mermaid supports it, or use different subgraph grouping)
- Group services by domain/bounded context if using modular-monolith or microservices
- Show which service owns which database (use dashed lines to data stores if helpful, but keep the focus on inter-service communication)
- For monolith with internal modules, show module-to-module function calls instead of HTTP/event patterns
- Include retry/circuit-breaker annotations on critical paths:
-->|"REST (retry: 3x, timeout: 5s)"| ServiceB
When to generate this diagram:
- Always: when the system has 2+ backend services or a modular-monolith with 3+ modules
- Skip: for single-service systems (the Solution Architecture diagram is sufficient)
C4 Context Diagram
Shows the system as a single box, with users and external systems around it.
graph TB
User["👤 End User<br/><i>Uses the application</i>"]
Admin["👤 Admin<br/><i>Manages content and users</i>"]
System["🏢 System Name<br/><i>Brief description of what<br/>the system does</i>"]
Email["📧 Email Service<br/><i>SendGrid / Resend</i>"]
Payment["💳 Payment Provider<br/><i>Stripe</i>"]
LLM["🤖 LLM Provider<br/><i>Anthropic Claude</i>"]
User -->|"Uses"| System
Admin -->|"Manages"| System
System -->|"Sends emails via"| Email
System -->|"Processes payments via"| Payment
System -->|"Generates content via"| LLM
style System fill:#4a90d9,stroke:#2c5ea0,color:#fff
style User fill:#e8e8e8,stroke:#999
style Admin fill:#e8e8e8,stroke:#999
style Email fill:#9b59b6,stroke:#6c3483,color:#fff
style Payment fill:#9b59b6,stroke:#6c3483,color:#fff
style LLM fill:#e74c3c,stroke:#c0392b,color:#fff
C4 Container Diagram
Shows the internal structure: frontends, services, databases, and their connections.
graph TB
subgraph "Frontend"
WebApp["🌐 Web App<br/><i>Next.js</i>"]
end
subgraph "Backend"
API["⚙️ API Server<br/><i>Node.js / Express</i>"]
Worker["⏰ Background Worker<br/><i>BullMQ</i>"]
end
subgraph "Data"
DB[("🗄️ PostgreSQL<br/><i>Primary database</i>")]
Cache[("⚡ Redis<br/><i>Cache + queues</i>")]
end
subgraph "External"
Stripe["💳 Stripe"]
Resend["📧 Resend"]
Claude["🤖 Claude API"]
end
WebApp -->|"REST API"| API
API -->|"Reads/writes"| DB
API -->|"Cache + queue"| Cache
Worker -->|"Processes jobs from"| Cache
Worker -->|"Reads/writes"| DB
API -->|"Payments"| Stripe
Worker -->|"Sends emails"| Resend
API -->|"LLM calls"| Claude
style WebApp fill:#4a90d9,stroke:#2c5ea0,color:#fff
style API fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Worker fill:#5cb85c,stroke:#3d8b3d,color:#fff
style DB fill:#f0ad4e,stroke:#c77c00,color:#fff
style Cache fill:#f0ad4e,stroke:#c77c00,color:#fff
style Stripe fill:#9b59b6,stroke:#6c3483,color:#fff
style Resend fill:#9b59b6,stroke:#6c3483,color:#fff
style Claude fill:#e74c3c,stroke:#c0392b,color:#fff
Agent Flow Diagram
Shows how an AI agent processes requests, uses tools, and returns results.
graph TD
Input["📥 User Message"]
Router{"🧭 Intent Router"}
Agent1["🤖 Agent: Researcher<br/><i>Gathers information</i>"]
Agent2["🤖 Agent: Writer<br/><i>Generates content</i>"]
Tool1["🔍 Web Search"]
Tool2["🗄️ Knowledge Base"]
Tool3["📝 Content Generator"]
Guardrails{"🛡️ Guardrails Check"}
Output["📤 Response"]
Input --> Router
Router -->|"Research query"| Agent1
Router -->|"Content request"| Agent2
Agent1 --> Tool1
Agent1 --> Tool2
Agent1 --> Guardrails
Agent2 --> Tool3
Agent2 --> Tool2
Agent2 --> Guardrails
Guardrails -->|"Pass"| Output
Guardrails -->|"Fail"| Agent1
style Input fill:#e8e8e8,stroke:#999
style Router fill:#f0ad4e,stroke:#c77c00,color:#fff
style Agent1 fill:#e74c3c,stroke:#c0392b,color:#fff
style Agent2 fill:#e74c3c,stroke:#c0392b,color:#fff
style Tool1 fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Tool2 fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Tool3 fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Guardrails fill:#1abc9c,stroke:#16a085,color:#fff
style Output fill:#e8e8e8,stroke:#999
Data Flow Diagram
Shows how data moves through the system from input to storage to output.
graph LR
User["👤 User"] -->|"Submits form"| WebApp
WebApp["🌐 Web App"] -->|"POST /api/data"| API
API["⚙️ API Server"] -->|"Validate + transform"| DB
DB[("🗄️ Database")] -->|"Change event"| Queue
Queue["📬 Message Queue"] -->|"Process"| Worker
Worker["⏰ Worker"] -->|"Generate"| LLM
LLM["🤖 LLM"] -->|"Result"| Worker
Worker -->|"Store result"| DB
Worker -->|"Notify"| Email["📧 Email"]
style User fill:#e8e8e8,stroke:#999
style WebApp fill:#4a90d9,stroke:#2c5ea0,color:#fff
style API fill:#5cb85c,stroke:#3d8b3d,color:#fff
style DB fill:#f0ad4e,stroke:#c77c00,color:#fff
style Queue fill:#1abc9c,stroke:#16a085,color:#fff
style Worker fill:#5cb85c,stroke:#3d8b3d,color:#fff
style LLM fill:#e74c3c,stroke:#c0392b,color:#fff
style Email fill:#9b59b6,stroke:#6c3483,color:#fff
Deployment Diagram
Shows where each component is deployed.
graph TB
subgraph "Vercel"
Frontend["🌐 Next.js App"]
Serverless["⚡ API Routes"]
end
subgraph "Railway"
API["⚙️ API Server"]
Worker["⏰ Background Worker"]
end
subgraph "Managed Services"
Supabase[("🗄️ Supabase<br/>PostgreSQL + Auth")]
Upstash[("⚡ Upstash Redis")]
end
subgraph "Third Party"
Stripe["💳 Stripe"]
Claude["🤖 Claude API"]
Resend["📧 Resend"]
end
Frontend --> Serverless
Serverless --> API
API --> Supabase
API --> Upstash
API --> Stripe
API --> Claude
Worker --> Upstash
Worker --> Supabase
Worker --> Resend
style Frontend fill:#4a90d9,stroke:#2c5ea0,color:#fff
style Serverless fill:#4a90d9,stroke:#2c5ea0,color:#fff
style API fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Worker fill:#5cb85c,stroke:#3d8b3d,color:#fff
style Supabase fill:#f0ad4e,stroke:#c77c00,color:#fff
style Upstash fill:#f0ad4e,stroke:#c77c00,color:#fff
style Stripe fill:#9b59b6,stroke:#6c3483,color:#fff
style Claude fill:#e74c3c,stroke:#c0392b,color:#fff
style Resend fill:#9b59b6,stroke:#6c3483,color:#fff
Sequence Diagram
Shows time-ordered interactions between components.
sequenceDiagram
actor User
participant Web as Web App
participant API as API Server
participant DB as Database
participant LLM as Claude API
User->>Web: Submit question
Web->>API: POST /api/chat
API->>DB: Fetch conversation history
DB-->>API: History
API->>LLM: Send prompt + history
LLM-->>API: Stream response
API-->>Web: SSE stream
Web-->>User: Display streaming response
API->>DB: Save conversation
ER Diagram
Shows the database schema: entities, their key fields, and relationships. Generated whenever the system has a relational database.
Use erDiagram type. Include only the core domain entities (max 8) — omit lookup/config tables. Show the relationship cardinality and the foreign key name on each relationship line.
erDiagram
USERS {
uuid id PK
string email UK
string name
timestamp createdAt
}
PROJECTS {
uuid id PK
string name
uuid ownerId FK
enum status
timestamp createdAt
}
TASKS {
uuid id PK
string title
enum status
enum priority
uuid projectId FK
uuid assigneeId FK
date dueDate
timestamp createdAt
}
COMMENTS {
uuid id PK
uuid taskId FK
uuid userId FK
text content
timestamp createdAt
}
USERS ||--o{ PROJECTS : "owns"
USERS ||--o{ TASKS : "assigned to"
USERS ||--o{ COMMENTS : "writes"
PROJECTS ||--o{ TASKS : "contains"
TASKS ||--o{ COMMENTS : "has"
Adaptation rules:
- Only show entities with direct relationships to core domain objects — omit audit logs, config tables, join tables unless they have their own meaningful fields
- List only the most important fields per entity (PK, FKs, status/type enums, 1-2 key data fields) — not every column
- Use standard cardinality notation:
||--o{ (one-to-many), ||--|| (one-to-one), }o--o{ (many-to-many)
Authentication Sequence
Shows the full auth flow. Always generated — every system has authentication.
sequenceDiagram
actor User
participant Web as Web App
participant API as API Server
participant Auth as Auth Service
participant DB as Database
participant Cache as Redis
User->>Web: Submit credentials
Web->>API: POST /auth/login
API->>Auth: Verify credentials
Auth->>DB: Lookup user by email
DB-->>Auth: User record
Auth-->>API: User verified
API->>Cache: Store session / refresh token
API-->>Web: Access token + refresh token
Web-->>User: Redirect to dashboard
Note over Web,Cache: Token refresh flow
Web->>API: POST /auth/refresh (refresh token)
API->>Cache: Validate refresh token
Cache-->>API: Valid
API-->>Web: New access token
Adaptation rules:
- If using OAuth/SSO (Clerk, Auth0, Google): replace
Auth Service with the provider and show the redirect flow
- If using JWT only (no session store): remove the Cache step and show token validation inline in API
- Max 6 participants — collapse internal services if needed
Diagram Rules
- Output location: always write to
architecture-output/diagrams/<canonical-filename>.mmd — never embed diagrams inside markdown files
- Hard node limit: max 12 nodes per diagram — split into a second file rather than cramming more in
- Short labels: ≤ 5 words per node label; technology on a second line with
<br/><i>Tech</i>
- Label every arrow: every connection must have a label (protocol, event name, or purpose) — unlabelled arrows are meaningless
- Use subgraphs to group related components (Frontend, Backend, Data, External, Cloud regions)
- Use icons in node labels for visual scanning: 🌐 web · ⚙️ service · 🗄️ database · 🤖 AI · 💳 payment · 📧 email · ⚡ cache · 📬 queue
- Show direction:
graph TB for hierarchy, graph LR for data/communication flows
- Include technology names: "Next.js" not just "Web App", "PostgreSQL" not just "Database"
- NEVER use C4 Mermaid types: no
C4Context, C4Container, C4Component, C4Dynamic, C4Deployment — use graph TB with subgraphs instead
- No nested block syntax: never write
Container(...) { or any keyword(...) { block — all node declarations are flat
- Sequence diagrams: max 6 participants, max 15 messages — show only the critical path