Claude Skill

c4-diagramming

Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not

LLM Mart · 0 points · 9 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download magnus919-agent-skills-c4-diagramming-addad86.zip · 16 KB
magnus919/agent-skills 96 9 forks MIT Updated 13h ago
Part of magnus919/agent-skills — 145 skills

Install

skills CLI npx skills add https://github.com/magnus919/agent-skills/tree/main/c4-diagramming
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install magnus919-agent-skills@llmmart
Git git clone https://github.com/magnus919/agent-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole magnus919/agent-skills collection as a plugin from our marketplace. Git is the plain clone.

README

C4 Diagramming

Make system boundaries, responsibilities, and relationships legible at the architectural level appropriate to the reader.

Why Install This Skill

Make system boundaries, responsibilities, and relationships legible at the architectural level appropriate to the reader. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer.

Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator.

What You Get

Path What it provides
SKILL.md Trigger conditions, workflow, and guidance for loading deeper resources.
references/ Reference material for C4 levels, architecture-as-code tooling, CI, and communication review, including technical-diagram-communication.md.

Quick Start

Choose the C4 level and authoring format in SKILL.md, load the matching reference before drawing, and review the rendered artifact for the audience's job rather than syntax alone.

Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.

Triggers

  • Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views.
  • Requests involving the method, deliverables, or review process described in SKILL.md.
  • Requests to make a C4 diagram understandable to a particular audience or to review its hierarchy, narrative, labels, uncertainty, or accessible fallback.
  • Work where a reusable template or reference from this skill would reduce avoidable mistakes.

Requirements

Mermaid or Structurizr tooling is optional and only needed to render or validate diagrams.

Source and maintenance

This skill was extracted from magnus919/hermes-profiles at commit 867a555. The portable methodology was retained; Hermes-specific profile, orchestration, and memory assumptions were removed.

Skill manifest

C4 Diagramming

C4 Model for structural architecture visualization. Produces diagrams at four zoom levels, mapped into the artifact pyramid.

C4-to-Pyramid Mapping

C4 Level Pyramid Layer Path
Level 1: System Context L1 (Summary) 01-summary/system-context.md
Level 2: Container L2 (Analysis) 02-analysis/structural-views/container.md
Level 3: Component L2 (Analysis) 02-analysis/structural-views/components.md
Level 4: Code L3 (Dossiers) 03-dossiers/code-level-detail.md

C4 is the cleanest structural fit — its four-level hierarchy maps to the three pyramid layers with almost no translation, and Levels 2-3 both resolve to separate L2 analysis files.

Communication Gate

Before choosing notation or polishing layout, state the audience and the job the reader must complete. Select one C4 level that answers that job; do not mix system context, container, component, and code claims merely to fill a canvas. Keep the abstraction level, element vocabulary, boundary treatment, and relationship meaning consistent within a view. A structurally valid C4 model can still be the wrong communication artifact if it asks the reader to infer the purpose, mixes levels, hides important paths, or overwhelms the intended reader.

Load references/technical-diagram-communication.md when creating, revising, or reviewing a diagram for a real audience. Use its review record to check narrative/read order, visual hierarchy, labels and legends, signal-to-noise, color-independent meaning, accessibility handoff, uncertainty, and review evidence. Full accessibility conformance remains owned by web-accessibility; architecture decisions remain owned by software-architecture.

Review Evidence

Record the intended audience and question, C4 level and scope, key claim, known uncertainty, target renderer, and an accessible text or tabular fallback. Review both the source model and the rendered artifact. A passing syntax/model validator proves structural validity only; it does not prove that the diagram communicates the intended claim.

Authoring Formats

Mermaid (Default for Quick Diagrams)

Use when you need a single diagram embedded in markdown. See the GitHub Rendering Constraint section below for C4-in-Mermaid compatibility notes.

Structurizr DSL (Recommended for Long-Lived Projects)

Structurizr DSL is the C4 model's reference "models as code" implementation, created by Simon Brown. Define the entire architecture model in a single DSL file; all 4 C4 levels are generated from it. This ensures structural consistency across diagrams that hand-written Mermaid cannot guarantee.

workspace {
    model {
        user = person "Customer"
        system = softwareSystem "Your System" {
            webapp = container "Web Application" "TypeScript, React"
            api = container "API" "Go"
            db = container "Database" "PostgreSQL"
            user -> webapp "Uses"
            webapp -> api "Makes API calls"
            api -> db "Reads/writes"
        }
    }
    views {
        systemContext system { include * autolayout lr }
        container system { include * autolayout lr }
        component api { include * autolayout lr }
        theme default
    }
}

Key capabilities:

  • !adrs docs/adr — imports Architecture Decision Records (adr-tools, MADR, log4brains) into the workspace, rendered alongside C4 diagrams
  • !docs docs/arc42 — imports arc42 documentation as Markdown/AsciiDoc
  • Structurizr Lite (Docker) — local preview at http://localhost:8081
  • CI commands: validate, inspect, export (PlantUML, Mermaid, static site)

Full reference in references/architecture-as-code-ecosystem.md — tool comparison, DSL cookbook, C4-PlantUML alternative, and the converged repo convention.

Contents

  • references/c4-to-pyramid-mapping.md — context→L1, container/component→L2, code→L3 (Mermaid + Structurizr DSL paths)
  • c4-to-flowchart.md — companion Mermaid conversion patterns for GitHub-compatible flowcharts
  • references/architecture-as-code-ecosystem.md — Structurizr DSL, C4-PlantUML, docToolChain, converged repo convention, tool comparison table
  • references/ci-pipeline-templates.md — GitHub Actions, GitLab CI, ForgeJo (Gitea Actions, Woodpecker) pipeline templates for Structurizr validation, export, deploy

GitHub Rendering Constraint

