432 lines
15 KiB
Markdown
432 lines
15 KiB
Markdown
# Generate 5 Essential Architecture Diagrams in Mermaid.js
|
||
|
||
## Including C4 Level 1, 2, 3, Data Flow, and C4 Deployment
|
||
|
||
---
|
||
|
||
Goal: generate **5 essential architecture diagrams** in Mermaid.js format based on the provided system information.
|
||
|
||
---
|
||
|
||
## Instructions
|
||
|
||
Generate exactly **5 diagrams** in the following order. Each diagram should be complete, syntactically valid Mermaid code ready to render.
|
||
|
||
### Diagram 1: System Context Diagram (C4 Level 1)
|
||
|
||
**Purpose**: Show the big picture - your system in context with external users, systems, and services it connects to.
|
||
|
||
**Output Format**: Use C4Context Mermaid syntax
|
||
|
||
**Requirements**:
|
||
|
||
- Show the primary software system as the central element
|
||
- Include all external users/actors who interact with the system
|
||
- Include all external systems/services the system depends on
|
||
- Label all relationships with interaction descriptions
|
||
- Use clear, descriptive titles and descriptions
|
||
|
||
**Mermaid Syntax Template**:
|
||
|
||
```
|
||
C4Context
|
||
title System Context - [System Name]
|
||
Person(customer, "Customer", "End user of the system")
|
||
System(system, "[System Name]", "Core business functionality")
|
||
System_Ext(external, "External System", "Third-party integration")
|
||
Rel(customer, system, "uses")
|
||
Rel(system, external, "calls API")
|
||
```
|
||
|
||
**Key Elements to Include**:
|
||
|
||
- At least 1-2 external users
|
||
- The primary system (your product)
|
||
- 2-3 external systems/services it depends on
|
||
|
||
---
|
||
|
||
### Diagram 2: Container Diagram (C4 Level 2)
|
||
|
||
**Purpose**: Zoom into the primary system and show its main building blocks (containers) like web apps, APIs, databases, message queues, etc.
|
||
|
||
**Output Format**: Use C4Container Mermaid syntax
|
||
|
||
**Requirements**:
|
||
|
||
- Break down the system into logical containers (applications, services, databases)
|
||
- Show technology choices for each container (e.g., "Node.js API", "PostgreSQL")
|
||
- Show interactions between containers with labels
|
||
- Keep external systems visible but less detailed
|
||
- Include brief descriptions of what each container does
|
||
|
||
**Mermaid Syntax Template**:
|
||
|
||
```
|
||
C4Container
|
||
title Container Diagram - [System Name]
|
||
Person(user, "User", "System end user")
|
||
|
||
System_Boundary(system, "[System Name]") {
|
||
Container(web, "Web Application", "React", "Serves the UI")
|
||
Container(api, "API Server", "Node.js", "Provides API services")
|
||
Container(db, "Database", "PostgreSQL", "Stores application data")
|
||
Container(cache, "Cache", "Redis", "Session and data caching")
|
||
}
|
||
|
||
System_Ext(external, "External Service", "Third-party API")
|
||
|
||
Rel(user, web, "Uses [HTTPS]")
|
||
Rel(web, api, "Calls [REST API]")
|
||
Rel(api, db, "Reads/Writes [SQL]")
|
||
Rel(api, cache, "Reads/Writes")
|
||
Rel(api, external, "Calls [REST API]")
|
||
```
|
||
|
||
**Key Elements to Include**:
|
||
|
||
- 3-5 main containers (apps, APIs, databases, services)
|
||
- Technology stack for each container
|
||
- Container-to-container relationships
|
||
|
||
---
|
||
|
||
### Diagram 3: Component Diagram (C4 Level 3)
|
||
|
||
**Purpose**: Zoom into a specific container and show its internal components/structure (controllers, services, repositories, etc.).
|
||
|
||
**Output Format**: Use C4Component Mermaid syntax
|
||
|
||
**Requirements**:
|
||
|
||
- Focus on ONE important container (usually the API or main service)
|
||
- Show internal components/classes/modules within that container
|
||
- Show technology/framework for each component
|
||
- Show dependencies between components
|
||
- Include clear descriptions of each component's responsibility
|
||
- Keep it focused - don't show every single component, show the main 5-8
|
||
|
||
**Mermaid Syntax Template**:
|
||
|
||
```
|
||
C4Component
|
||
title Component Diagram - [Container Name]
|
||
|
||
Container_Boundary(container, "[Container Name]") {
|
||
Component(ctrl, "API Controller", "Express Router", "Handles HTTP requests")
|
||
Component(service, "Business Service", "Service Class", "Contains business logic")
|
||
Component(repo, "Data Repository", "Data Access Layer", "Database queries")
|
||
Component(auth, "Auth Component", "JWT/OAuth", "Handles authentication")
|
||
Component(email, "Email Component", "Email Service", "Sends emails")
|
||
}
|
||
|
||
ContainerDb(db, "Database", "PostgreSQL", "Persistence")
|
||
System_Ext(email_service, "Email Service", "SendGrid/SMTP")
|
||
|
||
Rel(ctrl, service, "Uses")
|
||
Rel(service, repo, "Uses")
|
||
Rel(service, auth, "Uses")
|
||
Rel(service, email, "Uses")
|
||
Rel(repo, db, "Reads/Writes")
|
||
Rel(email, email_service, "Sends via")
|
||
```
|
||
|
||
**Key Elements to Include**:
|
||
|
||
- 5-8 main internal components
|
||
- Component responsibilities clearly described
|
||
- Dependencies between components
|
||
- External dependencies (databases, services)
|
||
- Focus on one container (usually API/backend service)
|
||
|
||
---
|
||
|
||
### Diagram 4: Data Flow Diagram (DFD)
|
||
|
||
**Purpose**: Show how data moves through the system - from sources, through processes and transformations, to storage and destinations.
|
||
|
||
**Output Format**: Use flowchart syntax with data process symbols
|
||
|
||
**Requirements**:
|
||
|
||
- Identify all data sources (users, external systems)
|
||
- Show major data processing/transformation steps
|
||
- Show all data storage locations (databases, caches, files)
|
||
- Show data destinations (output systems, reports, notifications)
|
||
- Label flows with data type descriptions
|
||
- Use consistent formatting for similar element types
|
||
|
||
**Mermaid Syntax Template**:
|
||
|
||
```
|
||
flowchart LR
|
||
subgraph sources["📥 Data Sources"]
|
||
user["👤 User Input"]
|
||
external["🔗 External APIs"]
|
||
end
|
||
|
||
subgraph processes["⚙️ Data Processing"]
|
||
validation["Validate Data"]
|
||
transform["Transform Data"]
|
||
aggregate["Aggregate Data"]
|
||
end
|
||
|
||
subgraph storage["💾 Data Storage"]
|
||
db["Primary DB<br/>(PostgreSQL)"]
|
||
cache["Cache<br/>(Redis)"]
|
||
archive["Archive<br/>(S3)"]
|
||
end
|
||
|
||
subgraph outputs["📤 Data Outputs"]
|
||
api_out["API Response"]
|
||
report["Reports"]
|
||
notification["Notifications"]
|
||
end
|
||
|
||
user -->|"raw input"| validation
|
||
external -->|"API data"| validation
|
||
validation -->|"valid data"| transform
|
||
transform -->|"structured data"| aggregate
|
||
aggregate -->|"final data"| db
|
||
aggregate -->|"hot data"| cache
|
||
db -->|"queries"| api_out
|
||
cache -->|"session data"| api_out
|
||
db -->|"historical"| report
|
||
aggregate -->|"events"| notification
|
||
db -->|"old data"| archive
|
||
```
|
||
|
||
**Key Elements to Include**:
|
||
|
||
- Data sources (at least 2)
|
||
- Data transformation steps (at least 3)
|
||
- Data storage locations
|
||
- Data destinations
|
||
- Flow labels showing data types
|
||
|
||
---
|
||
|
||
### Diagram 5: Deployment Diagram (C4Deployment)
|
||
|
||
**Purpose**: Show how software components are deployed across physical/cloud infrastructure, environments, and how they're replicated/distributed.
|
||
|
||
**Output Format**: Use C4Deployment Mermaid syntax with Deployment_Node and Node elements
|
||
|
||
**Requirements**:
|
||
|
||
- Show deployment environments (production, staging)
|
||
- Show cloud providers or infrastructure boundaries
|
||
- Show servers/nodes/instances where containers run
|
||
- Show load balancers, databases, and other infrastructure
|
||
- Show internal connections between nodes
|
||
- Indicate scaling and high availability configurations
|
||
- Use proper C4Deployment syntax with Deployment_Node, Node, and Rel
|
||
|
||
**Mermaid Syntax Template**:
|
||
|
||
```mermaid
|
||
C4Deployment
|
||
title <Diagram Title>
|
||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||
Container(<id>, "<Name>", "<Technology>", "<Description>")
|
||
}
|
||
|
||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||
Deployment_Node(<id>, "<Name>", "<Technology>") {
|
||
Container(<id>, "<Name>", "<Technology>", "<Description>")
|
||
}
|
||
}
|
||
|
||
Deployment_Node(<id>, "<Name>", "<Technology/Environment>") {
|
||
Deployment_Node(<id>, "<Name>", "<Technology>") {
|
||
ContainerDb(<id>, "<Name>", "<Technology>", "<Description>")
|
||
}
|
||
}
|
||
|
||
Rel(<source_id>, <target_id>, "<Description>", "<Protocol>")
|
||
Rel_U(<source_id>, <target_id>, "<Description>")
|
||
Rel_R(<source_id>, <target_id>, "<Description>")
|
||
|
||
UpdateRelStyle(<source_id>, <target_id>, $offsetX="<value>", $offsetY="<value>")
|
||
|
||
```
|
||
|
||
**Notes:**
|
||
- Use Deployment_Node for devices, servers, or environments.
|
||
- Use Container for applications or services.
|
||
- Use ContainerDb for databases.
|
||
- Use Rel, Rel_U, or Rel_R for relationships.
|
||
- Use UpdateRelStyle to adjust label or arrow positions.
|
||
|
||
## Example: C4Deployment for Internet Banking System
|
||
|
||
```mermaid
|
||
C4Deployment
|
||
title Deployment Diagram for Internet Banking System - Live
|
||
|
||
Deployment_Node(mob, "Customer's mobile device", "Apple IOS or Android"){
|
||
Container(mobile, "Mobile App", "Xamarin", "Provides a limited subset of the Internet Banking functionality to customers via their mobile device.")
|
||
}
|
||
|
||
Deployment_Node(comp, "Customer's computer", "Microsoft Windows or Apple macOS"){
|
||
Deployment_Node(browser, "Web Browser", "Google Chrome, Mozilla Firefox,<br/> Apple Safari or Microsoft Edge"){
|
||
Container(spa, "Single Page Application", "JavaScript and Angular", "Provides all of the Internet Banking functionality to customers via their web browser.")
|
||
}
|
||
}
|
||
|
||
Deployment_Node(plc, "Big Bank plc", "Big Bank plc data center"){
|
||
Deployment_Node(dn, "bigbank-api*** x8", "Ubuntu 16.04 LTS"){
|
||
Deployment_Node(apache, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||
Container(api, "API Application", "Java and Spring MVC", "Provides Internet Banking functionality via a JSON/HTTPS API.")
|
||
}
|
||
}
|
||
Deployment_Node(bb2, "bigbank-web*** x4", "Ubuntu 16.04 LTS"){
|
||
Deployment_Node(apache2, "Apache Tomcat", "Apache Tomcat 8.x"){
|
||
Container(web, "Web Application", "Java and Spring MVC", "Delivers the static content and the Internet Banking single page application.")
|
||
}
|
||
}
|
||
Deployment_Node(bigbankdb01, "bigbank-db01", "Ubuntu 16.04 LTS"){
|
||
Deployment_Node(oracle, "Oracle - Primary", "Oracle 12c"){
|
||
ContainerDb(db, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||
}
|
||
}
|
||
Deployment_Node(bigbankdb02, "bigbank-db02", "Ubuntu 16.04 LTS") {
|
||
Deployment_Node(oracle2, "Oracle - Secondary", "Oracle 12c") {
|
||
ContainerDb(db2, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
|
||
}
|
||
}
|
||
}
|
||
|
||
Rel(mobile, api, "Makes API calls to", "json/HTTPS")
|
||
Rel(spa, api, "Makes API calls to", "json/HTTPS")
|
||
Rel_U(web, spa, "Delivers to the customer's web browser")
|
||
Rel(api, db, "Reads from and writes to", "JDBC")
|
||
Rel(api, db2, "Reads from and writes to", "JDBC")
|
||
Rel_R(db, db2, "Replicates data to")
|
||
|
||
UpdateRelStyle(spa, api, $offsetY="-40")
|
||
UpdateRelStyle(web, spa, $offsetY="-40")
|
||
UpdateRelStyle(api, db, $offsetY="-20", $offsetX="5")
|
||
UpdateRelStyle(api, db2, $offsetX="-40", $offsetY="-20")
|
||
UpdateRelStyle(db, db2, $offsetY="-10")
|
||
|
||
|
||
```
|
||
|
||
---
|
||
|
||
**Key Elements to Include**:
|
||
|
||
- Cloud provider/infrastructure boundary
|
||
- Production environment with load balancer
|
||
- Multiple instances of compute nodes for high availability
|
||
- Database with read replicas
|
||
- Caching layer
|
||
- External service connections
|
||
- Message queues for async processing
|
||
|
||
---
|
||
|
||
## Input Information Required
|
||
|
||
Before generating the diagrams, gather or confirm the following information about the system:
|
||
|
||
### Project Overview
|
||
|
||
- System name and purpose
|
||
- Primary users/actors
|
||
- Main external systems it integrates with
|
||
|
||
### Technical Components (Containers)
|
||
|
||
- List all applications/services in the system
|
||
- Technology stack for each container (language, framework)
|
||
- Database systems and their purposes
|
||
- Message queues, caches, or other data stores
|
||
- Third-party services (payment, auth, notifications, etc.)
|
||
|
||
### Internal Components (for Level 3)
|
||
|
||
- Main controller/handler types
|
||
- Key service/business logic components
|
||
- Data access/repository layers
|
||
- Utility/helper components
|
||
- Authentication/authorization components
|
||
|
||
### Data Processing
|
||
|
||
- Main data types flowing through the system
|
||
- How data enters the system (APIs, uploads, imports)
|
||
- Major processing/transformation steps
|
||
- How data is stored and how long
|
||
- How data exits the system (exports, reports, APIs)
|
||
|
||
### Infrastructure & Deployment
|
||
|
||
- Cloud provider (AWS, GCP, Azure, on-premises)
|
||
- Number of instances/replicas for high availability
|
||
- Load balancing strategy
|
||
- Database replication/backup strategy
|
||
- CDN or content delivery strategy
|
||
- Message queue setup
|
||
|
||
---
|
||
|
||
## Generation Steps
|
||
|
||
1. **Understand the context**: Read and understand the system description
|
||
2. **Generate Diagram 1**: System Context (C4 Level 1) - showing external relationships
|
||
3. **Generate Diagram 2**: Container (C4 Level 2) - showing internal components and technologies
|
||
4. **Generate Diagram 3**: Component (C4 Level 3) - showing one container's internal structure
|
||
5. **Generate Diagram 4**: Data Flow - showing how data moves through the system
|
||
6. **Generate Diagram 5**: Deployment (C4Deployment) - showing infrastructure and deployment topology
|
||
|
||
---
|
||
|
||
## Output Format
|
||
|
||
For each diagram, output:
|
||
|
||
```markdown
|
||
### Diagram [Number]: [Diagram Title]
|
||
|
||
**Description**: [One sentence about what this diagram shows]
|
||
|
||
**Focus**: [What this diagram emphasizes]
|
||
|
||
\`\`\`mermaid
|
||
[Complete Mermaid diagram code]
|
||
\`\`\`
|
||
```
|
||
|
||
---
|
||
|
||
## Quality Checklist
|
||
|
||
For each diagram, verify:
|
||
|
||
- ✅ Syntax is valid Mermaid.js code
|
||
- ✅ Diagram clearly shows the intended architectural layer
|
||
- ✅ All relationships/connections are labeled
|
||
- ✅ Component descriptions are concise and clear
|
||
- ✅ Technology choices are explicitly shown (where applicable)
|
||
- ✅ No syntax errors or unclosed elements
|
||
- ✅ Diagram is readable and not overcrowded
|
||
- ✅ Follows C4 model conventions for that level
|
||
- ✅ For C4Deployment: Uses proper Deployment_Node, Node, and Rel syntax
|
||
|
||
---
|
||
|
||
## Why All 5 Diagrams?
|
||
|
||
| Diagram | Audience | Detail Level | Purpose |
|
||
| ---------------------- | -------------------------------------- | ---------------- | ------------------------------------------ |
|
||
| **Level 1: Context** | Everyone | Ultra-high level | System boundary and external relationships |
|
||
| **Level 2: Container** | Tech leads, architects, devs | High level | Main technical components |
|
||
| **Level 3: Component** | Senior devs, architects | Mid-level | How one container is built internally |
|
||
| **Data Flow** | Data engineers, backend devs, security | Process level | Data movement and transformations |
|
||
| **Deployment** | DevOps, SRE, ops team | Infrastructure | How it runs in production |
|
||
|
||
---
|
||
|