Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

C4 Architecture Documentation · davila7 | DecimalAI

davila7/c4-architecture

SkillScore73Maintained

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

Documentationby davila7

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Doc Ops pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/davila7-c4-architecture/SKILL.md

decimalai skills pull davila7-c4-architecture --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/davila7-c4-architecture/SKILL.md https://app.decimal.ai/s/davila7-c4-architecture/SKILL.md

Raw file: /s/davila7-c4-architecture/SKILL.md ↗ · machine-readable summary at /s/davila7-c4-architecture.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 47d ago

—+84% tokens0% turns73% of whole cases pass with skill (16/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-02	✗→✓	▲ Improved	71%	0%
case-08	✗→✓	▲ Improved	75%	0%
case-09	✗→✓	▲ Improved	160%	0%
case-11	✗→✓	▲ Improved	-1%	0%
case-13	✗→✓	▲ Improved	82%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

davila7 / claude-code-templates

cli-tool/components/skills/creative-design/c4-architecture/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1Bundled 3 files

Skill contents

references/

SKILL.md

C4 Architecture Documentation

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

Workflow

Understand scope - Determine which C4 level(s) are needed based on audience
Analyze codebase - Explore the system to identify components, containers, and relationships
Generate diagrams - Create Mermaid C4 diagrams at appropriate abstraction levels
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)

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

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

Clarity Guidelines

Start at Level 1 - Context diagrams help frame the system scope
One diagram per file - Keep diagrams focused on a single abstraction level
Meaningful aliases - Use descriptive aliases (e.g., orderService not s1)
Concise descriptions - Keep descriptions under 50 characters when possible
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):

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

| 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

Illustrative Want to see what davila7/c4-architecture would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/11/2026, 22:05 UTC · 22 cases

Measured on 21 comparable cases — below the 22 needed to publish a lift, so this result is shown here but not on the registry card or leaderboard.

Lift

+32%

73% vs 41%

Agent turns

1.0 vs 1.0

Tokens

+84%

4,428.29 vs 2,412.9

