Advanced C4 Platform

A Claude Code skill for creating and managing C4 architecture diagrams — the industry-standard approach for visualizing software architecture at multiple levels of abstraction. Covers all four C4 levels: System Context, Container, Component, and Code, with support for Structurizr DSL, PlantUML, and Mermaid output.

When to Use This Skill

Choose Advanced C4 Platform when:

• You need to document software architecture at multiple abstraction levels
• You're creating architecture diagrams for technical documentation or presentations
• You want to generate C4 diagrams from code or descriptions using Structurizr DSL
• You need to communicate system architecture to both technical and non-technical stakeholders
• You're reviewing or evolving an existing system's architecture

Consider alternatives when:

• You need UML class or sequence diagrams (use a diagramming skill)
• You want flowcharts or process diagrams (use a draw framework skill)
• You need database schema visualization (use a database design skill)

Quick Start

Copy
# Install the skill
claude install advanced-c4-platform

# Generate a system context diagram
claude "Create a C4 System Context diagram for an e-commerce platform that integrates with Stripe, SendGrid, and a warehouse management system"

# Create container-level architecture
claude "Generate a C4 Container diagram for a microservices-based order management system with API gateway, message queue, and 4 services"

# Document an existing system
claude "Here's our system: React frontend → Next.js API → PostgreSQL + Redis + S3. Create C4 diagrams at all levels"

Core Concepts

C4 Abstraction Levels

Level	What It Shows	Audience	Detail Level
Level 1: System Context	Your system and its external dependencies	Everyone (business + tech)	Lowest
Level 2: Container	Applications, databases, message queues within your system	Technical stakeholders	Medium
Level 3: Component	Internal components/modules within a container	Developers and architects	High
Level 4: Code	Classes, interfaces, and their relationships	Developers only	Highest

Structurizr DSL Syntax

workspace {
    model {
        user = person "User" "A customer of the platform"
        system = softwareSystem "E-Commerce Platform" {
            webapp = container "Web App" "React SPA" "TypeScript"
            api = container "API Server" "REST API" "Node.js"
            db = container "Database" "PostgreSQL" "SQL"
        }
        stripe = softwareSystem "Stripe" "Payment processing" "External"

        user -> webapp "Browses products"
        webapp -> api "Makes API calls" "HTTPS/JSON"
        api -> db "Reads/writes data" "SQL"
        api -> stripe "Processes payments" "HTTPS"
    }
    views {
        systemContext system "Context" {
            include *
            autoLayout
        }
        container system "Containers" {
            include *
            autoLayout
        }
    }
}

Diagram Elements

Element	Symbol	Description
Person	Stick figure	Human user or actor
Software System	Large box	Your system or external dependency
Container	Box within system	Application, database, file system
Component	Box within container	Module, service, controller
Relationship	Arrow with label	Communication path with protocol

Configuration

Parameter	Type	Default	Description
output_format	string	"structurizr"	Format: structurizr, plantuml, mermaid, d2
levels	number[]	[1, 2]	C4 levels to generate: 1, 2, 3, 4
style	string	"default"	Visual style: default, minimal, detailed
include_legend	boolean	true	Include diagram legend
auto_layout	boolean	true	Automatic element positioning

Best Practices

1. Start at Level 1 and work down — Always begin with the System Context diagram. It forces you to identify all external systems and users, which is the most valuable architectural information. Most stakeholders only need Levels 1 and 2.

2. Don't skip to Level 4 — Code-level diagrams (UML class diagrams) become outdated immediately. Levels 1-3 change infrequently and provide lasting value. Only create Level 4 diagrams for critical or complex subsystems.

3. Label relationships with technology — "Makes API calls via HTTPS/JSON" is far more useful than just an unlabeled arrow. Include the protocol, data format, and direction of communication.

4. Use consistent naming — Name containers by what they are, not how they're implemented. "Web Application" is better than "React App" at Level 1. Save technology details for the container description or Level 2.

5. Keep diagrams up to date — Store diagram source (Structurizr DSL) in version control alongside the code. Update diagrams as part of architecture change PRs. Stale diagrams are worse than no diagrams.

Common Issues

Diagrams are too detailed at high levels — Level 1 should have 5-10 elements maximum. If you're showing internal components at the System Context level, you're mixing abstraction levels. Push detail down to lower levels.

Unclear diagram boundaries — Draw a clear boundary around "your system" at each level. External systems and users sit outside the boundary. This makes it obvious what you own vs. what you depend on.

Too many relationships — If every element connects to every other element, the diagram loses its value. Group related relationships, show the primary communication paths, and use supplementary diagrams for specific interaction flows.