diff --git a/README.md b/README.md index 69cdfa9..74952ee 100644 --- a/README.md +++ b/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
Base: text-based diagramming engine"] standalone["🧩 Standalone
Independent rendering engines"] htmlcss["🎨 HTML/CSS
Direct HTML embedding"] + structurizr["πŸ—οΈ Structurizr
C4 models-as-code engine"] plantuml --> uml["πŸ“ uml
14 UML types + 9500 stencils"] plantuml --> cloud["☁️ cloud
AWS/Azure/GCP/Alibaba/IBM"] @@ -170,6 +180,7 @@ flowchart TD htmlcss --> architecture["πŸ›οΈ architecture
12 styles Γ— 13 layouts"] htmlcss --> infocard["πŸƒ infocard
14 styles Γ— 13 layouts"] + structurizr --> c4["πŸ—οΈ c4
Context/Containers/Components/Code"] ``` ### 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 ``) or ` ```plantuml ` / ` ```mermaid ` | SVG | | Architecture | (no fence, raw HTML) | HTML | | Infocard | (no fence, raw HTML) | HTML | diff --git a/c4/SKILL.md b/c4/SKILL.md new file mode 100644 index 0000000..b34c09c --- /dev/null +++ b/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 `` (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 +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 ``** β€” 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. diff --git a/c4/examples/code.md b/c4/examples/code.md new file mode 100644 index 0000000..675d333 --- /dev/null +++ b/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 +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. diff --git a/c4/examples/component.md b/c4/examples/component.md new file mode 100644 index 0000000..8f12eb1 --- /dev/null +++ b/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 `), 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 +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 +``` diff --git a/c4/examples/container.md b/c4/examples/container.md new file mode 100644 index 0000000..924ab7b --- /dev/null +++ b/c4/examples/container.md @@ -0,0 +1,75 @@ +# Containers (Level 2) + +The high-level technology shape: the containers (applications, databases, services) that make up the system in scope, and how they connect. No components β€” only containers. + +## Key Elements + +- **Container** β€” a separately deployable/runnable unit (web app, mobile app, API, database, message broker). Declared inside its parent system's `{ … }`. +- Each container carries a **technology** ("Angular", "Java + Spring", "Oracle") as its third argument. + +## Step 1 β€” Author the model + +```dsl +workspace "Internet Banking System" "Containers view." { + + 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 Application" "All banking functionality via the web browser." "Angular" + mobile = container "Mobile App" "A limited subset of functionality on mobile." "Xamarin" + api = container "API Application" "Banking functionality via a JSON/HTTPS API." "Java + Spring MVC" + db = container "Database" "User registration, hashed credentials, access logs." "Oracle" + } + + customer -> spa "Visits using" + customer -> mobile "Visits using" + spa -> api "Makes API calls to" "JSON/HTTPS" + mobile -> api "Makes API calls to" "JSON/HTTPS" + api -> mainframe "Makes API calls to" "XML/HTTPS" + api -> db "Reads from and writes to" "JDBC" + } + + views { + container ibs "Containers" { + include * + autoLayout + } + styles { + element "Person" { shape Person background #08427b color #ffffff } + element "Software System" { background #1168bd color #ffffff } + 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 +Person(customer, "Personal Banking Customer", "A customer of the bank.") +System(mainframe, "Mainframe Banking System", "Core banking data.") +System_Boundary(ibs, "Internet Banking System") { + Container(spa, "Single-Page Application", "Angular", "All banking functionality via the web browser.") + Container(mobile, "Mobile App", "Xamarin", "A limited subset of functionality on mobile.") + Container(api, "API Application", "Java + Spring MVC", "Banking functionality via a JSON/HTTPS API.") + ContainerDb(db, "Database", "Oracle", "User registration, hashed credentials, access logs.") +} +Rel(customer, spa, "Visits using", "HTTPS") +Rel(customer, mobile, "Visits using", "HTTPS") +Rel(spa, api, "Makes API calls to", "JSON/HTTPS") +Rel(mobile, api, "Makes API calls to", "JSON/HTTPS") +Rel(api, mainframe, "Makes API calls to", "XML/HTTPS") +Rel(api, db, "Reads from and writes to", "JDBC") +@enduml +``` diff --git a/c4/examples/system-context.md b/c4/examples/system-context.md new file mode 100644 index 0000000..b984bc9 --- /dev/null +++ b/c4/examples/system-context.md @@ -0,0 +1,59 @@ +# System Context (Level 1) + +The highest-level view: the system in scope, the people who use it, and the other software systems it interacts with. No containers or components here β€” only people and systems. + +## Key Elements + +- **Person** β€” a human user/role (internal or external). +- **Software system** β€” the system in scope, plus any system it depends on. +- **Relationship descriptions** read as verb phrases and carry the interaction intent. + +## Step 1 β€” Author the model + +```dsl +workspace "Internet Banking System" "System context for the bank's online banking." { + + model { + customer = person "Personal Banking Customer" "A customer of the bank, with personal bank accounts." + mainframe = softwareSystem "Mainframe Banking System" "Stores all core banking information about customers, accounts and transactions." + + ibs = softwareSystem "Internet Banking System" "Allows customers to view account information and make payments." { + # containers are declared here but NOT shown at this level + } + + customer -> ibs "Views account balances and makes payments using" + ibs -> mainframe "Gets account information from, and makes payments using" + } + + views { + systemContext ibs "System Context" { + include * + autoLayout + } + styles { + element "Person" { shape Person background #08427b color #ffffff } + element "Software System" { background #1168bd color #ffffff } + } + } +} +``` + +## Step 2 β€” Render + +```bash +structurizr export -workspace workspace.dsl -format svg -output diagrams # inline SVG (fidelity) +structurizr export -workspace workspace.dsl -format plantuml/c4plantuml -output diagrams # fence +``` + +## Rendered view (C4-PlantUML fence) + +```plantuml +@startuml +!include +Person(customer, "Personal Banking Customer", "A customer of the bank, with personal bank accounts.") +System(mainframe, "Mainframe Banking System", "Stores all core banking information about customers, accounts and transactions.") +System(ibs, "Internet Banking System", "Allows customers to view account information and make payments.") +Rel(customer, ibs, "Views account balances and makes payments using", "HTTPS") +Rel(ibs, mainframe, "Gets account information from, and makes payments using", "HTTPS") +@enduml +``` diff --git a/c4/references/dsl.md b/c4/references/dsl.md new file mode 100644 index 0000000..71cb97d --- /dev/null +++ b/c4/references/dsl.md @@ -0,0 +1,176 @@ +# Structurizr DSL Reference + +Syntax reference for authoring C4 models as code. Load this when you need precise element, relationship, view, or style syntax. + +--- + +## Workspace & Model + +```dsl +workspace "Name" "Description" { + model { + # elements and relationships + } + views { + # one view per C4 level + } +} +``` + +The `workspace` is the top-level container; `model` holds the elements and relationships (the single source of truth); `views` defines which diagrams to render. + +--- + +## Elements + +| Type | Syntax | Purpose | +|---|---|---| +| Person | `p = person "Name" "Description" "Tag"` | A human user (internal or external) | +| Software system | `ss = softwareSystem "Name" "Description" "Tag"` | A system in its own right (may be out of scope) | +| Container | `c = container "Name" "Description" "Technology" "Tag"` | A deployable/runtime unit (app, DB, service) | +| Component | `comp = component "Name" "Description" "Technology" "Tag"` | A structural block inside a container | +| Group | `group "Name" { … }` | A visual grouping of elements | +| Deployment node | `node = deploymentNode "Name" "Description" "Technology" { … }` | Physical/cloud infrastructure | +| Infrastructure node | `infra = infrastructureNode "Name" "Description" "Technology"` | A piece of infrastructure (e.g. a database engine) | +| Instances | `softwareSystemInstance` / `containerInstance` | Deployment-specific instances of systems/containers | + +Elements can be nested to express ownership (a `container` or `component` is declared inside its parent's `{ … }`): + +```dsl +ibs = softwareSystem "Internet Banking System" "…" { + api = container "API Application" "…" "Java + Spring" { + controller = component "Account Controller" "Handles account requests." "Spring MVC" + service = component "Account Service" "Business logic for accounts." "Java" + } +} +``` + +--- + +## Relationships + +```dsl +a -> b "Uses" "HTTPS" "tag1,tag2" +``` + +| Part | Meaning | +|---|---| +| `a -> b` | Direction (source β†’ destination) | +| `"Uses"` | Description (required) | +| `"HTTPS"` | Technology/protocol (optional) | +| `"tag1,tag2"` | Comma-separated tags (optional) | + +**C4 relationship intent is the description** β€” it should read as a verb phrase ("Makes API calls to", "Reads from and writes to", "Sends payment instructions to"). Omit direction only when it is genuinely bidirectional. + +--- + +## Views + +Each view is a named block under `views { }`. The keyword sets the level: + +```dsl +views { + systemContext ibs "System Context" { + include * # everything at this level (people + systems) + autoLayout + } + container ibs "Containers" { + include * # every container inside ibs + autoLayout + } + component api "API Components" { + include * # every component inside the api container + autoLayout + } +} +``` + +| Keyword | Level | Shows | +|---|---|---| +| `systemContext ` | 1 β€” Context | People + software systems | +| `container ` | 2 β€” Containers | Containers within one system | +| `component ` | 3 β€” Components | Components within one container | +| `dynamic ` | Dynamic | Ordering of interactions (numbered) | +| `deployment ` | Deployment | Deployment nodes + infrastructure | +| `filtered` / `custom` | Custom | Hand-picked elements and relationships | + +### Include / exclude + +- `include *` β€” everything at this level (auto-expands to the correct elements). +- `include a b c` β€” specific elements only. +- `exclude a` β€” drop an element from an otherwise `*` view. +- `include a -> b` β€” include a specific relationship. + +--- + +## Styles & Themes + +Style elements once by **tag**, not inline: + +```dsl +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 } + relationship "HTTPS" { color #707070 } +} +``` + +Key style properties: `shape` (Box, RoundedBox, Circle, Ellipse, Hexagon, Person, Cylinder, Folder, Component), `background`, `color` (text), `stroke`, `width`/`height`, `fontSize`, `icon`, `opacity`. + +To use a published theme instead of hand-writing styles: + +```dsl +views { + theme https://static.structurizr.com/themes/microsoft-azure-2021.01.26/theme.json +} +``` + +--- + +## Properties & Metadata + +```dsl +api = container "API Application" "…" "Java" { + properties { + "Health Check" "https://api.example.com/health" + } + healthcheck "https://api.example.com/health" +} +``` + +`properties` is a free key/value bag; `healthcheck` is a first-class field. + +--- + +## Includes & Imports + +```dsl +!include https://example.com/shared-people.dsl +!include ./software-systems.dsl +!docs ./docs/adrs +``` + +`!include` pulls in another DSL fragment (inline); `!docs` attaches a folder of Markdown to the workspace for decision logs and supplementary docs. + +--- + +## Exporting (Structurizr CLI) + +```bash +# SVG / PNG β€” native browser-based renderer (needs Chromium/headless browser) +structurizr export -workspace workspace.dsl -format svg -output diagrams +structurizr export -workspace workspace.dsl -format png -output diagrams + +# PlantUML β€” Structurizr dialect or C4-PlantUML dialect +structurizr export -workspace workspace.dsl -format plantuml -output diagrams +structurizr export -workspace workspace.dsl -format plantuml/c4plantuml -output diagrams + +# Mermaid +structurizr export -workspace workspace.dsl -format mermaid -output diagrams + +# Other formats: dot, d2, json, ilograph, websequencediagrams, static, theme +``` + +The CLI ships as `structurizr.sh` (from the release zip), a native `structurizr` binary, or the `structurizr/lite` Docker image (which also serves an interactive workspace with the browser renderer).