fail → pass · 9pass → pass · 7fail → fail · 4pass → fail · 2

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 I need architectural diagrams for our e-commerce platform. Please inspect our project structure and produce comprehensive C4 architecture documentation with Mermaid syntax embedded in markdown files. Make sure to capture the overall system boundaries, application containers, data stores, and interaction flows where appropriate.	fail→fail	1,641	2,580	+57%	1	1	0%	238	2,890	+1114%	0	0	—
case-02 We are building an event-driven logistics application with multiple services communicating via messaging queues. Generate C4 model documentation rendered in Mermaid format as markdown files. I'd like to see the high-level ecosystem, backend runtime services, event queues, and deployment topology clearly mapped out.	fail→pass	23,468	26,781	+14%	1	1	0%	4,723	8,069	+71%	0	0	—
case-03 Please document our mobile fitness app and backend API using C4 model diagrams formatted with Mermaid inside markdown documents. Produce visual architecture documentation suited for both technical and non-technical stakeholders, illustrating external users, client applications, database layers, and key request flows.	pass→pass	30,788	26,377	-14%	1	1	0%	6,001	8,184	+36%	0	0	—
case-04 We decided to adopt PostgreSQL over MongoDB for our primary database due to relational data integrity needs. Document this choice as a Markdown Architecture Decision Record covering context, decision, and consequences.	pass→fail	10,501	10,298	-2%	1	1	0%	1,850	4,305	+133%	0	0	—
case-05 Draft an OpenAPI 3.0 specification in YAML format for our user management endpoint, including POST /users with request body schema and 201 created response.	pass→pass	8,040	9,808	+22%	1	1	0%	1,912	5,249	+175%	0	0	—
case-06 Perform a STRIDE threat model security analysis for our user authentication service, identifying potential threats across Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, and Elevation of Privilege.	pass→fail	19,315	23,317	+21%	1	1	0%	3,826	7,213	+89%	0	0	—
case-07 We have an order service, inventory service, and payment service all owned and maintained by our single core backend team. Create the container level documentation in Markdown format showing these services and their databases.	pass→pass	14,539	10,242	-30%	1	1	0%	2,820	4,608	+63%	0	0	—
case-08 Our enterprise platform consists of three separate backend systems owned by independent engineering teams: Team Alpha (Orders), Team Beta (Inventory), and Team Gamma (Payments). Model how these top-level systems interact in a high-level overview diagram in Markdown.	fail→pass	11,811	5,782	-51%	1	1	0%	2,128	3,730	+75%	0	0	—
case-09 In our payment processing system, the Checkout Service publishes payment.initiated and payment.completed messages to Apache Kafka, which the Notification and Billing services consume. Create a diagram showing these messaging interactions in Markdown.	fail→pass	7,635	7,065	-7%	1	1	0%	1,544	4,022	+160%	0	0	—
case-10 Map out our production AWS infrastructure where our React frontend runs in customer browsers, our Node.js API runs in ECS Fargate, and our PostgreSQL database runs in RDS us-east-1. Output the infrastructure diagram in Markdown.	fail→fail	17,830	9,260	-48%	1	1	0%	3,448	4,591	+33%	0	0	—
case-11 Document the internal code components of our workout tracking feature, which includes a useWorkout composable, a useTimer state machine, and a WorkoutRepository data persistence layer inside our Vue single-page application.	fail→pass	19,411	8,406	-57%	1	1	0%	4,315	4,280	-1%	0	0	—
case-12 Show the step-by-step request flow when a user signs in: SPA submits credentials to Sign In Controller, Controller validates with Security Service, and Security Service queries the PostgreSQL database. Format this sequence as an architecture diagram in Markdown.	fail→fail	5,907	4,751	-20%	1	1	0%	1,288	3,656	+184%	0	0	—
case-13 When rendering our dynamic API workflow diagram in Mermaid, the text labels on the arrow between the web app and API controller overlap visually with adjacent shapes. Show how to fix label positions and apply blue text styling on that link.	fail→pass	10,534	4,059	-61%	1	1	0%	1,942	3,533	+82%	0	0	—
case-14 Our container diagram has 8 service containers inside a boundary, causing Mermaid to wrap them into an overly wide 4-per-row layout. Show how to configure the C4 layout so that shapes render 3 per row and boundaries render 1 per row.	fail→pass	13,642	3,167	-77%	1	1	0%	2,705	3,353	+24%	0	0	—
case-15 We are presenting our platform architecture to non-technical executive stakeholders who only care about external actors, high-level system boundaries, and external third-party integrations. Which diagram level should we generate and what syntax block should be used?	pass→pass	6,794	5,437	-20%	1	1	0%	1,276	3,627	+184%	0	0	—
case-16 Our DevOps engineers need architectural documentation specifically showing physical/cloud infrastructure nodes, AWS regions, ECS clusters, and database instances. Which diagram levels are recommended and what markdown file names should store them?	fail→pass	11,284	6,152	-45%	1	1	0%	2,199	3,916	+78%	0	0	—
case-17 In our core system diagram, we need to represent an external human customer using our platform, along with an external third-party payment gateway service like Stripe. What exact C4 Mermaid element syntax should be used for these two external entities?	pass→pass	5,647	3,829	-32%	1	1	0%	1,174	3,445	+193%	0	0	—
case-22 We are documenting the component-level view of our authentication subsystem feature. What specific file path and naming convention should be used for this feature documentation?	fail→pass	8,916	2,130	-76%	1	1	0%	1,780	3,127	+76%	0	0	—
case-18 In our container diagram, we want to represent our PostgreSQL database and Redis caching layer as dedicated storage containers rather than standard compute containers. What exact C4 element macros should be used?	pass→pass	6,011	5,161	-14%	1	1	0%	1,057	3,704	+250%	0	0	—
case-19 In our C4 container model, how should the relationship between our Web App and Backend API be drawn to comply with best practices for arrow directions and action descriptions?	pass→pass	10,592	6,233	-41%	1	1	0%	1,872	3,862	+106%	0	0	—
case-20 When defining descriptions for containers and components in C4 model diagrams, what is the recommended max length and key content rule for descriptions to ensure diagram readability?	fail→pass	8,377	2,755	-67%	1	1	0%	1,484	3,129	+111%	0	0	—
case-21 We need to document the specific dynamic request flow for our checkout order placement process. What file path and naming convention must be used for this dynamic flow document?	fail→fail	7,801	3,709	-52%	1	1	0%	1,327	3,391	+156%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 21 counted toward the lift figure. The other 1 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +32 percentage points is the difference between those two pass rates over the 21 comparable cases. 2 cases got worse with the skill loaded, and they are included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 40.9%
Pass rate with the skill: 72.7%
Cases attempted: 22
Cases counted toward lift: 21
Cases that regressed: 2
Skill version measured: v1
Run completed: 8/11/2026, 22:05 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-02

Prompt

We are building an event-driven logistics application with multiple services communicating via messaging queues. Generate C4 model documentation rendered in Mermaid format as markdown files. I'd like to see the high-level ecosystem, backend runtime services, event queues, and deployment topology clearly mapped out.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run73

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+103% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 47 days ago

Other measured skills in the registry, with their headline benchmark lift.