GitHub's built-in Mermaid renderer does not bundle the C4 plugin (@mermaid-js/mermaid). Any ````mermaidblock usingC4Context, C4Container, or C4Component` syntax renders as raw code rather than a diagram on GitHub. This affects issues, PR descriptions, discussion comments, and markdown files.

Workaround: Convert C4 diagrams to standard flowchart syntax before embedding in GitHub markdown:

  • Person() → [rect] node with label
  • System() / System_Ext() → [rect] inside or outside subgraphs
  • Container() → [rect with tech stack label]`
  • Db() → [(cylinder shape)]
  • System_Boundary{} / Container_Boundary{} → subgraph ... end
  • Rel() → -- label --> or -.->
  • Drop UpdateLayoutConfig() — use flowchart LR or TB directive instead

For the full conversion table with worked examples, load c4-to-flowchart.md from the companion mermaid-diagrams skill when it is available.

.mmd files in a DIAGRAMS/ directory must also use standard flowchart syntax if they need to render via mmdc or on GitHub. Files using C4-plugin syntax can only render in tools that bundle the plugin (e.g., Mermaid Live Editor, mmdc with C4 extension config). If you commit .mmd files with C4 syntax to a repo, GitHub's file preview will show them as raw text — convert them to standard syntax or render them to PNG first.

Feature Request Filed

A GitHub Community feature request to bundle the C4 mermaid plugin was filed at https://github.com/orgs/community/discussions/197898 (closed — requires submission through the web UI with the Apps, API and Webhooks discussion template). If this gets implemented, the flowchart conversions below would no longer be necessary for GitHub rendering.

Canonical Reference

Portability

This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.

When not to use

  • Use mermaid-diagrams for Mermaid grammar, renderer compatibility, layout, and export troubleshooting that does not require C4 level/model decisions.
  • Use software-architecture for architecture drivers, tradeoffs, decisions, and fitness evidence; this skill visualizes those decisions rather than owning them.
  • Use web-accessibility for complete WCAG/ARIA conformance work and assistive-technology evidence; this skill contributes diagram-specific accessibility checks and fallbacks.
Files (agent-skills)
  • evals
    • evals.json 4.8 KB 
      {
  "schema_version": 1,
  "skill_name": "c4-diagramming",
  "evals": [
    {
      "id": "context-view-for-new-maintainer",
      "prompt": "Create a C4 view for a new maintainer who needs to understand the system boundary and external import dependencies before changing an ingestion path. Keep the view useful in a GitHub README.",
      "expected_output": "A C4 system-context view with a stated audience and job, consistent abstraction, a clear read order, labeled relationships, a legend or explanation where needed, and a text fallback. It uses GitHub-compatible Mermaid or explains why another format is chosen.",
      "assertions": [
        "The audience and reader job are stated before the diagram",
        "The view stays at system-context abstraction and does not mix container internals",
        "External dependencies and relationships have meaningful labels",
        "The output includes a text-only summary or equivalent accessible fallback",
        "GitHub Mermaid compatibility is addressed without claiming syntax validity proves communication quality"
      ]
    },
    {
      "id": "container-view-signal-to-noise",
      "prompt": "Review a proposed container diagram with 28 nodes, several crossed edges, database icons mixed with services, and three colors that indicate criticality. The team wants to use it in an incident handoff.",
      "expected_output": "A review that identifies the view as overloaded, proposes a smaller incident-oriented container view or split views, preserves C4 level ownership, and replaces color-only criticality with redundant meaning.",
      "assertions": [
        "The review names the incident handoff audience and job",
        "Node and edge density are treated as a signal-to-noise problem rather than completeness",
        "The proposed revision keeps container-level abstraction consistent",
        "Criticality is encoded with labels, line or shape differences, or text in addition to color",
        "The review distinguishes C4 communication review from incident procedure and architecture decision ownership"
      ]
    },
    {
      "id": "uncertain-target-model",
      "prompt": "Document a target architecture that is still being validated. Some integrations are confirmed, one data store is inferred from code, and the future event path is only a proposal. Produce a C4 view and review notes.",
      "expected_output": "A C4 view that marks confirmed, inferred, and proposed information explicitly, avoids false precision, and records evidence and open questions without turning the diagram into an architecture decision record.",
      "assertions": [
        "Confirmed, inferred, and proposed claims are visibly distinguished without relying on color alone",
        "The output records the evidence source or uncertainty for the inferred store and proposed event path",
        "The selected C4 level and scope are stated",
        "Open questions are separated from asserted relationships",
        "The output routes consequential architecture decisions to software-architecture or ADR ownership"
      ]
    },
    {
      "id": "related-view-consistency",
      "prompt": "Generate system-context, container, and component views for a payments platform. Check that names, boundaries, and relationship meanings remain coherent across views while each view serves a different reader.",
      "expected_output": "Three linked views with explicit audience/job and read order, stable identities and boundaries, deliberate scope changes, and evidence of rendered review.",
      "assertions": [
        "Each view has a distinct audience or question and does not try to answer every question",
        "Element identities and relationship meanings remain consistent across levels",
        "Scope omissions are documented instead of implying nonexistent elements",
        "The component view does not silently redefine a container boundary",
        "Rendered-output review evidence is recorded for each target surface"
      ]
    },
    {
      "id": "accessibility-boundary",
      "prompt": "A product manager asks for an accessible C4 architecture diagram for a roadmap review, including a color-coded legend and a WCAG conformance statement. Explain what to produce and which work must be handed off.",
      "expected_output": "A diagram communication plan with redundant non-color encoding, labels, reading order, text fallback, and review evidence, plus an explicit handoff to web-accessibility for full conformance and assistive-technology evaluation.",
      "assertions": [
        "The roadmap audience and decision job are defined",
        "The plan requires meaning that survives color loss and zoom",
        "A textual or tabular equivalent is specified",
        "The output refuses to claim full WCAG conformance from diagram checks alone",
        "C4 model decisions remain distinct from accessibility conformance ownership"
      ]
    }
  ]
}
  • references
    • architecture-as-code-ecosystem.md 11.5 KB 
      # Architecture as Code (AaC) Ecosystem

Tools, conventions, and patterns for managing C4 model diagrams, arc42 documentation, and Architecture Decision Records (ADRs) together in a git repository.

## 1. Structurizr — C4 Reference Implementation

Structurizr is the official "models as code" tool for the C4 model, created by Simon Brown (the C4 model's author). You write a text-based DSL that defines your entire software architecture model; all diagrams are generated from that single model.

**Key website:** https://structurizr.com/ — **Docs:** https://docs.structurizr.com/

### Core Concepts

- **Workspace** — the top-level container. Holds a model + views + documentation + decisions.
- **Model** — defines elements (persons, software systems, containers, components) and their relationships.
- **Views** — selects subsets of the model for diagram rendering (system context, container, component, dynamic, deployment).
- **DSL** — text-based domain-specific language. Single source of truth. Git-friendly.

### Minimal Example (All Four C4 Levels)

```
workspace {

    model {
        user = person "Customer"
        system = softwareSystem "Internet Banking System" {
            webapp = container "Web Application" "TypeScript, React" {
                user -> this "Uses"
            }
            api = container "API" "Go" {
                webapp -> this "Makes API calls"
            }
            db = container "Database" "PostgreSQL" {
                api -> this "Reads/writes"
            }
        }
    }

    views {
        systemContext system {
            include *
            autolayout lr
        }
        container system {
            include *
            autolayout lr
        }
        component api {
            include *
            autolayout lr
        }
        theme default
    }

}
```

### The `!adrs` Keyword — Native ADR Integration

Structurizr can import Architecture Decision Records directly into the workspace:

```
workspace {

    !adrs docs/adr

    model { ... }
    views { ... }

}
```

This imports all Markdown files from `docs/adr/` using the adr-tools format by default. Supported formats:
- `adrtools` (default) — expects files matching adr-tools naming convention
- `madr` — for MADR-format ADRs
- `log4brains` — for log4brains-format ADRs

The ADRs are rendered in the Structurizr UI alongside the C4 diagrams. This is the tightest integration available between C4 and ADRs.

### The `!docs` Keyword — arc42 Documentation Import

```
workspace {

    !docs docs/arc42

    model { ... }
    views { ... }

}
```

Imports Markdown or AsciiDoc documentation (structured as arc42 sections) and renders them in the UI alongside diagrams and ADRs. Supports section-based navigation.

### Structurizr Lite — Local Preview

Docker container for rendering the full workspace in a browser:

```yaml
# docker-compose.yml
services:
  structurizr-lite:
    image: structurizr/lite
    ports:
      - "8081:8080"
    volumes:
      - ./docs/arch:/usr/local/structurizr
