Initial commit
This commit is contained in:
Zhongwei Li
500
skills/documentation-architecture/reference/mermaid-diagrams.md
Normal file
500
skills/documentation-architecture/reference/mermaid-diagrams.md
Normal file
@@ -0,0 +1,500 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user