C4 Architecture
Install this when you need C4-level Mermaid architecture docs (context through deployment) generated from your actual codebase for investors, hires, or your future self.
Overview
c4-architecture is an agent skill most often used in Build docs (also Validate scope, Operate infra) that generates C4-model Mermaid diagrams and markdown architecture documentation from your codebase.
Install
npx skills add https://github.com/softaworks/agent-toolkit --skill c4-architectureWhat is this skill?
- Four-step workflow: scope audience, analyze codebase, generate Mermaid C4, write markdown with context
- Supports C4Context, C4Container, C4Component, and C4Deployment diagram types in Mermaid syntax
- Level selection table maps audience (everyone vs DevOps) to required vs optional diagrams
- Triggers on phrases like architecture diagram, system context, container diagram, document architecture
- Explores the repo to infer containers, components, and relationships instead of hand-waving boxes
- 4 C4 diagram levels documented in the level selection table (Context, Container, Component, Deployment)
Adoption & trust: 3.8k installs on skills.sh; 2k GitHub stars; 3/3 security scanners passed (skills.sh audits).
What problem does it solve?
You can ship features fast but lack a trustworthy system diagram that matches the repo and explains containers, actors, and deployment to teammates or AI agents.
Who is it for?
Solo founders documenting a growing SaaS or API who need standard C4 views without learning a separate architecture modeling suite first.
Skip if: Pure whiteboard ideation with no code to analyze, or teams that already maintain a locked enterprise ArchiMate source of truth they will not regenerate from repo scans.
When should I use this skill?
Asked to create architecture diagrams, document system architecture, visualize software structure, or generate context/container/component/deployment C4 diagrams.
What do I get? / Deliverables
You get leveled C4 Mermaid diagrams plus explanatory markdown files grounded in explored code structure, ready to drop into README, Notion, or investor updates.
- Markdown files with Mermaid C4 diagrams
- Explanatory context per diagram level chosen
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Build/docs is the primary shelf because the workflow writes markdown architecture artifacts developers consume while the product is taking shape. Docs subphase captures diagram generation and explanatory narrative—not runtime deploy automation, which is a follow-on concern.
Where it fits
Produce a C4 context diagram showing users, your app, and external APIs before committing to a monolith split.
Add container and database relationships to README so your coding agent stops inventing phantom services.
Optional component diagram for a messy package tree only where it explains ownership boundaries.
Draft a deployment-level C4 view mapping processes to nodes before migrating off a single VPS.
How it compares
Structured C4+Mermaid doc generator from the repo—not a live cloud inventory MCP or automated IaC diagram sync.
Common Questions / FAQ
Who is c4-architecture for?
Indie builders and small teams who want investor- or hire-ready architecture pages and agent-friendly system maps without manual diagram drawing.
When should I use c4-architecture?
In Validate when scoping system boundaries; in Build when onboarding collaborators; in Operate when documenting deployment nodes against production reality.
Is c4-architecture safe to install?
It analyzes and writes documentation in your project via the agent—check the Security Audits panel on this Prism page and avoid pasting secrets into generated diagrams.
SKILL.md
READMESKILL.md - C4 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: | 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