```

Access at `http://localhost:8081`. Shows C4 diagrams, arc42 documentation, and ADRs in a unified web UI with navigation.

### CI/CD Commands

```bash
# Validate DSL syntax and model consistency
structurizr-cli validate -w docs/arch/model/system.dsl

# Inspect for architectural drift
structurizr-cli inspect -w docs/arch/model/system.dsl

# Export diagrams to PlantUML
structurizr-cli export -w docs/arch/model/system.dsl -format plantuml

# Export diagrams to Mermaid
structurizr-cli export -w docs/arch/model/system.dsl -format mermaid

# Export to static HTML site
structurizr-cli export -w docs/arch/model/system.dsl -format site
```

### DSL Cookbook

Full tutorial guide: https://docs.structurizr.com/dsl/cookbook/

Topics covered: workspace structure, model elements, relationships, views, styling, themes, animations, deployment nodes, dynamic diagrams, filtering, properties, perspectives.

---

## 2. C4-PlantUML — Lighter Alternative

**Repo:** https://github.com/plantuml-stdlib/C4-PlantUML

PlantUML include files that add C4 semantics to standard PlantUML. No single-model consistency (each diagram is a separate file), but much lower learning curve than Structurizr.

### Function Reference

| Function | C4 Level | Purpose |
|---|---|---|
| `Person(alias, label, description)` | Any | External user or actor |
| `Person_Ext(alias, label, description)` | Context | External user (outside system boundary) |
| `System(alias, label, description)` | Context | Software system |
| `System_Ext(alias, label, description)` | Context | External software system |
| `Container(alias, label, tech, description)` | Container | Application container (web app, API, DB) |
| `Container_Boundary(alias, label)` | Container | Groups related containers |
| `Component(alias, label, tech, description)` | Component | Module within a container |
| `System_Boundary(alias, label)` | Context | Groups related systems |
| `Rel(from, to, label, tech)` | Any | Relationship between elements |
| `Rel_D(from, to, label, tech)` | Any | Relationship (dashed) |
| `Rel_Neighbor(from, to, label, tech)` | Any | Relationship rendering optimization |
| `UpdateLayoutConfig(c4ShapeInRow, c4BoundaryInRow)` | Any | Layout tuning |
| `LAYOUT_WITH_LEGEND()` | Any | Renders with automatic legend |

### Example

```plantuml
@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Context.puml

Person(customer, "Customer")
System(system, "Your System", "Core platform")
System_Ext(external, "External Service", "Payment processor")

Rel(customer, system, "Uses")
Rel(system, external, "Charges via")
@enduml
```

### When to Choose Over Structurizr

| Situation | Choice |
|---|---|
| Team already uses PlantUML for other diagrams | C4-PlantUML (consistent toolchain) |
| Need a quick C4 diagram for an ad-hoc document | C4-PlantUML (no DSL learning curve) |
| Need consistent multi-diagram model across 4 C4 levels | Structurizr (single source of truth) |
| Want ADR integration in the diagram viewer | Structurizr (native `!adrs` support) |
| CI pipeline already has PlantUML | Either — Structurizr exports to PlantUML |

---

## 3. docToolChain — arc42 Build Pipeline

