C4 Architecture

by softaworks3027f20f3181No license2.5K starsListed Oct 8, 2026Updated Oct 8, 2026Repository updated 7 months ago

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".

Instructions onlySoftware DevelopmentDocuments & Office
AI-generated overview

Generates C4 model architecture documentation as Mermaid diagrams in markdown files.

What it does
This skill guides an agent through producing software architecture documentation using C4 model diagrams written in Mermaid syntax. It covers context, container, component, dynamic and deployment diagram levels, with element, relationship, boundary and styling syntax references. Output is written to markdown files under docs/architecture/ with a fixed naming convention.
When to use it
Use it when asked to create architecture diagrams, document system architecture, visualize software structure, or produce context, container, component or deployment diagrams. It suits teams needing audience-appropriate architecture documentation.
Requirements
No scripts; instructions and reference markdown files only. The agent needs the ability to read the codebase and write markdown files to docs/architecture/.

C4 Architecture Documentation

Generate software architecture documentation using C4 model diagrams in Mermaid syntax.

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:

LevelDiagram TypeAudienceShowsWhen to Create
1C4ContextEveryoneSystem + external actorsAlways (required)
2C4ContainerTechnicalApps, databases, servicesAlways (required)
3C4ComponentDevelopersInternal componentsOnly if adds value
4C4DeploymentDevOpsInfrastructure nodesFor production systems
-C4DynamicTechnicalRequest 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)

mermaid
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)

mermaid
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")

Component Diagram (Level 3)

mermaid
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)

mermaid
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

mermaid
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 personSystem(alias, "Label", "Description")System_Ext(alias, "Label", "Description")       # External systemSystemDb(alias, "Label", "Description")         # Database systemSystemQueue(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")                        # BidirectionalRel_U(from, to, "Label")                        # UpwardRel_D(from, to, "Label")                        # DownwardRel_L(from, to, "Label")                        # LeftwardRel_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 [blocked] 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):

mermaid
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:

mermaid
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:

mermaid
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

AudienceRecommended Diagrams
ExecutivesSystem Context only
Product ManagersContext + Container
ArchitectsContext + Container + key Components
DevelopersAll levels as needed
DevOpsContainer + Deployment

References

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

Source and attribution

Source:softaworks/agent-toolkitinskills/c4-architectureat commit3027f20

License: No license

Content belongs to its original authors. SourceWeft indexes it from a public repository.

Report or request removal

More from softaworks/agent-toolkit

Writing Clearly And Concisely

softaworks

Applies Strunk's Elements of Style rules and an AI-writing-pattern checklist to make human-facing prose clearer and more concise.

Writing & Content2.5Kupdated 7 months ago

Web To Markdown

softaworks

Converts webpage URLs into clean Markdown using a locally installed web2md CLI with Puppeteer and Readability.

Productivity & Workflow2.5Kupdated 7 months ago

Skill Judge

softaworks

Scores Agent Skill packages against official specifications and best practices, with multi-dimensional ratings and improvement advice.

AI & Agents2.5Kupdated 7 months ago

Ship Learn Next

softaworks

Turns learning content such as transcripts or articles into a Ship-Learn-Next action plan with concrete weekly iterations.

Learning & Education2.5Kupdated 7 months ago

Reducing Entropy

softaworks

Guides an agent to minimize total codebase size by biasing toward deletion and measuring the final code amount.

Software Development2.5Kupdated 7 months ago

Qa Test Planner

softaworks

Generates QA test plans, manual test cases, regression suites, Figma design validations and bug reports.

Includes scripts
Software Development2.5Kupdated 7 months ago

More in Software Development

Playground

anthropics

Featured

Builds self-contained interactive HTML playgrounds with controls, live preview, and copyable prompt output.

Software Development37Kupdated today

M5 Onboard

anthropics

Featured

Provisions M5Stack ESP32 boards by detecting them on USB, flashing UIFlow 2.0 firmware, and installing a MicroPython app bundle.

Software Development37Kupdated today

Cardputer Buddy

anthropics

Featured

Guides iterating on a Cardputer-Adv MicroPython app bundle: adding apps, pushing files over USB-serial, tailing logs, and running REPL commands.

Software Development37Kupdated today

Web Design Guidelines

vercel-labs

Featured

Reviews UI code against Web Interface Guidelines fetched from a remote source and reports findings as file:line entries.

Software Development32Kupdated 5 weeks ago

Vercel React Native Skills

vercel-labs

Featured

React Native and Expo best-practice rules covering list performance, animation, navigation, UI patterns, state, and monorepo setup.

Software Development32Kupdated 5 weeks ago

Vercel React Best Practices

vercel-labs

Featured

Vercel's React and Next.js performance guidelines, organized as 70 rules for writing, reviewing, and refactoring code.

Software Development32Kupdated 5 weeks ago