501 lines
10 KiB
Markdown
501 lines
10 KiB
Markdown
# Mermaid Diagram Templates for Architecture Documentation
|
|
|
|
Comprehensive guide to Mermaid diagram types for visualizing system architecture, data flows, and interactions.
|
|
|
|
## Why Mermaid?
|
|
|
|
- **Version Controlled**: Diagrams in code, reviewable in PRs
|
|
- **Always Up-to-Date**: Easy to update alongside code changes
|
|
- **No Image Files**: Rendered dynamically in documentation
|
|
- **GitHub Native**: Renders in README.md and issues
|
|
- **Interactive**: Clickable links, zooming
|
|
|
|
## System Architecture Diagrams
|
|
|
|
### Basic Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Frontend"
|
|
UI[React UI]
|
|
end
|
|
|
|
subgraph "Backend"
|
|
API[FastAPI]
|
|
DB[(PostgreSQL)]
|
|
end
|
|
|
|
UI --> API
|
|
API --> DB
|
|
```
|
|
|
|
### Multi-Tier Architecture
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Client"
|
|
Browser[Web Browser]
|
|
Mobile[Mobile App]
|
|
end
|
|
|
|
subgraph "Edge (Cloudflare)"
|
|
Gateway[API Gateway]
|
|
Cache[KV Cache]
|
|
end
|
|
|
|
subgraph "Application"
|
|
Frontend[TanStack Start]
|
|
Backend[FastAPI]
|
|
end
|
|
|
|
subgraph "Data"
|
|
DB[(PostgreSQL)]
|
|
Redis[(Redis)]
|
|
R2[(Object Storage)]
|
|
end
|
|
|
|
Browser --> Gateway
|
|
Mobile --> Gateway
|
|
Gateway --> Frontend
|
|
Gateway --> Backend
|
|
Gateway --> Cache
|
|
Backend --> DB
|
|
Backend --> Redis
|
|
Backend --> R2
|
|
```
|
|
|
|
### Microservices Architecture
|
|
|
|
```mermaid
|
|
graph LR
|
|
Gateway[API Gateway]
|
|
|
|
subgraph "Services"
|
|
Auth[Auth Service]
|
|
Users[User Service]
|
|
Orders[Order Service]
|
|
Payments[Payment Service]
|
|
end
|
|
|
|
subgraph "Data"
|
|
AuthDB[(Auth DB)]
|
|
UserDB[(User DB)]
|
|
OrderDB[(Order DB)]
|
|
end
|
|
|
|
Gateway --> Auth
|
|
Gateway --> Users
|
|
Gateway --> Orders
|
|
Gateway --> Payments
|
|
|
|
Auth --> AuthDB
|
|
Users --> UserDB
|
|
Orders --> OrderDB
|
|
Payments -.Stripe.-> External[External API]
|
|
```
|
|
|
|
## Sequence Diagrams
|
|
|
|
### Authentication Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
actor User
|
|
participant Browser
|
|
participant Gateway
|
|
participant Auth
|
|
participant DB
|
|
|
|
User->>Browser: Enter credentials
|
|
Browser->>Gateway: POST /auth/login
|
|
Gateway->>Auth: Validate credentials
|
|
Auth->>DB: Query user
|
|
DB-->>Auth: User record
|
|
|
|
alt Valid
|
|
Auth->>Auth: Generate JWT
|
|
Auth-->>Gateway: {token, user}
|
|
Gateway-->>Browser: 200 OK
|
|
Browser-->>User: Redirect
|
|
else Invalid
|
|
Auth-->>Gateway: 401
|
|
Gateway-->>Browser: Error
|
|
Browser-->>User: Show error
|
|
end
|
|
```
|
|
|
|
### API Request Flow
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client
|
|
participant Gateway
|
|
participant Backend
|
|
participant DB
|
|
participant Cache
|
|
|
|
Client->>Gateway: GET /users/123
|
|
Gateway->>Gateway: Validate JWT
|
|
Gateway->>Cache: Check cache
|
|
|
|
alt Cache Hit
|
|
Cache-->>Gateway: User data
|
|
Gateway-->>Client: 200 OK (cached)
|
|
else Cache Miss
|
|
Gateway->>Backend: Forward request
|
|
Backend->>DB: Query user
|
|
DB-->>Backend: User data
|
|
Backend-->>Gateway: Response
|
|
Gateway->>Cache: Store in cache
|
|
Gateway-->>Client: 200 OK
|
|
end
|
|
```
|
|
|
|
### Payment Processing
|
|
|
|
```mermaid
|
|
sequenceDiagram
|
|
participant Client
|
|
participant API
|
|
participant PaymentSvc
|
|
participant Stripe
|
|
participant DB
|
|
|
|
Client->>API: POST /orders
|
|
API->>PaymentSvc: Process payment
|
|
PaymentSvc->>Stripe: Create payment intent
|
|
Stripe-->>PaymentSvc: Payment intent
|
|
PaymentSvc-->>API: Intent created
|
|
API-->>Client: {client_secret}
|
|
|
|
Client->>Stripe: Confirm payment
|
|
Stripe->>PaymentSvc: Webhook: payment.succeeded
|
|
PaymentSvc->>DB: Update order status
|
|
PaymentSvc->>API: Notify completion
|
|
API->>Client: Send confirmation email
|
|
```
|
|
|
|
## Data Flow Diagrams
|
|
|
|
### Order Processing Flow
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
Start[User Creates Order] --> Validate[Validate Data]
|
|
Validate --> Stock{Check Stock}
|
|
|
|
Stock -->|Insufficient| Error[Return Error]
|
|
Stock -->|Available| Reserve[Reserve Items]
|
|
|
|
Reserve --> Payment[Process Payment]
|
|
Payment -->|Failed| Release[Release Items]
|
|
Release --> Error
|
|
|
|
Payment -->|Success| Create[Create Order]
|
|
Create --> Queue[Queue Email]
|
|
Queue --> Cache[Invalidate Cache]
|
|
Cache --> Success[Return Order]
|
|
|
|
Success --> Async[Async: Send Email]
|
|
```
|
|
|
|
### Data Transformation Pipeline
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
Raw[Raw Data] --> Extract[Extract]
|
|
Extract --> Transform[Transform]
|
|
Transform --> Validate{Validate}
|
|
|
|
Validate -->|Invalid| Log[Log Error]
|
|
Validate -->|Valid| Enrich[Enrich Data]
|
|
|
|
Enrich --> Normalize[Normalize]
|
|
Normalize --> Store[(Store in DB)]
|
|
Store --> Index[Update Search Index]
|
|
Index --> Cache[Update Cache]
|
|
```
|
|
|
|
## Entity Relationship Diagrams
|
|
|
|
### Multi-Tenant E-Commerce
|
|
|
|
```mermaid
|
|
erDiagram
|
|
TENANT ||--o{ USER : has
|
|
TENANT ||--o{ ORDER : has
|
|
TENANT ||--o{ PRODUCT : has
|
|
USER ||--o{ ORDER : places
|
|
ORDER ||--|{ ORDER_ITEM : contains
|
|
PRODUCT ||--o{ ORDER_ITEM : included_in
|
|
|
|
TENANT {
|
|
uuid id PK
|
|
string name
|
|
string subdomain UK
|
|
timestamp created_at
|
|
}
|
|
|
|
USER {
|
|
uuid id PK
|
|
uuid tenant_id FK
|
|
string email UK
|
|
string role
|
|
}
|
|
|
|
PRODUCT {
|
|
uuid id PK
|
|
uuid tenant_id FK
|
|
string name
|
|
decimal price
|
|
int stock
|
|
}
|
|
|
|
ORDER {
|
|
uuid id PK
|
|
uuid tenant_id FK
|
|
uuid user_id FK
|
|
decimal total
|
|
string status
|
|
}
|
|
|
|
ORDER_ITEM {
|
|
uuid id PK
|
|
uuid order_id FK
|
|
uuid product_id FK
|
|
int quantity
|
|
decimal unit_price
|
|
}
|
|
```
|
|
|
|
### User Authentication Schema
|
|
|
|
```mermaid
|
|
erDiagram
|
|
USER ||--o{ SESSION : has
|
|
USER ||--o{ API_KEY : has
|
|
USER ||--o{ OAUTH_TOKEN : has
|
|
USER }|--|| USER_PROFILE : has
|
|
|
|
USER {
|
|
uuid id PK
|
|
string email UK
|
|
string hashed_password
|
|
bool email_verified
|
|
}
|
|
|
|
SESSION {
|
|
uuid id PK
|
|
uuid user_id FK
|
|
string token UK
|
|
timestamp expires_at
|
|
}
|
|
|
|
API_KEY {
|
|
uuid id PK
|
|
uuid user_id FK
|
|
string key_hash UK
|
|
string name
|
|
timestamp last_used
|
|
}
|
|
```
|
|
|
|
## State Diagrams
|
|
|
|
### Order State Machine
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Pending: Order Created
|
|
Pending --> Processing: Payment Confirmed
|
|
Pending --> Cancelled: Payment Failed
|
|
|
|
Processing --> Shipped: Fulfillment Complete
|
|
Processing --> Cancelled: Out of Stock
|
|
|
|
Shipped --> Delivered: Tracking Confirmed
|
|
Shipped --> Returned: Customer Return
|
|
|
|
Delivered --> Returned: Return Requested
|
|
Returned --> Refunded: Return Approved
|
|
|
|
Cancelled --> [*]
|
|
Delivered --> [*]
|
|
Refunded --> [*]
|
|
```
|
|
|
|
### User Lifecycle
|
|
|
|
```mermaid
|
|
stateDiagram-v2
|
|
[*] --> Invited: User Invited
|
|
Invited --> Active: Accept Invitation
|
|
Invited --> Expired: 7 Days Passed
|
|
|
|
Active --> Suspended: Policy Violation
|
|
Active --> Inactive: 90 Days No Login
|
|
|
|
Suspended --> Active: Appeal Approved
|
|
Inactive --> Active: User Logs In
|
|
|
|
Active --> Deleted: User Deletes Account
|
|
Suspended --> Deleted: Admin Deletes
|
|
|
|
Expired --> [*]
|
|
Deleted --> [*]
|
|
```
|
|
|
|
## Deployment Diagrams
|
|
|
|
### CI/CD Pipeline
|
|
|
|
```mermaid
|
|
graph LR
|
|
Dev[Feature Branch] -->|PR| CI[GitHub Actions]
|
|
CI -->|Tests| Tests{Tests Pass?}
|
|
|
|
Tests -->|No| Fail[❌ Fail]
|
|
Tests -->|Yes| Build[Build]
|
|
|
|
Build --> Stage[Deploy to Staging]
|
|
Stage -->|Smoke Tests| SmokeTest{Pass?}
|
|
|
|
SmokeTest -->|No| Fail
|
|
SmokeTest -->|Yes| Approve{Manual Approve?}
|
|
|
|
Approve -->|No| Wait[Wait]
|
|
Approve -->|Yes| Canary[Canary Deploy 10%]
|
|
|
|
Canary -->|Monitor| Monitor{Healthy?}
|
|
Monitor -->|No| Rollback[Rollback]
|
|
Monitor -->|Yes| Prod[Deploy 100%]
|
|
```
|
|
|
|
### Multi-Region Deployment
|
|
|
|
```mermaid
|
|
graph TB
|
|
subgraph "Region: US-East"
|
|
USWorker[Cloudflare Workers]
|
|
USDB[(Primary DB)]
|
|
end
|
|
|
|
subgraph "Region: Europe"
|
|
EUWorker[Cloudflare Workers]
|
|
EUDB[(Read Replica)]
|
|
end
|
|
|
|
subgraph "Region: Asia"
|
|
AsiaWorker[Cloudflare Workers]
|
|
AsiaDB[(Read Replica)]
|
|
end
|
|
|
|
subgraph "Global"
|
|
DNS[Global DNS]
|
|
CDN[Cloudflare CDN]
|
|
end
|
|
|
|
DNS --> USWorker
|
|
DNS --> EUWorker
|
|
DNS --> AsiaWorker
|
|
|
|
CDN --> USWorker
|
|
CDN --> EUWorker
|
|
CDN --> AsiaWorker
|
|
|
|
USDB -.replication.-> EUDB
|
|
USDB -.replication.-> AsiaDB
|
|
```
|
|
|
|
## Class Diagrams (TypeScript/Python)
|
|
|
|
### Service Architecture
|
|
|
|
```mermaid
|
|
classDiagram
|
|
class OrderService {
|
|
-repository: OrderRepository
|
|
-payment: PaymentService
|
|
+createOrder(data) Order
|
|
+getOrder(id) Order
|
|
+cancelOrder(id) void
|
|
}
|
|
|
|
class OrderRepository {
|
|
-db: Database
|
|
+save(order) Order
|
|
+findById(id) Order
|
|
+findByUser(userId) Order[]
|
|
}
|
|
|
|
class PaymentService {
|
|
-stripe: StripeClient
|
|
+processPayment(amount) PaymentResult
|
|
+refund(paymentId) void
|
|
}
|
|
|
|
class Order {
|
|
+id: string
|
|
+userId: string
|
|
+total: number
|
|
+status: OrderStatus
|
|
}
|
|
|
|
OrderService --> OrderRepository
|
|
OrderService --> PaymentService
|
|
OrderRepository --> Order
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Keep Diagrams Simple**: One concept per diagram
|
|
2. **Use Subgraphs**: Group related components
|
|
3. **Consistent Naming**: Use same names as code
|
|
4. **Color Coding**: Use colors sparingly for emphasis
|
|
5. **Labels**: Add descriptive labels to edges
|
|
6. **Legend**: Include legend for complex diagrams
|
|
7. **Direction**: LR (left-right) or TB (top-bottom) based on flow
|
|
8. **Update Regularly**: Keep in sync with code changes
|
|
|
|
## Rendering in Documentation
|
|
|
|
### GitHub Markdown
|
|
|
|
````markdown
|
|
```mermaid
|
|
graph TB
|
|
A[Start] --> B[Process]
|
|
B --> C[End]
|
|
```
|
|
````
|
|
|
|
### Docusaurus
|
|
|
|
Install plugin:
|
|
```bash
|
|
npm install @docusaurus/theme-mermaid
|
|
```
|
|
|
|
### MkDocs
|
|
|
|
Install plugin:
|
|
```bash
|
|
pip install mkdocs-mermaid2-plugin
|
|
```
|
|
|
|
## Common Patterns
|
|
|
|
### Request/Response Flow
|
|
Use sequence diagrams with alt/opt for error handling
|
|
|
|
### Data Relationships
|
|
Use ER diagrams with proper cardinality (||--o{)
|
|
|
|
### State Transitions
|
|
Use state diagrams for order status, user lifecycle
|
|
|
|
### System Overview
|
|
---
|
|
|
|
Related: [openapi-patterns.md](openapi-patterns.md) | [documentation-standards.md](documentation-standards.md) | [Return to INDEX](INDEX.md)
|