**Repo:** https://github.com/docToolchain/docToolchain

A Gradle-based docs-as-code toolchain purpose-built for arc42 documentation. Handles the full pipeline: AsciiDoc compilation, PlantUML diagram generation, PDF/HTML export, Confluence publishing.

### Key Capabilities

- **arc42 template management** — generates skeleton arc42 documentation with all 12 sections
- **AsciiDoc compilation** — converts `.adoc` source files to HTML, PDF, DocBook
- **PlantUML integration** — renders C4 diagrams (via C4-PlantUML includes) as part of the build
- **Confluence export** — publishes rendered docs to Confluence spaces via asciidoc2confluence
- **Gradle task hierarchy** — `generateHTML`, `generatePDF`, `exportConfluence` as standard tasks

### Directory Structure Convention

```
docs/
├── src/
│   ├── arc42/
│   │   ├── 01_introduction_and_goals.adoc
│   │   ├── ...
│   │   └── 12_glossary.adoc
│   └── images/
├── build/              ← Generated output
├── build.gradle        ← docToolChain configuration
└── gradle.properties
```

### When to Use

docToolChain is for organizations that want a **standardized, build-pipeline-driven** approach to arc42 documentation. It adds ceremony (Gradle build, strict directory structure) in exchange for consistent output formats and Confluence integration. For teams that just want C4 diagrams with ADRs, Structurizr is lighter.

---

## 4. Converged Repo Convention

The AaC community has converged on a standard directory structure for combining C4, arc42, and ADRs in a single git repository. Multiple reference implementations use the same pattern:

### Directory Structure

```
docs/arch/
├── model/
│   ├── system.dsl                ← Structurizr DSL (the architecture model)
│   └── deployment/               ← Deployment-specific views (dev, staging, prod)
│       ├── dev.dsl
│       └── live.dsl
├── src/                          ← arc42 12-section template
│   ├── 01_introduction_and_goals.adoc
│   ├── 02_constraints.adoc
│   ├── 03_system_scope_and_context.adoc
│   ├── 04_solution_strategy.adoc
│   ├── 05_building_block_view.adoc
│   ├── 06_runtime_view.adoc
│   ├── 07_deployment_view.adoc
│   ├── 08_crosscutting_concepts.adoc
│   ├── 09_architecture_decisions.adoc
│   ├── 10_quality_requirements.adoc
│   ├── 11_technical_risks.adoc
│   └── 12_glossary.adoc
├── adr/                          ← Architecture Decision Records
│   ├── 0001-record-architecture-decisions.md
│   ├── 0002-use-postgresql.md
│   ├── 0003-adopt-event-sourcing.md
│   └── README.md                 ← ADR index with status table
├── images/                       ← Embedded screenshots, diagrams
├── README.md                     ← Project overview
└── docker-compose.yml            ← Structurizr Lite
```

### How the Three Methodologies Relate

| Component | Purpose | Created By | Consumed By |
|---|---|---|---|
| `model/system.dsl` | C4 model (all levels) | Technical architect | Structurizr renders 4 diagrams |
| `src/09_architecture_decisions.adoc` | arc42 decision section | Technical architect | Humans reading arc42 docs |
| `adr/0002-use-postgresql.md` | Full ADR content | Technical architect | Structurizr imports via `!adrs` |
| `docker-compose.yml` | Local preview | Team | `docker compose up` → browser |

### Reference Implementations

- **dzimchuk/architecture-as-code** — Structurizr DSL + arc42 AsciiDoc + ADRs + Docker Compose. The cleanest minimal example. https://github.com/dzimchuk/architecture-as-code
- **milanm/architecture-docs** — Same approach but with PlantUML diagram export and GitHub Pages CI. https://github.com/milanm/architecture-docs
- **bitsmuggler/arc42-c4-example** — arc42 template filled out for an Internet Banking System. https://bitsmuggler.github.io/arc42-c4-software-architecture-documentation-example/

---

## 5. Tool Comparison

| Criteria | Structurizr | C4-PlantUML | Mermaid |
|---|---|---|---|
| **Model consistency** | Single model → all 4 diagrams | Per-file includes | Per-file manual |
| **Learning curve** | Medium (DSL syntax) | Low (PlantUML) | Low |
| **ADR integration** | Native (`!adrs` keyword) | None | None |
| **arc42 integration** | Native (`!docs` keyword) | None | None |
| **CI readiness** | CLI + Docker image | PlantUML CLI | `mmdc` CLI |
| **GitHub rendering** | No (needs Structurizr viewer) | Via PlantUML GitHub Action | Native (if flowchart syntax) |
| **Local preview** | Structurizr Lite (Docker) | PlantUML server | VS Code plugins |
| **Layout** | Auto + manual (drag to arrange) | Auto only | Auto via `---` direction |

## 6. Further Reading

- Structurizr DSL cookbook: https://docs.structurizr.com/dsl/cookbook/
- Structurizr DSL language reference: https://docs.structurizr.com/dsl/language
- Structurizr ADR integration: https://docs.structurizr.com/dsl/adrs
- Structurizr "as code" philosophy: https://docs.structurizr.com/as-code
- C4-PlantUML: https://github.com/plantuml-stdlib/C4-PlantUML
- docToolChain: https://github.com/docToolchain/docToolchain
- dzimchuk AaC example: https://github.com/dzimchuk/architecture-as-code
- milanm AaC example: https://github.com/milanm/architecture-docs
- CI pipeline templates (GitHub Actions, GitLab CI, ForgeJo): `references/ci-pipeline-templates.md`
    • c4-to-pyramid-mapping.md 1.8 KB 
      # C4-to-Pyramid Mapping

## Mapping Table

