91 lines
2.8 KiB
Markdown
91 lines
2.8 KiB
Markdown
# C4 Architecture in Docusaurus — Mermaid Syntax Reference
|
|
|
|
Mermaid (built into Docusaurus via `@docusaurus/theme-mermaid`) supports C4 diagrams natively.
|
|
|
|
## L1 — C4Context
|
|
|
|
```mermaid
|
|
C4Context
|
|
title System Context — My Application
|
|
|
|
Person(user, "User", "Description of the human actor.")
|
|
|
|
System(mySystem, "My System", "What it does in one sentence.")
|
|
|
|
System_Ext(extA, "External System A", "Description")
|
|
System_Ext(extB, "External System B", "Description")
|
|
|
|
Rel(user, mySystem, "Uses")
|
|
Rel(mySystem, extA, "Fetches data", "REST API")
|
|
Rel(mySystem, extB, "Delivers output", "Webhook")
|
|
```
|
|
|
|
## L2 — C4Container
|
|
|
|
```mermaid
|
|
C4Container
|
|
title Container Diagram — My Application
|
|
|
|
Person(user, "User", "Description")
|
|
|
|
System_Boundary(mySystem, "My Application") {
|
|
Container(api, "API Service", "Python / FastAPI", "Handles requests.")
|
|
Container(worker, "Background Worker", "Python / Celery", "Async processing.")
|
|
ContainerDb(db, "Database", "PostgreSQL", "Stores data.")
|
|
Container(notifier, "Notifier", "Python", "Sends notifications.")
|
|
}
|
|
|
|
System_Ext(extA, "External System", "Description")
|
|
|
|
Rel(user, api, "Calls", "HTTPS")
|
|
Rel(api, worker, "Enqueues tasks", "Redis")
|
|
Rel(worker, db, "Reads/writes", "SQL")
|
|
Rel(notifier, extA, "Posts", "Webhook")
|
|
```
|
|
|
|
## L3 — C4Component
|
|
|
|
```mermaid
|
|
C4Component
|
|
title Components — API Service
|
|
|
|
Container_Ext(db, "Database", "PostgreSQL", "Stores data")
|
|
Container_Ext(worker, "Worker", "Celery", "Async tasks")
|
|
|
|
Container_Boundary(api, "API Service") {
|
|
Component(router, "Request Router", "FastAPI", "Routes HTTP requests.")
|
|
Component(authMiddleware, "Auth Middleware", "Python", "Validates tokens.")
|
|
Component(handler, "Request Handler", "Python", "Business logic.")
|
|
Component(repo, "Repository", "SQLAlchemy", "DB access layer.")
|
|
}
|
|
|
|
Rel(router, authMiddleware, "Passes request")
|
|
Rel(authMiddleware, handler, "Authenticated request")
|
|
Rel(handler, repo, "Queries data")
|
|
Rel(repo, db, "SQL", "TCP")
|
|
Rel(handler, worker, "Enqueues task", "Redis")
|
|
```
|
|
|
|
## Sidebar Structure for C4
|
|
|
|
```ts
|
|
// In sidebars.ts — recommended structure per app
|
|
{
|
|
type: 'category',
|
|
label: 'C4 Architecture',
|
|
collapsed: false,
|
|
items: [
|
|
'applications/app-name/c4/context', // L1
|
|
'applications/app-name/c4/containers', // L2
|
|
'applications/app-name/c4/components', // L3
|
|
],
|
|
},
|
|
```
|
|
|
|
## Tips
|
|
|
|
- Each C4 level is a separate `.md` file under `docs/applications/<app>/c4/`
|
|
- Add an `:::info C4 Model — Level N` admonition at the top of each page to explain what the level shows
|
|
- For interactive diagrams (richer layout), use `draw.io` via `docusaurus-plugin-drawio` instead of Mermaid
|
|
- Mermaid C4 is best for quick text-as-code diagrams; drawio is better for polished presentation diagrams
|