c4-architecture

C4 Architecture Documentation

Generate architecture documentation using C4 model Mermaid diagrams. Use when asked to create architecture diagrams, document system architecture, visualize software structure, create C4 diagrams, or generate context/container/component/deployment diagrams. Triggers include "architecture diagram", "C4 diagram", "system context", "container diagram", "component diagram", "deployment diagram", "document architecture", "visualize architecture".

Workflow

1. Understand scope — Determine which C4 level(s) are needed based on audience
2. Analyze codebase — Explore the system to identify components, containers, and relationships
3. Generate diagrams — Create Mermaid C4 diagrams at appropriate abstraction levels
4. Document — Write diagrams to markdown files with explanatory context

C4 Diagram Levels

Select the appropriate level based on the documentation need:

Level	Diagram Type	Audience	Shows	When to Create
1	C4Context	Everyone	System + external actors	Always (required)
2	C4Container	Technical	Apps, databases, services	Always (required)
3	C4Component	Developers	Internal components	Only if adds value
4	C4Deployment	DevOps	Infrastructure nodes	For production systems
-	C4Dynamic	Technical	Request flows (numbered)	For complex workflows

Key Insight: "Context + Container diagrams are sufficient for most software development teams." Only create Component/Code diagrams when they genuinely add value.

Quick Start Examples

System Context (Level 1)

C4Context
  title System Context - Workout Tracker

  Person(user, "User", "Tracks workouts and exercises")
  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")

  Rel(user, app, "Uses")
  Rel(app, browser, "Persists data to", "IndexedDB")

Container Diagram (Level 2)

When the request names apps, services, workers, databases, or queues, draw each name as exactly one element: Container for an app, service, or worker; ContainerDb for a database or store; ContainerQueue for a queue or topic. Put that name in the label. Do not make it a Container_Boundary and do not invent inner containers or components. Pass only element aliases to Rel, never a boundary alias. Keep the request's direction: A calls B, A writes to B, A reads B, A pulls from B, A drains B, and from A to B are all Rel(a, b, ...).

C4Container
  title Container Diagram - Checkout

  Container(shop, "Basket App", "React", "Places orders")
  Container(api, "Catalog API", "Java", "Accepts orders")
  ContainerDb(db, "Catalog DB", "PostgreSQL", "Product rows")
  ContainerQueue(bus, "Price Queue", "Kafka", "Price events")
  Container(worker, "Index Worker", "Java", "Updates search")

  Rel(shop, api, "Sends orders to", "JSON/HTTPS")
  Rel(api, db, "Writes to", "JDBC")
  Rel(api, bus, "Publishes to")
  Rel(bus, worker, "Delivers events to")

The workout diagram below breaks one app into internal containers. For a list of named containers, use the flat form above.

C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

Named parts are elements, not boundaries. On C4Container, each app, service, worker, portal, console, screen, database, store, and queue the user names is one element. Put that exact name in the label:

• app, service, worker, portal, console, or screen → Container(alias, "Name", "tech", "description")
• database or store → ContainerDb(alias, "Name", "tech", "description")
• queue or topic → ContainerQueue(alias, "Name", "tech", "description")

Do not declare that name as Container_Boundary and do not nest Components under it. A boundary cannot be a Rel endpoint. Aim the arrow with the sentence: "A calls B" / "A writes to B" → Rel(a, b, "..."); "events flow from the queue to the worker" → Rel(queue, worker, "..."); "the worker pulls or drains the queue" → Rel(worker, queue, "...").

C4Container
  title Container Diagram - Parcel Desk
  Container(desk, "Desk App", "React", "Creates bookings")
  Container(api, "Booking API", "Go", "Reads and writes bookings")
  ContainerDb(db, "Booking DB", "PostgreSQL", "Booking records")
  ContainerQueue(q, "Job Queue", "SQS", "Booking events")
  Container(worker, "Ticket Worker", "Go", "Issues tickets")
  Rel(desk, api, "Calls", "JSON/HTTPS")
  Rel(api, db, "Reads and writes", "SQL")
  Rel(api, q, "Publishes events to")
  Rel(q, worker, "Delivers events to")

A container diagram declares each named app, service, worker, database, queue, or external system once: Container, ContainerDb, ContainerQueue, or Container_Ext, with that name as the label. Rel may use only those aliases, or Person for a human. Never pass a Container_Boundary, System_Boundary, or Deployment_Node alias — above, arrows go to spa, not app. Do not replace a named container with a boundary that holds some other element.

Invalid: Container_Boundary(api, "Checkout API") { Container(handler, "Handler", "Node", "Handles calls") } then Rel(shop, api, "Calls"). Valid: Container(shop, "Storefront", "React", "Takes orders"), Container(api, "Checkout API", "Node.js", "Validates orders"), ContainerDb(db, "Catalog DB", "PostgreSQL", "Product rows"), Rel(shop, api, "Submits orders", "JSON/HTTPS"), Rel(api, db, "Reads", "SQL").

Component Diagram (Level 3)