| C4 Level | Pyramid Layer | Mermaid Path | Structurizr DSL Path | Consumer |
|----------|--------------|--------------|----------------------|----------|
| Level 1: System Context | **L1** (01-summary/) | 01-summary/system-context.md | `docs/arch/model/system.dsl` (systemContext view) | Any stakeholder needing the big picture |
| Level 2: Container | **L2** (02-analysis/) | 02-analysis/structural-views/container.md | `docs/arch/model/system.dsl` (container view) | Developers, integrators |
| Level 3: Component | **L2** (02-analysis/) | 02-analysis/structural-views/components.md | `docs/arch/model/system.dsl` (component view) | Component developers |
| Level 4: Code | **L3** (03-dossiers/) | 03-dossiers/code-level-detail.md | `docs/arch/model/system.dsl` (code view) | Implementers, code reviewers |

**Note on Structurizr DSL paths:** All four C4 levels are defined in a single `system.dsl` file. The `system.dsl` path is the same for all levels because Structurizr generates all diagrams from one model. The difference is which **view** is rendered: `systemContext` for L1, `container` for L2, `component` for L3, `code` for L4. See `references/architecture-as-code-ecosystem.md` for the full Structurizr reference.

## Why C4 Maps Cleanly

C4 is the only architecture methodology with a built-in depth hierarchy. Its four zoom levels correspond naturally to the three pyramid layers (with Levels 2-3 both resolved as separate L2 analysis files). No other methodology maps this cleanly.

## Key Principle

C4 is fundamentally a visual notation. It communicates structure to someone who already understands the domain. It does NOT communicate rationale (that's ADRs) or constraints (that's arc42). The three methodologies are complementary, not competitive.
    • ci-pipeline-templates.md 10.3 KB 
      # CI Pipeline Templates for Architecture Documentation

Platform-specific CI/CD pipeline templates for automating Structurizr-based architecture documentation — validation, diagram export, static site generation, and deployment.

All templates use the **Docker image** `structurizr/cli:latest` to avoid Java runtime dependencies on CI runners.

## Pipeline Stages (Common Across Platforms)

Every pipeline follows the same logical sequence:

```
1. validate  →  structurizr-cli validate -w docs/arch/model/system.dsl
2. inspect   →  structurizr-cli inspect -w docs/arch/model/system.dsl
3. export    →  structurizr-cli export -w docs/arch/model/system.dsl -format mermaid -output site/diagrams
4. site      →  structurizr-cli export -w docs/arch/model/system.dsl -format static -output site
5. deploy    →  Platform-specific Pages or artifact publishing
```

Not all stages run on every trigger. PRs typically run only stages 1-2 (validation). Merges to main run the full pipeline.

---

## 1. GitHub Actions

### Pipeline A: PR Validation (Stages 1-2 Only)

Path: `.github/workflows/validate-architecture.yml`

```yaml
name: Validate Architecture Docs
on:
  pull_request:
    paths:
      - 'docs/arch/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Structurizr DSL
        uses: docker://structurizr/cli:latest
        with:
          args: validate -w docs/arch/model/system.dsl

      - name: Inspect for architectural drift
        uses: docker://structurizr/cli:latest
        with:
          args: inspect -w docs/arch/model/system.dsl
```

### Pipeline B: Full Deploy to GitHub Pages (Stages 1-5)

Path: `.github/workflows/deploy-architecture-site.yml`

```yaml
name: Deploy Architecture Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/arch/**'

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Structurizr DSL
        uses: docker://structurizr/cli:latest
        with:
          args: validate -w docs/arch/model/system.dsl

      - name: Inspect for architectural drift
        uses: docker://structurizr/cli:latest
        with:
          args: inspect -w docs/arch/model/system.dsl

      - name: Export Mermaid diagrams
        uses: docker://structurizr/cli:latest
        with:
          args: export -w docs/arch/model/system.dsl -format mermaid -output site/diagrams

      - name: Export static site
        uses: docker://structurizr/cli:latest
        with:
          args: export -w docs/arch/model/system.dsl -format static -output site

      - name: Upload Pages artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: site

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4
```

### Alternative: Marketplace Action

A community action `structurizr/structurizr-cli-action` wraps the CLI as a dedicated action step:

```yaml
- name: Validate with marketplace action
  uses: structurizr/structurizr-cli-action@v1
  with:
    args: validate -w docs/arch/model/system.dsl
```

The Docker-based approach above is more portable and works identically on ForgeJo.

---

## 2. GitLab CI

Path: `.gitlab-ci.yml`

```yaml
stages:
  - validate
  - export
  - pages

validate-architecture:
  stage: validate
  image:
    name: structurizr/cli:latest
    entrypoint: [""]
  script:
    - /usr/local/structurizr-cli/structurizr.sh validate -w docs/arch/model/system.dsl
    - /usr/local/structurizr-cli/structurizr.sh inspect -w docs/arch/model/system.dsl
  only:
    changes:
      - docs/arch/**/*
  except:
    - main

export-diagrams:
  stage: export
  image:
    name: structurizr/cli:latest
    entrypoint: [""]
  script:
    - /usr/local/structurizr-cli/structurizr.sh export -w docs/arch/model/system.dsl -format mermaid -output public/diagrams
    - /usr/local/structurizr-cli/structurizr.sh export -w docs/arch/model/system.dsl -format static -output public
  artifacts:
    paths:
      - public
  only:
    - main

pages:
  stage: pages
  script:
    - echo "Publishing architecture documentation to GitLab Pages"
  artifacts:
    paths:
      - public
  only:
    - main
  environment: production
```

**Notes:**
- The `entrypoint: [""]` override is required to use the Structurizr CLI as a command rather than a long-running process
- GitLab Pages serves from the `public/` directory — the export step targets `public/` directly
- The `except: main` on validate ensures it runs on feature branches but not on the main branch (redundant with `only: changes` but explicit)

---

## 3. ForgeJo (Gitea Actions)

ForgeJo is a fork of Gitea. Gitea 1.19+ ships **Gitea Actions** as a built-in CI/CD solution — a GitHub Actions compatible runner using `act`. Workflows go in `.gitea/workflows/` and use the same syntax as GitHub Actions.

