Add c4 skill — C4 model architecture diagrams (Structurizr DSL)

README.md

@@ -2,7 +2,7 @@
 
 Opinionated skills for AI coding agents to create stunning diagrams and visualizations directly in Markdown. These skills extend agent capabilities across diagram generation, data visualization, and technical documentation.
 
-**14 skills** covering 5 rendering engines — from software modeling to enterprise architecture, data analytics, and editorial-quality content cards.
+**15 skills** covering 6 rendering engines — from software modeling to enterprise architecture, data analytics, and editorial-quality content cards.
 
 Skills follow the [Agent Skills](https://agentskills.io/) format.
 
@@ -76,6 +76,14 @@ These skills use PlantUML as the diagram engine, with domain-specific mxgraph st
 | 📡 IoT | [iot](iot/SKILL.md) | IoT device, sensor, and edge computing diagrams | Smart home/factory, fleet management, digital twins |
 | 🧠 Mind Map | [mindmap](mindmap/SKILL.md) | Native PlantUML mind map syntax with directional branches and rich text | Brainstorming trees, study outlines, decision maps |
 
+### Structurizr-Based Skills
+
+These skills use the [C4 model](https://c4model.com) with **Structurizr DSL** as the authoring engine — models as code, one versionable source of truth. Views render as inline SVG (raw HTML) or a PlantUML/Mermaid code fence.
+
+| Category | Skill | Description | Best For |
+|----------|-------|-------------|----------|
+| 🏗️ C4 Architecture | [c4](c4/SKILL.md) | C4 model (Context → Containers → Components → Code) from Structurizr DSL | Software architecture, system context, container & component views |
+
 ### Skill Selection Guide
 
 | Use Case | Recommended Skill | Reason |
@@ -107,6 +115,7 @@ These skills use PlantUML as the diagram engine, with domain-specific mxgraph st
 | System layers (User→App→Data→Infra) | `architecture` | Color-coded HTML/CSS layer templates |
 | Microservices architecture | `architecture` | Grid-based component layout |
 | Enterprise architecture (ArchiMate) | `archimate` | ArchiMate layered modeling notation |
+| C4 system context / containers / components | `c4` | C4 model from Structurizr DSL — models as code |
 | **Network & Cloud** | | |
 | Network topology (LAN/WAN) | `network` | Cisco/Citrix/industry device icons |
 | AWS architecture | `cloud` | AWS stdlib icons |
@@ -153,6 +162,7 @@ flowchart TD
     plantuml["📐 PlantUML<br/><small>Base: text-based diagramming engine</small>"]
     standalone["🧩 Standalone<br/><small>Independent rendering engines</small>"]
     htmlcss["🎨 HTML/CSS<br/><small>Direct HTML embedding</small>"]
+    structurizr["🏗️ Structurizr<br/><small>C4 models-as-code engine</small>"]
 
     plantuml --> uml["📐 uml<br/><small>14 UML types + 9500 stencils</small>"]
     plantuml --> cloud["☁️ cloud<br/><small>AWS/Azure/GCP/Alibaba/IBM</small>"]
@@ -170,6 +180,7 @@ flowchart TD
 
     htmlcss --> architecture["🏛️ architecture<br/><small>12 styles × 13 layouts</small>"]
     htmlcss --> infocard["🃏 infocard<br/><small>14 styles × 13 layouts</small>"]
+    structurizr --> c4["🏗️ c4<br/><small>Context/Containers/Components/Code</small>"]
 ```
 
 ### SKILL.md Format
@@ -210,6 +221,7 @@ When the agent receives a request involving diagrams or visualizations:
 | Data Analytics | ` ```plantuml ` / ` ```puml ` | SVG |
 | IoT | ` ```plantuml ` / ` ```puml ` | SVG |
 | Mindmap | ` ```plantuml ` / ` ```puml ` | SVG |
+| C4 | (raw HTML `<svg>`) or ` ```plantuml ` / ` ```mermaid ` | SVG |
 | Architecture | (no fence, raw HTML) | HTML |
 | Infocard | (no fence, raw HTML) | HTML |
 

c4/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: c4
+description: C4 software-architecture diagrams (Context, Containers, Components, Code) from one Structurizr DSL workspace — models as code. Use when you need a system's architecture at multiple abstraction levels, all derived from a single versionable, diffable model.
+metadata:
+  author: C4 model diagrams are powered by Markdown Viewer — the best multi-platform Markdown extension (Chrome/Edge/Firefox/VS Code) with diagrams, formulas, and one-click Word export. Learn more at https://docu.md
+---
+
+# C4 Model Architecture Diagrams (Structurizr DSL)
+
+**Quick Start:** Model the system once as Structurizr DSL → define one view per C4 level (Context → Containers → Components → Code) → render with the Structurizr CLI → embed the result inside the Markdown document.
+
+> ⚠️ **IMPORTANT:** Never hand-draw C4 diagrams. Author the **Structurizr DSL workspace** (the single source of truth) and derive every view from it. This enforces C4's abstraction rules and keeps the architecture model versionable and diffable.
+
+## What is C4
+
+The **C4 model** (Simon Brown, c4model.com) describes a software system at four levels of abstraction, from the highest (system context) to the lowest (code). Each level answers a different question for a different audience.
+
+| Level | Name | Answers | Audience | Elements |
+|---|---|---|---|---|
+| 1 | **Context** | What does the system do, and who uses it? | Everyone | People + software systems |
+| 2 | **Containers** | What is the high-level shape, and where does the tech live? | Technical people | Containers (apps, DBs, services) |
+| 3 | **Components** | What are the major structural building blocks inside one container? | Developers / architects | Components |
+| 4 | **Code** | How is each component implemented? *(fine-grained, optional)* | Developers | Classes / interfaces |
+
+## Critical Rules
+
+1. **One model, many views.** Write a single `workspace { model { … } }` and add a `views { … }` section per C4 level. Write the model once; derive every view from it.
+2. **Respect the abstraction levels.** A Context view must not contain containers or components; a Containers view must not contain components. C4's value is the enforced hierarchy — keep each view at its own level of abstraction.
+3. **The diagram lives in the Markdown document** (this repo's model), not as a standalone file. Produce the rendered view *inside* the document.
+4. **Code (level 4) is optional.** Model it only when the added precision is worth the maintenance cost; otherwise stop at Components.
+5. **Two render paths** (below), both derived from the same DSL. Prefer SVG for fidelity; use a PlantUML/Mermaid fence when you want inline, diffable code.
+
+## Authoring: the Structurizr DSL
+
+The DSL is "models as code" — the reference implementation of C4. Full syntax: [references/dsl.md](references/dsl.md). The shape in one glance:
+
+```dsl
+workspace "Internet Banking System" "A model of the bank's software architecture." {
+
+    model {
+        customer = person "Personal Banking Customer" "A customer of the bank."
+        mainframe = softwareSystem "Mainframe Banking System" "Core banking data."
+
+        ibs = softwareSystem "Internet Banking System" "Online banking for customers." {
+            spa = container "Single-Page App" "All banking functionality via the browser." "Angular"
+            api = container "API Application" "Banking functionality via JSON/HTTPS." "Java + Spring" {
+                controller = component "Account Controller" "Handles account requests." "Spring MVC"
+            }
+            db  = container "Database" "User data and access logs." "Oracle"
+        }
+
+        customer -> spa "Visits using HTTPS"
+        spa -> api "Makes API calls to"
+        api -> mainframe "Makes API calls to"
+        api -> db "Reads from and writes to"
+    }
+
+    views {
+        systemContext ibs "System Context" { include * autoLayout }
+        container ibs "Containers" { include * autoLayout }
+        component api "API Components" { include * autoLayout }
+        styles {
+            element "Person" { shape Person background #08427b color #ffffff }
+            element "Software System" { background #1168bd color #ffffff }
+            element "Container" { background #438dd5 color #ffffff }
+            element "Component" { background #85bbf0 color #000000 }
+        }
+    }
+}
+```
+
+## Render Path 1 — Inline SVG (native fidelity, recommended)
+
+Export each view as SVG with the browser-based Structurizr renderer, then embed the result as raw HTML `<svg>` (no code fence) — the same pattern as the `architecture` / `infocard` skills. The engine's sanitizer already permits `svg`, so **no engine change is required**.
+
+```bash
+structurizr export -workspace workspace.dsl -format svg -output diagrams
+```
+
+This writes one `*.svg` per view. Paste the contents directly into the Markdown (raw HTML block, no empty lines inside the structure). SVG export uses the browser-based renderer and needs a Chromium/headless browser — see the `structurizr/puppeteer` scripts for automation, or use `structurizr/lite` (Docker) which renders and serves the SVG interactively.
+
+> Highest fidelity: element shapes, arrow routing, and tags match the official Structurizr renderer exactly.
+
+## Render Path 2 — PlantUML / Mermaid inline fence (repo-pattern consistency)
+
+Export to PlantUML (C4-PlantUML dialect recommended) or Mermaid, then emit the result in a code fence — fully inline, diffable code, consistent with every other fence in Markdown Viewer.
+
+```bash
+structurizr export -workspace workspace.dsl -format plantuml/c4plantuml -output diagrams
+structurizr export -workspace workspace.dsl -format mermaid -output diagrams
+```
+
+```plantuml
+@startuml
+!include <C4/C4_Container>
+Person(customer, "Personal Banking Customer")
+System(mainframe, "Mainframe Banking System")
+System_Boundary(ibs, "Internet Banking System") {
+    Container(spa, "Single-Page App", "Angular")
+    Container(api, "API Application", "Java + Spring")
+    ContainerDb(db, "Database", "Oracle")
+}
+Rel(customer, spa, "Visits using HTTPS")
+Rel(spa, api, "Makes API calls to")
+Rel(api, mainframe, "Makes API calls to")
+Rel(api, db, "Reads from and writes to")
+@enduml
+```
+
+> ⚠️ **Caveat:** the PlantUML/Mermaid exporters do not support every shape and feature of the native renderer (this is exactly why Render Path 1 exists). Use Path 2 for quick inline diagrams; switch to Path 1 when fidelity matters. For Mermaid output, the viewer's Mermaid configuration must set `"securityLevel": "loose"` for the diagrams to render.
+
+## The Four Levels
+
+| Level | View keyword | Example | Notes |
+|---|---|---|---|
+| Context | `systemContext` | [examples/system-context.md](examples/system-context.md) | People + systems only |
+| Containers | `container` | [examples/container.md](examples/container.md) | Apps, DBs, services inside one system |
+| Components | `component` | [examples/component.md](examples/component.md) | Building blocks inside one container |
+| Code | `component` + code elements | [examples/code.md](examples/code.md) | Classes/interfaces — optional |
+
+## Best Practices
+
+1. **Model top-down.** Start at Context and only drill into the levels the reader needs. A Context + Containers pair covers most cases.
+2. **Use `autoLayout`** for clean initial layout, then adjust element positions manually only if a view needs it.
+3. **Tag and style once.** Define `styles { element "Tag" { … } }` and apply `#tag` / `tags` to elements instead of styling each one inline.
+4. **Keep descriptions short** — one sentence per element, one verb phrase per relationship.
+5. **Treat the DSL as code.** Version it in the repo next to the document.
+
+## Common Pitfalls
+
+- **Flattening levels** — putting a `container` inside a `systemContext` view (or a `component` in a `container` view). Each view must hold only its level's elements.
+- **Hand-editing the output** — editing the exported SVG/PlantUML instead of the DSL. Regenerate from the DSL or the model drifts.
+- **Empty lines inside an embedded raw `<svg>`** — can break parsing, exactly as with the `architecture` skill's raw-HTML rule.
+- **Forgetting the Mermaid `securityLevel: "loose"`** — C4-exported Mermaid uses `{{…}}` node labels that strict securityLevel rejects.

c4/examples/code.md

@@ -0,0 +1,64 @@
+# Code (Level 4) — fine-grained / optional
+
+The lowest level: how a component is implemented, down to classes and interfaces. **Model this only when the added precision is worth the maintenance cost** — in most systems, stop at Components (Level 3).
+
+## Key Elements
+
+The Structurizr DSL has no distinct "class" element. Code-level diagrams are expressed one of two ways:
+
+1. **`component` elements styled as code** — declare the classes/interfaces as `component` elements (tagged `Code`) and render a component view scoped to their container. The approach used below.
+2. **Imported code model** — pull in a workspace generated by a source-code scanner via `!include` (e.g. a JSON model from the Structurizr "extract" / `structurizr-class` tooling). This keeps the model synced to the real code.
+
+## Step 1 — Author the model
+
+```dsl
+workspace "Internet Banking System" "Code-level view for the Security Component." {
+
+    model {
+        ibs = softwareSystem "Internet Banking System" "Online banking." {
+            apiApp = container "API Application" "Banking API." "Java + Spring MVC" {
+                authFilter    = component "JwtAuthFilter" "Validates the JWT on each request." "Java" "Code"
+                userService   = component "UserDetailsService" "Loads user details for authentication." "Java" "Code"
+                tokenProvider = component "TokenProvider" "Issues and validates tokens." "Java" "Code"
+            }
+        }
+
+        authFilter -> tokenProvider "Validates tokens with"
+        authFilter -> userService "Loads user details via"
+    }
+
+    views {
+        component apiApp "Security Component — Code" {
+            include *
+            autoLayout
+        }
+        styles {
+            element "Code" { background #dddddd color #000000 fontSize 22 }
+        }
+    }
+}
+```
+
+## Step 2 — Render
+
+```bash
+structurizr export -workspace workspace.dsl -format svg -output diagrams
+structurizr export -workspace workspace.dsl -format plantuml/c4plantuml -output diagrams
+```
+
+## Rendered view (C4-PlantUML fence)
+
+```plantuml
+@startuml
+!include <C4/C4_Component>
+Container_Boundary(apiApp, "API Application") {
+    Component(authFilter, "JwtAuthFilter", "Java", "Validates the JWT on each request.")
+    Component(userService, "UserDetailsService", "Java", "Loads user details for authentication.")
+    Component(tokenProvider, "TokenProvider", "Java", "Issues and validates tokens.")
+}
+Rel(authFilter, tokenProvider, "Validates tokens with")
+Rel(authFilter, userService, "Loads user details via")
+@enduml
+```
+
+> **When to skip:** if the class-level detail is stable and well-understood, a Components diagram plus the source code itself is usually the better reference. Reserve Code views for complex, hard-to-navigate components.

c4/examples/component.md

@@ -0,0 +1,70 @@
+# Components (Level 3)
+
+The major structural building blocks inside a single container. Components are declared inside their parent container's `{ … }`.
+
+## Key Elements
+
+- **Component** — a structural unit within a container (a controller, service, repository, client). Carries a technology as its third argument.
+- A component view targets **one container** (`component <container>`), not the whole system.
+
+## Step 1 — Author the model
+
+```dsl
+workspace "Internet Banking System" "Components view for the API." {
+
+    model {
+        customer = person "Personal Banking Customer" "A customer of the bank."
+
+        ibs = softwareSystem "Internet Banking System" "Online banking." {
+            api = container "API Application" "Banking functionality via a JSON/HTTPS API." "Java + Spring MVC" {
+                signIn    = component "Sign In Controller" "Allows users to sign in." "Spring MVC Rest Controller"
+                accounts  = component "Accounts Summary Controller" "Provides account summaries." "Spring MVC Rest Controller"
+                security  = component "Security Component" "Authentication and authorisation." "Spring Security"
+            }
+            db = container "Database" "User data and access logs." "Oracle"
+        }
+
+        customer -> signIn "Signs in using" "HTTPS"
+        signIn -> security "Authenticates with"
+        security -> db "Reads from and writes to" "JDBC"
+        accounts -> db "Reads from" "JDBC"
+    }
+
+    views {
+        component api "API Components" {
+            include *
+            autoLayout
+        }
+        styles {
+            element "Component" { background #85bbf0 color #000000 }
+            element "Container" { background #438dd5 color #ffffff }
+        }
+    }
+}
+```
+
+## Step 2 — Render
+
+```bash
+structurizr export -workspace workspace.dsl -format svg -output diagrams
+structurizr export -workspace workspace.dsl -format plantuml/c4plantuml -output diagrams
+```
+
+## Rendered view (C4-PlantUML fence)
+
+```plantuml
+@startuml
+!include <C4/C4_Component>
+Person(customer, "Personal Banking Customer", "A customer of the bank.")
+Container_Boundary(api, "API Application") {
+    Component(signIn, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in.")
+    Component(accounts, "Accounts Summary Controller", "Spring MVC Rest Controller", "Provides account summaries.")
+    Component(security, "Security Component", "Spring Security", "Authentication and authorisation.")
+}
+ContainerDb(db, "Database", "Oracle", "User data and access logs.")
+Rel(customer, signIn, "Signs in using", "HTTPS")
+Rel(signIn, security, "Authenticates with")
+Rel(security, db, "Reads from and writes to", "JDBC")
+Rel(accounts, db, "Reads from", "JDBC")
+@enduml
+```