C4 Architecture

C4 Architecture is an AI skill that guides the creation of software architecture diagrams using the C4 model's four abstraction levels: Context, Containers, Components, and Code. It covers diagram creation at each level, notation standards, Structurizr DSL usage, diagram-as-code workflows, and documentation integration that communicate system architecture clearly to different audiences.

What Is This?

Overview

C4 Architecture provides structured diagramming workflows based on the C4 model created by Simon Brown. It addresses System Context diagrams showing how software fits into the wider environment, Container diagrams revealing technology decisions, Component diagrams detailing internal structure, Code diagrams mapping to implementation, and Structurizr DSL for version-controlled diagram-as-code workflows.

Who Should Use This

This skill serves software architects documenting system designs for stakeholders, developers creating technical documentation for their services, team leads communicating architecture decisions to non-technical audiences, and organizations standardizing their architecture documentation approach.

Why Use It?

Problems It Solves

Architecture diagrams often use inconsistent notation, mix abstraction levels, and become outdated quickly. Box-and-arrow diagrams without a consistent model are ambiguous. Without version-controlled diagrams, documentation diverges from the actual system.

Core Highlights

The C4 model's four levels provide the right amount of detail for each audience: executives see context, developers see components. Structurizr DSL enables diagram-as-code that lives in the repository alongside source code. Consistent notation eliminates ambiguity about what shapes and lines represent. Each level zooms into the previous level for progressive detail disclosure.

How to Use It?

Basic Usage

// Structurizr DSL: System Context and Container diagrams
workspace {
    model {
        customer = person "Customer" "Places orders and tracks deliveries"
        admin = person "Admin" "Manages products and orders"

        ecommerce = softwareSystem "E-Commerce Platform" {
            webapp = container "Web Application" "React SPA" "TypeScript"
            api = container "API Service" "REST API" "Node.js"
            db = container "Database" "Stores orders and products" "PostgreSQL"
            queue = container "Message Queue" "Async processing" "RabbitMQ"
            worker = container "Worker Service" "Processes background jobs" "Node.js"
        }

        payments = softwareSystem "Payment Gateway" "External" "Processes payments"
        email = softwareSystem "Email Service" "External" "Sends notifications"

        customer -> webapp "Browses and orders"
        admin -> webapp "Manages catalog"
        webapp -> api "API calls" "HTTPS/JSON"
        api -> db "Reads/writes" "SQL"
        api -> queue "Publishes events" "AMQP"
        worker -> queue "Consumes events" "AMQP"
        api -> payments "Charges cards" "HTTPS"
        worker -> email "Sends emails" "SMTP"
    }
}

Real-World Examples

// Component diagram for the API Service container
workspace {
    model {
        ecommerce = softwareSystem "E-Commerce Platform" {
            api = container "API Service" {
                router = component "API Router" "Routes HTTP requests" "Express.js"
                authMiddleware = component "Auth Middleware" "Validates JWT tokens"
                orderController = component "Order Controller" "Handles order endpoints"
                productController = component "Product Controller" "Handles product endpoints"
                orderService = component "Order Service" "Order business logic"
                productService = component "Product Service" "Product business logic"
                orderRepo = component "Order Repository" "Database access for orders"
                productRepo = component "Product Repository" "Database access for products"
            }
        }

        router -> authMiddleware "Authenticates requests"
        router -> orderController "Routes order requests"
        router -> productController "Routes product requests"
        orderController -> orderService "Delegates to"
        orderService -> orderRepo "Persists via"
        productController -> productService "Delegates to"
        productService -> productRepo "Persists via"
    }
}

Advanced Tips

Generate diagrams automatically from Structurizr DSL in CI so documentation stays current. Supplement diagrams with prose explaining reasoning behind architectural decisions. Create templates for common patterns so new services get consistent documentation.

When to Use It?

Use Cases

Use C4 Architecture when documenting a new system's architecture for stakeholder review, when creating onboarding materials that explain system structure, when communicating architecture changes in design review meetings, or when standardizing architecture documentation across an organization.

Related Topics

Structurizr tool for rendering C4 diagrams, PlantUML and Mermaid for diagram generation, architecture decision records, documentation-as-code practices, and UML diagramming all complement C4 architecture documentation.

Important Notes

Requirements

Familiarity with the C4 model's four abstraction levels and their intended audiences. Structurizr DSL or an alternative rendering tool for generating diagrams. Understanding of the system being documented at both high and detailed levels.

Usage Recommendations

Do: start with the System Context diagram and work inward to maintain a top-down understanding. Keep each diagram focused on a single abstraction level without mixing levels. Include brief descriptions on every element explaining its purpose.

Don't: create Component diagrams for every container when many are simple and well-understood. Mix infrastructure concerns with application architecture in the same diagram. Create Code-level diagrams unless the implementation mapping is genuinely useful for the audience.

Limitations

The C4 model focuses on static structure and does not directly address runtime behavior, data flow, or deployment architecture. Diagrams require manual updates or CI automation to stay synchronized with code changes. Very large systems may have Container diagrams that are too complex to fit readable on a single page.