### Pipeline A: PR Validation

Path: `.gitea/workflows/validate-architecture.yml`

```yaml
name: Validate Architecture Docs
on:
  pull_request:
    paths:
      - 'docs/arch/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Structurizr DSL
        uses: docker://structurizr/cli:latest
        with:
          args: validate -w docs/arch/model/system.dsl

      - name: Inspect for architectural drift
        uses: docker://structurizr/cli:latest
        with:
          args: inspect -w docs/arch/model/system.dsl
```

### Pipeline B: Full Deploy (Artifact-based)

Path: `.gitea/workflows/deploy-architecture.yml`

```yaml
name: Build Architecture Documentation
on:
  push:
    branches: [main]
    paths:
      - 'docs/arch/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Structurizr DSL
        uses: docker://structurizr/cli:latest
        with:
          args: validate -w docs/arch/model/system.dsl

      - name: Export Mermaid diagrams
        uses: docker://structurizr/cli:latest
        with:
          args: export -w docs/arch/model/system.dsl -format mermaid -output site/diagrams

      - name: Export static site
        uses: docker://structurizr/cli:latest
        with:
          args: export -w docs/arch/model/system.dsl -format static -output site

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: architecture-docs
          path: site
```

**Deploy note:** Gitea/ForgeJo does not have a built-in Pages deployment in all versions (unlike GitHub Pages or GitLab Pages). Options for hosting the generated static site:

1. **Download artifact manually** — developers download from the Actions run page
2. **External hosting** — add a step to rsync/scp to a web server:
   ```yaml
   - name: Deploy to web server
     run: |
       rsync -avz --delete site/ user@server:/var/www/architecture/
   ```
3. **Woodpecker CI** — if your ForgeJo instance uses Woodpecker instead of Gitea Actions, see the note below

### Woodpecker CI Alternative

If the ForgeJo instance uses Woodpecker CI (not Gitea Actions), the schema is different:

```yaml
# .woodpecker.yml
pipeline:
  validate:
    image: structurizr/cli:latest
    commands:
      - /usr/local/structurizr-cli/structurizr.sh validate -w docs/arch/model/system.dsl
      - /usr/local/structurizr-cli/structurizr.sh inspect -w docs/arch/model/system.dsl
    when:
      path:
        include: [docs/arch/**]

  export:
    image: structurizr/cli:latest
    commands:
      - /usr/local/structurizr-cli/structurizr.sh export -w docs/arch/model/system.dsl -format mermaid -output site/diagrams
      - /usr/local/structurizr-cli/structurizr.sh export -w docs/arch/model/system.dsl -format static -output site
    when:
      branch: main

  deploy:
    image: alpine:latest
    commands:
      - echo "Site generated in ./site — deploy via rsync, S3, or artifact download"
    when:
      branch: main
```

---

## 4. Pipeline Selection Guide

| Situation | Trigger | Stages | Pipeline |
|---|---|---|---|
| PR changes architecture docs | `pull_request` | 1-2 (validate + inspect) | Short validation |
| Merge to main | `push main` | 1-5 (full pipeline) | Full deploy |
| Ad-hoc manual run | `workflow_dispatch` | 1-5 (full pipeline) | Full deploy |

---

## 5. Customization Notes

### Path Scoping

All templates use `docs/arch/**` as the path filter. Adjust to match your actual architecture directory:

| Directory Convention | Path Pattern |
|---|---|
| AaC standard (`docs/arch/`) | `docs/arch/**` |
| ADR + docs (`docs/adr/`, `docs/`) | Add multiple paths: `['docs/adr/**', 'docs/model/**']` |
| Root-level (`model.dsl` at project root) | `*.dsl` |
| Monorepo with multiple systems | `services/*/docs/arch/**` |

### PNG/SVG Export Limitation

The Structurizr CLI can only export Mermaid, PlantUML, DOT, and static HTML. For PNG/SVG rendering, you need headless Chrome + Puppeteer. Scripts are available at:

https://github.com/structurizr/puppeteer

This adds significant CI complexity (Chrome installation, rendering time). For most CI pipelines, the static HTML site with interactive diagrams (Mermaid) is sufficient.

### vNext Migration

The Structurizr CLI is deprecated in favor of new vNext commands. When vNext stabilizes:
- The binary name may change (`structurizr.sh` → `structurizr`)
- Flag syntax may change (`-workspace` → `--workspace`)
- The pipeline structure (validate → export → deploy) and Docker image (`structurizr/cli`) will remain the same

Monitor https://docs.structurizr.com/commands for updates.

### Trigger on Specific File Types

To only run when the DSL or ADR files change (not images or unrelated docs):

```yaml
paths:
  - 'docs/arch/model/**/*.dsl'
  - 'docs/arch/adr/**/*.md'
  - 'docs/arch/src/**/*.adoc'
```

---

## 6. Further Reading

- Structurizr CLI installation: https://docs.structurizr.com/cli/installation
- Structurizr CLI export: https://docs.structurizr.com/cli/export
- Structurizr static site: https://docs.structurizr.com/static
- GitHub Actions marketplace (Structurizr): https://github.com/marketplace/actions/structurizr-cli-action
- Gitea Actions overview: https://docs.gitea.com/usage/actions/overview
- Woodpecker CI: https://woodpecker-ci.org/
    • source-index.md 381 B 
      # Source index

- **Source repository:** https://github.com/magnus919/hermes-profiles
- **Inspected commit:** `867a555`
- **Imported source directory:** `architecture/c4-diagramming`
- **Porting boundary:** Retained portable methodology, templates, scripts, and references. Removed or generalized Hermes profile, task-orchestration, memory, and rigid response-handoff assumptions.
    • technical-diagram-communication.md 3.3 KB 
      # C4 Diagram Communication Review

Use this reference after the C4 level and model scope are chosen, and before calling a diagram complete. It improves the communication artifact without changing C4 ownership.

