| name | system-design |
| description | Creates system design diagrams in Mermaid (.mmd) following the project's architecture color standard. Use when the user asks to create a system design, architecture diagram, or infrastructure diagram for a project. |
| allowed-tools | Read, Write, Edit, Glob, Grep, Bash |
| user-invocable | true |
System Design Diagram Generator
You create system design / architecture diagrams in Mermaid syntax (.mmd) following a strict visual standard with colored subgraphs and nodes.
Input
The user may provide a project name or description as argument: $ARGUMENTS
If no arguments are provided, ask the user what system they want to diagram.
Color Palette Reference
Subgraph (area) backgrounds
| Area | Fill | Stroke |
|---|
| Frontend | #e8f4fd | #61DAFB |
| API | #ede7f6 | #512BD4 |
| Messaging | #fff8e1 | #f7b731 |
| External Services | #f8d7da | #dc3545 |
Node fills
| Type | Fill | Stroke | Text |
|---|
| Web site / web app | #2980b9 | #1a5276 | #fff |
| Mobile app | #e74c3c | #c0392b | #fff |
| Package / lib (NuGet, NPM) | #c0392b | #96281B | #fff |
| .NET Controller / service | #512BD4 | #3a1d9e | #fff |
| GraphQL / special feature | #E10098 | #b3007a | #fff |
| Messaging server (RabbitMQ, etc) | #f7b731 | #d4991a | #000 |
| Database | #336791 | #264d6e | #fff |
| Internal microservice | #28a745 | #1e7e34 | #fff |
| External API / service | #dc3545 | #c0392b | #fff |
| Background worker | #f7b731 | #d4991a | #000 |
Link style
linkStyle default stroke:#999,stroke-width:2px
Architecture Rules
1. Frontend Area (light blue background)
- Subgraph name:
Frontend
- Style:
fill:#e8f4fd,stroke:#61DAFB,color:#000
- Inside, color each node by type:
- Web sites / web apps → blue (
#2980b9)
- Mobile apps → light red (
#e74c3c)
- Packages / libs (NuGet, NPM) → dark red (
#c0392b)
- Frontend connects to the API via REST, GraphQL, or WebSocket (label the edge)
2. API Area (very light purple background)
- Subgraph name:
API (with label if needed, e.g., API["API Layer"])
- Style:
fill:#ede7f6,stroke:#512BD4,color:#000
- For .NET projects, create one node per Controller (purple
#512BD4)
- Special features (auth handler, middleware, etc.) get a different color within the area
- Controllers that access a database → arrow to the DB node
- Controllers that call external services or microservices → arrow to that service
3. Messaging Area (yellow background) — only if the system uses queues
- Subgraph name:
Messaging
- Style:
fill:#fff8e1,stroke:#f7b731,color:#000
- Place the messaging server node inside (e.g., RabbitMQ)
- On the arrow TO the server, write the queue or exchange name
- Background workers/consumers also go here
4. Database — standalone (no subgraph)
- Use cylinder shape:
DB[("PostgreSQL")]
- Style:
fill:#336791,stroke:#264d6e,color:#fff
- Placed outside any subgraph
5. External Services Area (light red background)
- Subgraph name:
External (with label External["External Services"])
- Style:
fill:#f8d7da,stroke:#dc3545,color:#000
- Inside:
- Internal microservices (NAuth, zTools, NNews, etc.) → green (
#28a745)
- External APIs / third-party services (Stripe, AbacatePay, Twitter, etc.) → red (
#dc3545)
- On arrows to internal microservices, specify what will be used (e.g.,
|"Email"|, |"S3"|, |"Auth"|, |"IA"|)
6. Click callbacks
- Only internal microservices (green nodes like NAuth, zTools, NNews, BazzucaMedia, Lofn, ProxyPay) get click callbacks:
click NodeId mermaidCallback "NodeId"
- Do NOT add click callbacks to frontend apps, API controllers/services, databases, external APIs, background workers, or any other non-microservice node
- This enables diagram navigation — clicking a microservice navigates to its own system design diagram
7. General rules
- Direction:
graph TD (top-down)
- No emojis in labels
- Use meaningful node IDs (not A, B, C)
- Label all arrows with the protocol, action, or purpose
- Always end with
linkStyle default stroke:#999,stroke-width:2px
Output Location
- Default directory:
emagine-site/src/data/diagrams/
- File name:
<project-slug>.mmd (kebab-case)
- Only generate the
.mmd file (no PNG needed — the site renders Mermaid directly)
Complete Example
Below is a full example for a payment proxy system with React frontend, GraphQL API, background workers, and external services:
graph TD
subgraph Frontend
FrontendApp["Frontend React"]
end
subgraph API["API Layer"]
GraphQL["GraphQL API (HotChocolate)"]
StoreSvc["Store Service"]
ProductSvc["Product Service"]
OrderSvc["Order Service"]
InvoiceSvc["Invoice Service"]
PaymentProxy["Payment Proxy"]
end
subgraph Messaging
BgService["Background Service"]
end
subgraph External["External Services"]
NAuth["NAuth"]
AbacatePay["AbacatePay"]
zTools["zTools"]
end
DB[("PostgreSQL")]
FrontendApp -->|"GraphQL"| GraphQL
GraphQL --> StoreSvc
GraphQL --> ProductSvc
GraphQL --> OrderSvc
GraphQL --> InvoiceSvc
InvoiceSvc -->|"Payment"| PaymentProxy
PaymentProxy -->|"Gateway"| AbacatePay
GraphQL -->|"Auth"| NAuth
BgService -->|"Jobs"| OrderSvc
BgService -->|"Jobs"| InvoiceSvc
StoreSvc -->|"CRUD"| DB
ProductSvc -->|"CRUD"| DB
OrderSvc -->|"CRUD"| DB
InvoiceSvc -->|"CRUD"| DB
GraphQL -->|"Utils"| zTools
click NAuth mermaidCallback "NAuth"
click zTools mermaidCallback "zTools"
style FrontendApp fill:#2980b9,stroke:#1a5276,color:#fff
style GraphQL fill:#E10098,stroke:#b3007a,color:#fff
style StoreSvc fill:#512BD4,stroke:#3a1d9e,color:#fff
style ProductSvc fill:#512BD4,stroke:#3a1d9e,color:#fff
style OrderSvc fill:#512BD4,stroke:#3a1d9e,color:#fff
style InvoiceSvc fill:#512BD4,stroke:#3a1d9e,color:#fff
style PaymentProxy fill:#512BD4,stroke:#3a1d9e,color:#fff
style BgService fill:#f7b731,stroke:#d4991a,color:#000
style NAuth fill:#28a745,stroke:#1e7e34,color:#fff
style AbacatePay fill:#dc3545,stroke:#c0392b,color:#fff
style zTools fill:#28a745,stroke:#1e7e34,color:#fff
style DB fill:#336791,stroke:#264d6e,color:#fff
style Frontend fill:#e8f4fd,stroke:#61DAFB,color:#000
style API fill:#ede7f6,stroke:#512BD4,color:#000
style Messaging fill:#fff8e1,stroke:#f7b731,color:#000
style External fill:#f8d7da,stroke:#dc3545,color:#000
linkStyle default stroke:#999,stroke-width:2px
Instructions
Phase 1 — Understand the System
- If the user specifies a project, look for its GitHub repos or existing code to understand the architecture
- Identify: frontend type, API type, controllers/services, databases, external services, messaging
- Ask clarifying questions only if the architecture is ambiguous
Phase 2 — Create the Diagram
- Build the Mermaid diagram following all rules above
- Write the
.mmd file to the output directory
- Ensure every node has a click callback and proper styling
Phase 3 — Confirm
Report the file path and a brief summary of the diagram structure.
Critical Rules
- ALWAYS follow the color palette — do not invent new colors
- ALWAYS use subgraphs to group related components
- ONLY add click callbacks to internal microservices (green nodes) — never to frontend, API, DB, external, or worker nodes
- ALWAYS label arrows with protocol, action, or purpose
- NO emojis in any label
- Database nodes are standalone — never inside a subgraph
- Internal microservices are green, external APIs are red — never mix these
- Frontend web apps are blue, mobile apps are light red, packages are dark red — always distinguish
- Every diagram ends with
linkStyle default stroke:#999,stroke-width:2px