C4Component
  title Component Diagram - Workout Feature

  Container(views, "Views", "Vue Router pages")

  Container_Boundary(workout, "Workout Feature") {
    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
    Component(useTimer, "useTimer", "Composable", "Timer state machine")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
  }

  Rel(views, useWorkout, "Uses")
  Rel(useWorkout, useTimer, "Controls")
  Rel(useWorkout, workoutRepo, "Saves to")

Dynamic Diagram (Request Flow)

C4Dynamic
  title Dynamic Diagram - User Sign In Flow

  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
  Container(spa, "Single-Page App", "React", "Banking UI")

  Container_Boundary(api, "API Application") {
    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
    Component(security, "Security Service", "JWT", "Validates credentials")
  }

  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
  Rel(signIn, security, "2. Validate")
  Rel(security, db, "3. Query user", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

Deployment Diagram

C4Deployment
  title Deployment Diagram - Production

  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web application")
  }

  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
      Container(api, "API Service", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "Database", "PostgreSQL", "Application data")
    }
  }

  Rel(spa, api, "API calls", "HTTPS")
  Rel(api, db, "Reads/writes", "JDBC")

Element Syntax

People and Systems

Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")       # External person
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # External system
SystemDb(alias, "Label", "Description")         # Database system
SystemQueue(alias, "Label", "Description")      # Queue system

Containers

Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")

Components

Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")

Boundaries

Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Boundary(alias, "Label", "type") { ... }

Relationships

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")                        # Bidirectional
Rel_U(from, to, "Label")                        # Upward
Rel_D(from, to, "Label")                        # Downward
Rel_L(from, to, "Label")                        # Leftward
Rel_R(from, to, "Label")                        # Rightward

Deployment Nodes

Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # Shorthand

Styling and Layout

Layout Configuration

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

• $c4ShapeInRow — Number of shapes per row (default: 4)
• $c4BoundaryInRow — Number of boundaries per row (default: 2)

Element Styling

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

Relationship Styling

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

Use $offsetX and $offsetY to fix overlapping relationship labels.

Best Practices

Essential Rules

1. Every element must have: Name, Type, Technology (where applicable), and Description
2. Use unidirectional arrows only — Bidirectional arrows create ambiguity
3. Label arrows with action verbs — "Sends email using", "Reads from", not just "uses"
4. Include technology labels — "JSON/HTTPS", "JDBC", "gRPC"
5. Stay under 20 elements per diagram — Split complex systems into multiple diagrams

Clarity Guidelines

1. Start at Level 1 — Context diagrams help frame the system scope
2. One diagram per file — Keep diagrams focused on a single abstraction level
3. Meaningful aliases — Use descriptive aliases (e.g., orderService not s1)
4. Concise descriptions — Keep descriptions under 50 characters when possible
5. Always include a title — "System Context diagram for [System Name]"

What to Avoid

See references/common-mistakes.md for detailed anti-patterns:

• Confusing containers (deployable) vs components (non-deployable)
• Modeling shared libraries as containers
• Showing message brokers as single containers instead of individual topics
• Adding undefined abstraction levels like "subcomponents"
• Removing type labels to "simplify" diagrams

Microservices Guidelines

Single Team Ownership

Model each microservice as a container (or container group):

C4Container
  title Microservices - Single Team

  System_Boundary(platform, "E-commerce Platform") {
    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
  }

Multi-Team Ownership

Promote microservices to software systems when owned by separate teams:

C4Context
  title Microservices - Multi-Team

  Person(customer, "Customer", "Places orders")
  System(orderSystem, "Order System", "Team Alpha")
  System(inventorySystem, "Inventory System", "Team Beta")
  System(paymentSystem, "Payment System", "Team Gamma")

  Rel(customer, orderSystem, "Places orders")
  Rel(orderSystem, inventorySystem, "Checks stock")
  Rel(orderSystem, paymentSystem, "Processes payment")

Event-Driven Architecture

Show individual topics/queues as containers, NOT a single "Kafka" box:

C4Container
  title Event-Driven Architecture

  Container(orderService, "Order Service", "Java", "Creates orders")
  Container(stockService, "Stock Service", "Java", "Manages inventory")
  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")
  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")

  Rel(orderService, orderTopic, "Publishes to")
  Rel(stockService, orderTopic, "Subscribes to")
  Rel(stockService, stockTopic, "Publishes to")
  Rel(orderService, stockTopic, "Subscribes to")

Output Location

Write architecture documentation to docs/architecture/ with naming convention:

• c4-context.md — System context diagram
• c4-containers.md — Container diagram
• c4-components-{feature}.md — Component diagrams per feature
• c4-deployment.md — Deployment diagram
• c4-dynamic-{flow}.md — Dynamic diagrams for specific flows

Audience-Appropriate Detail

Audience	Recommended Diagrams
Executives	System Context only
Product Managers	Context + Container
Architects	Context + Container + key Components
Developers	All levels as needed
DevOps	Container + Deployment

References

• references/c4-syntax.md — Complete Mermaid C4 syntax
• references/common-mistakes.md — Anti-patterns to avoid
• references/advanced-patterns.md — Microservices, event-driven, deployment