## 1. Audience and job

Write one sentence for the primary reader and the decision or task the view supports. For example: "A new maintainer needs to locate the system boundary and its external dependencies before changing the import path." If different readers need different jobs, produce separate views or a short sequence rather than one overloaded diagram.

## 2. Abstraction and representation

- Keep every element at the selected C4 level unless a deliberate reference to an adjacent level is labeled and explained.
- Use one vocabulary for people, systems, containers, components, code, stores, and relationships; do not make shape or color carry an undocumented category.
- Keep boundaries meaningful: a boundary should represent a real ownership or modeling scope, not a decorative grouping.
- Make relationship direction, interaction purpose, and technology detail comparable across the view. Do not label one edge with a protocol while labeling another with an unresolved business claim.
- Preserve the same element identity and naming across related C4 views. If a view omits an element, state that it is out of scope rather than implying it does not exist.

## 3. Narrative and visual hierarchy

Give the reader an entry point and an intended read order. Use title, short purpose statement, boundary order, spatial grouping, and relationship emphasis to lead from context to the claim that matters. Keep the primary path visually dominant; demote supporting paths and move implementation detail to a deeper view. A legend explains notation, not the story, so do not use it as a substitute for a caption.

Reduce signal loss by removing relationships that do not support the stated job, splitting dense views, shortening labels, and moving rationale to an ADR or accompanying prose. More nodes and edges are not evidence of completeness.

## 4. Labels, legend, and uncertainty

Use names that a reader can recognize without decoding internal abbreviations. Label relationships with the interaction or dependency the reader needs to understand. Add a legend only for non-obvious shapes, line styles, or categories, and keep it consistent with the diagram. Mark inferred, proposed, stale, or unknown elements and relationships in text or a documented line style; never imply certainty through polished layout.

## 5. Accessibility and review evidence

Meaning must survive grayscale, color-vision differences, zoom, small screens, and a text-only reading path. Pair color with labels, shapes, line styles, or explicit annotations. Provide a concise textual summary or table that names boundaries, elements, relationships, reading order, and uncertainty. Route full WCAG/ARIA and assistive-technology evaluation to `web-accessibility`.

Capture review evidence: audience/job, selected C4 level, source/model validation, rendered-tool and version, viewport or output surface, accessibility fallback, uncertainty register, reviewer, date, and concrete findings or accepted exceptions. Review the rendered result, not only the DSL or Mermaid source. A valid model and valid syntax are necessary but insufficient; a diagram can pass both and still fail its communication job.
  • README.md 2.2 KB 
    # C4 Diagramming

Make system boundaries, responsibilities, and relationships legible at the architectural level appropriate to the reader.

## Why Install This Skill

Make system boundaries, responsibilities, and relationships legible at the architectural level appropriate to the reader. It preserves a practical method, local reference material, and reusable templates so an agent can do more than produce a generic answer.

Use it when the work needs a repeatable process and an inspectable result. It is portable across Agent Skills-compatible clients and does not require a profile system or a particular task orchestrator.

## What You Get

| Path | What it provides |
|---|---|
| `SKILL.md` | Trigger conditions, workflow, and guidance for loading deeper resources. |
| `references/` | Reference material for C4 levels, architecture-as-code tooling, CI, and communication review, including `technical-diagram-communication.md`. |

## Quick Start

Choose the C4 level and authoring format in `SKILL.md`, load the matching reference before drawing, and review the rendered artifact for the audience's job rather than syntax alone.

Install or expose this directory using your agent's standard Agent Skills loading mechanism, then ask for work that matches the triggers below.

## Triggers

- Create C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need clear system context, container, component, or code-level views.
- Requests involving the method, deliverables, or review process described in `SKILL.md`.
- Requests to make a C4 diagram understandable to a particular audience or to review its hierarchy, narrative, labels, uncertainty, or accessible fallback.
- Work where a reusable template or reference from this skill would reduce avoidable mistakes.

## Requirements

Mermaid or Structurizr tooling is optional and only needed to render or validate diagrams.

## Source and maintenance

