documentation-docusaurus/references/c4-docusaurus.md

C4 Architecture in Docusaurus — Mermaid Syntax Reference

Mermaid (built into Docusaurus via @docusaurus/theme-mermaid) supports C4 diagrams natively.

L1 — C4Context

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

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

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

// 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