This skill was extracted from [`magnus919/hermes-profiles`](https://github.com/magnus919/hermes-profiles) at commit [`867a555`](https://github.com/magnus919/hermes-profiles/commit/867a555). The portable methodology was retained; Hermes-specific profile, orchestration, and memory assumptions were removed.
  • SKILL.md 7.7 KB 
    ---
name: c4-diagramming
description: Create and review C4 software-architecture diagrams using Mermaid or Structurizr. Use when teams need a communication-ready system context, container, component, or code-level view, including audience, narrative, hierarchy, labels, legends, accessibility, and uncertainty. Do not use for Mermaid syntax/rendering work without C4 modeling, architecture decisions, or full accessibility conformance reviews.
license: MIT
compatibility: Mermaid or Structurizr tooling is optional and only needed to render or validate diagrams.
metadata:
  source_repo: https://github.com/magnus919/hermes-profiles
  source_commit: 867a555
---


# C4 Diagramming

C4 Model for structural architecture visualization. Produces diagrams at four zoom levels, mapped into the artifact pyramid.

## C4-to-Pyramid Mapping

| C4 Level | Pyramid Layer | Path |
|----------|--------------|------|
| Level 1: System Context | L1 (Summary) | 01-summary/system-context.md |
| Level 2: Container | L2 (Analysis) | 02-analysis/structural-views/container.md |
| Level 3: Component | L2 (Analysis) | 02-analysis/structural-views/components.md |
| Level 4: Code | L3 (Dossiers) | 03-dossiers/code-level-detail.md |

C4 is the cleanest structural fit — its four-level hierarchy maps to the three pyramid layers with almost no translation, and Levels 2-3 both resolve to separate L2 analysis files.

## Communication Gate

Before choosing notation or polishing layout, state the audience and the job the reader must complete. Select one C4 level that answers that job; do not mix system context, container, component, and code claims merely to fill a canvas. Keep the abstraction level, element vocabulary, boundary treatment, and relationship meaning consistent within a view. A structurally valid C4 model can still be the wrong communication artifact if it asks the reader to infer the purpose, mixes levels, hides important paths, or overwhelms the intended reader.

Load `references/technical-diagram-communication.md` when creating, revising, or reviewing a diagram for a real audience. Use its review record to check narrative/read order, visual hierarchy, labels and legends, signal-to-noise, color-independent meaning, accessibility handoff, uncertainty, and review evidence. Full accessibility conformance remains owned by `web-accessibility`; architecture decisions remain owned by `software-architecture`.

## Review Evidence

Record the intended audience and question, C4 level and scope, key claim, known uncertainty, target renderer, and an accessible text or tabular fallback. Review both the source model and the rendered artifact. A passing syntax/model validator proves structural validity only; it does not prove that the diagram communicates the intended claim.

## Authoring Formats

### Mermaid (Default for Quick Diagrams)

Use when you need a single diagram embedded in markdown. See the GitHub Rendering Constraint section below for C4-in-Mermaid compatibility notes.

### Structurizr DSL (Recommended for Long-Lived Projects)

Structurizr DSL is the C4 model's reference "models as code" implementation, created by Simon Brown. Define the entire architecture model in a single DSL file; all 4 C4 levels are generated from it. This ensures structural consistency across diagrams that hand-written Mermaid cannot guarantee.

```
workspace {
    model {
        user = person "Customer"
        system = softwareSystem "Your System" {
            webapp = container "Web Application" "TypeScript, React"
            api = container "API" "Go"
            db = container "Database" "PostgreSQL"
            user -> webapp "Uses"
            webapp -> api "Makes API calls"
            api -> db "Reads/writes"
        }
    }
    views {
        systemContext system { include * autolayout lr }
        container system { include * autolayout lr }
        component api { include * autolayout lr }
        theme default
    }
}
```

**Key capabilities:**
- `!adrs docs/adr` — imports Architecture Decision Records (adr-tools, MADR, log4brains) into the workspace, rendered alongside C4 diagrams
- `!docs docs/arc42` — imports arc42 documentation as Markdown/AsciiDoc
- Structurizr Lite (Docker) — local preview at http://localhost:8081
- CI commands: `validate`, `inspect`, `export` (PlantUML, Mermaid, static site)

Full reference in `references/architecture-as-code-ecosystem.md` — tool comparison, DSL cookbook, C4-PlantUML alternative, and the converged repo convention.

## Contents

- `references/c4-to-pyramid-mapping.md` — context→L1, container/component→L2, code→L3 (Mermaid + Structurizr DSL paths)
- [`c4-to-flowchart.md`](../mermaid-diagrams/references/c4-to-flowchart.md) — companion Mermaid conversion patterns for GitHub-compatible flowcharts
- `references/architecture-as-code-ecosystem.md` — Structurizr DSL, C4-PlantUML, docToolChain, converged repo convention, tool comparison table
- `references/ci-pipeline-templates.md` — GitHub Actions, GitLab CI, ForgeJo (Gitea Actions, Woodpecker) pipeline templates for Structurizr validation, export, deploy

## GitHub Rendering Constraint

GitHub's built-in Mermaid renderer does **not** bundle the C4 plugin (`@mermaid-js/mermaid`). Any ````mermaid` block using `C4Context`, `C4Container`, or `C4Component` syntax renders as raw code rather than a diagram on GitHub. This affects issues, PR descriptions, discussion comments, and markdown files.

**Workaround:** Convert C4 diagrams to standard `flowchart` syntax before embedding in GitHub markdown:
- `Person()` → `[rect]` node with label
- `System()` / `System_Ext()` → `[rect]` inside or outside subgraphs
- `Container()` → `[rect` with tech stack label]`
- `Db()` → `[(cylinder shape)]`
- `System_Boundary{}` / `Container_Boundary{}` → `subgraph ... end`
- `Rel()` → `-- label -->` or `-.->`
- Drop `UpdateLayoutConfig()` — use `flowchart LR` or `TB` directive instead

For the full conversion table with worked examples, load [`c4-to-flowchart.md`](../mermaid-diagrams/references/c4-to-flowchart.md) from the companion `mermaid-diagrams` skill when it is available.

**.mmd files in a DIAGRAMS/ directory** must also use standard flowchart syntax if they need to render via `mmdc` or on GitHub. Files using C4-plugin syntax can only render in tools that bundle the plugin (e.g., Mermaid Live Editor, mmdc with C4 extension config). If you commit `.mmd` files with C4 syntax to a repo, GitHub's file preview will show them as raw text — convert them to standard syntax or render them to PNG first.

## Feature Request Filed

A GitHub Community feature request to bundle the C4 mermaid plugin was filed at https://github.com/orgs/community/discussions/197898 (closed — requires submission through the web UI with the Apps, API and Webhooks discussion template). If this gets implemented, the flowchart conversions below would no longer be necessary for GitHub rendering.

## Canonical Reference

- Simon Brown, "The C4 Model" — https://c4model.com/
- GroktoPlan C4 Diagrams (worked examples) — https://github.com/groktopus/groktoplan/blob/main/TECHNICAL_ARCHITECTURE.md

## Portability

This skill is intentionally host-neutral. Use your agent's normal mechanisms to load the references, templates, and scripts listed here. Do not assume a particular profile system, task orchestrator, memory service, or response-handoff format.

## When not to use

- Use `mermaid-diagrams` for Mermaid grammar, renderer compatibility, layout, and export troubleshooting that does not require C4 level/model decisions.
- Use `software-architecture` for architecture drivers, tradeoffs, decisions, and fitness evidence; this skill visualizes those decisions rather than owning them.
- Use `web-accessibility` for complete WCAG/ARIA conformance work and assistive-technology evidence; this skill contributes diagram-specific accessibility checks and fallbacks.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude