# C4

> Use when the user wants to create, design, model, visualize, validate, amend, or export a software architecture or C4 diagram — including rendering or checking an existing architecture.json. Triggers include "C4", "Architektur", "architecture", "Systemarchitektur", "system design", "Architekturdiagramm", architecture workshop, NFR/FR modeling, Structurizr export.

- **Type:** Skill
- **Install:** `agentstack add skill-sebastart-c4-skill-architect`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [SeBastArt](https://agentstack.voostack.com/s/sebastart)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [SeBastArt](https://github.com/SeBastArt)
- **Source:** https://github.com/SeBastArt/c4-skill/tree/master/skills/architect

## Install

```sh
agentstack add skill-sebastart-c4-skill-architect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# C4 Architecture Skill

## Overview

This skill creates **interactive C4 architecture diagrams** as self-contained HTML files with embedded SVG. It covers the full pipeline: guided discovery, structured data model (JSON), validation, and rendering.

**Load references on-demand per phase — NOT all at once:**

### Tier 1 — Always (minimal baseline):
- `references/json-schema.md` — Data model definition (v2.2, multi-container, multi-component, FRs + NFRs)
- `references/quality.md` — Validation rules (7 categories S/C/X/T/W/F/V — rule count and details there)

### Tier 2 — Phase 3 (NFR collection):
- `references/pattern-catalog.md` — Navigator: NFR→Pattern Quick-Reference, Pattern-Stacks

### Tier 3 — Phase 5-6 (Container & Component decomposition):
- `references/paradigms-guide.md` — Load when choosing decomposition strategy (DDD, EDA, CQRS, etc.)
- `references/pattern-deep-dive.md` — Load when applying specific patterns to containers/components

### Tier 4 — Phase 8 (Design Decisions):
- `references/decision-frameworks.md` — ADR, Canvas, ATAM, TARA, Quality Scenarios, Scorecards

### Tier 5 — Phase 10 (Render):
- `references/render-spec.md` — SVG, CSS, JS, layout, colors, accessibility
- `references/engine.js.md` — Complete rendering engine reference code
- `templates/base.html` — HTML skeleton template

### On-demand (only when explicitly needed):
- `references/example.json` — Load only to check format/structure when unsure
- `references/structurizr-export.md` — Load only in Export Mode

**Rule:** Never load Tier 3-5 references in Phase 1-2. Never load Tier 5 before Phase 10. This preserves context window for the actual architecture discussion.

## Output

A single self-contained `.html` file containing:
- SVG canvases: Context, Container, 1-N Component views (one per decomposed container), Code
- Tab navigation with breadcrumbs (component tabs show container name)
- Requirements panel (collapsible right sidebar: FRs, NFRs, Design Decisions)
- Code snippet overlays (dark theme, Catppuccin Mocha syntax highlighting)
- Drill-down navigation between levels (double-click)
- Rich tooltips on elements (why, pattern, decisions) and arrows (payload, why, detail)
- Keyboard navigation (Tab between elements, Enter to drill-down, 1-N for levels)
- Accessibility (ARIA labels, skip-link, print CSS)
- All CSS and JS embedded inline — no external dependencies

## Process: Guided Architecture Workshop

Work through these phases **sequentially**. Each phase ends with a confirmation from the user before proceeding. Ask focused questions — do not overwhelm. Summarize your understanding after each phase.

---

### Phase 1: Project Scope

**Goal:** Understand what we are building and for whom.

Ask the user:
1. **System name** — What is this system called?
2. **Core purpose** — What does it do in one sentence?
3. **Primary actors** — Who or what uses the system? (Users, admins, external systems, scheduled jobs)
4. **Key capabilities** — What are the 3-5 most important things the system does? (These become inputs for Phase 2: FRs)
5. **External dependencies** — What external systems does it integrate with? (Payment providers, auth, email, third-party APIs)

**Output:** A summary paragraph that the user confirms.

---

### Phase 2: Functional Requirements (FRs)

**Goal:** Capture what the system must do — structured and testable.

Transform the key use cases from Phase 1 into structured Functional Requirements. For each FR, ask:

1. **Title** — Short name (e.g., "Sitzplatz reservieren")
2. **Description** — What does the system do, from the actor's perspective?
3. **Actor** — Which person/external system triggers this? (Must reference a context-level element ID)
4. **Priority** — MoSCoW: must / should / could / wont
5. **Acceptance Criteria** — 2-5 testable conditions per FR (e.g., "Sitz wechselt zu Status HELD", "Reservierung hat eine TTL von 8 Minuten")

**Rules:**
- Every FR MUST have at least one acceptance criterion — if it's not testable, it's not a requirement
- Use the actor's perspective: "Der Kunde kann..." not "Das System soll..."
- Focus on the "what", not the "how" — implementation details come in later phases
- Group related use cases into one FR when they share the same actor and domain concept
- Mark FRs as `wont` to explicitly document what is out of scope
- Typical projects have 5-15 FRs

**Output:** A numbered FR list with id, title, description, actor, priority, and acceptance criteria.

---

### Phase 3: Non-Functional Requirements (NFRs)

**Goal:** Identify the quality attributes that drive architectural decisions.

Walk through each category and ask if it is relevant. For each relevant NFR, get a **measurable metric**:

| Category | Example Question |
|---|---|
| **Performance** | What peak load do you expect? (requests/sec, concurrent users) |
| **Availability** | What uptime is required? (99.9%? 99.99%?) |
| **Latency** | What response times are acceptable? (p95, p99) |
| **Consistency** | Are there invariants that must never be violated? (e.g., no overselling) |
| **Scalability** | How should the system grow? (horizontal, vertical, auto-scaling) |
| **Security** | Compliance requirements? (PCI-DSS, GDPR, SOC2) Auth model? |
| **Observability** | What must be monitored? (metrics, traces, logs, alerts) |
| **Auditability** | Must actions be traceable? (audit logs, immutable records) |

**Rules:**
- Every NFR MUST have a measurable metric — no vague statements like "should be fast"
- Identify which NFRs will drive architectural decisions (these become inputs for Phase 8)
- Typical projects have 3-7 relevant NFRs

**Pattern-Hinweis:** Nach dem Erfassen aller NFRs, schlage relevante Patterns aus `references/pattern-catalog.md` vor:
- Performance/Latency → CQRS, Cache-aside, CDN, Read Replicas
- Availability → Circuit Breaker, Bulkhead, Retry & Backoff
- Consistency → Outbox, Idempotency, Saga, Event Sourcing
- Scalability → CQRS, EDA, Horizontal Scaling, SCS
- Security → API Gateway, mTLS (Sidecar), ACL
- Observability → Sidecar (OpenTelemetry), Structured Logging
- Auditability → Event Sourcing, Append-only Logs

Frage den User: "Basierend auf den NFRs schlage ich folgende Patterns vor: [...]. Welche davon sind relevant?" Diese Vorauswahl beschleunigt Phasen 5-8.

**Output:** A numbered NFR list with id, category, title, metric, and approach.

---

### Phase 4: Context Level (C4 Level 1)

**Goal:** Define the system boundary — who interacts with the system and what external systems exist.

Build the context diagram by placing:
- **Persons** (human actors) — from Phase 1 actors
- **The main system** (one box representing the entire system)
- **External systems** — from Phase 1 dependencies

For each relationship, define:
- Direction (who initiates?)
- Label (short: what data/action flows?)
- **Detail** (longer: what happens in this communication?)
- **Payload** (for async: what is the event/message structure?)
- **Why** (why does this communication exist?)
- Sync vs. async
- Protocol if known (REST, gRPC, webhook, email)

**Rules:**
- Maximum 8-10 elements at context level. Multiple `system` elements are allowed when modeling a system landscape
- Every person and external system must have at least one relationship
- The main system is always present
- No internal details — this is the 30,000-foot view
- Every async relationship MUST have a payload description
- Each system element that should be decomposed gets `drillDown: "container:"` pointing to its container view

**Output:** Present the context diagram as a structured list for confirmation.

---

### Phase 5: Container Level (C4 Level 2)

**Goal:** Decompose each system into its deployable containers. Each system gets its own container view.

Guide the decomposition by asking about:
1. **API layer** — How do clients reach the system? (API Gateway, Load Balancer, CDN)
2. **Core services** — What are the main processing units? (microservices, monolith modules)
3. **Data stores** — What databases, caches, and queues are needed?
4. **Async infrastructure** — Message brokers, schedulers, background workers?
5. **External integrations** — How does each external system connect?
6. If multiple systems exist in C1, ask: **Which systems should be decomposed?** Create a separate container view per system.

For each container, capture:
- Name, type, technology choice
- Read-heavy vs. write-heavy
- Stateful vs. stateless
- **Why does this container exist?** — Which NFR or business need drives it?
- **Pattern** — What architectural pattern does it implement? (cache-aside, outbox, CQRS, etc.)

For each relationship:
- Source, target, label, protocol
- Sync (solid line) vs. async (dashed line)
- **Detail** — What happens in this communication?
- **Payload** — For async: what is the event structure? (e.g., `{ type: SeatReserved, eventId, seatId }`)
- **Why** — Why is this communication needed? Link to design decision if applicable.

Organize containers into **groups** (logical clusters):
- Core Services
- Persistence / Data Stores
- Async Infrastructure
- External

**Pattern-Stacks anwenden:** Basierend auf den in Phase 3 vorausgewählten Patterns, schlage bewährte Kombinationen vor (siehe `references/pattern-catalog.md`):
- **Event-Driven Consistency:** Outbox + Idempotency + Retry → Service + Outbox-DB + Relay + Broker
- **Resilience:** Circuit Breaker + Retry + Bulkhead → in Services oder als Sidecar
- **CQRS + Event Sourcing:** Command Service + Event Store + Projection + Read DB + Broker
- **Migration:** Strangler Fig + ACL + CDC → Gateway + Legacy + New Services + CDC-Connector
- **Distributed Transactions:** Saga + Outbox + Idempotency → Orchestrator + Services + Broker

Für jeden eingesetzten Pattern:
1. Setze `element.pattern` mit konkreter Beschreibung (z.B. "Outbox Pattern: Poll → Publish → Mark Published")
2. Setze `element.why` mit NFR-Begründung
3. Verknüpfe mit `element.relatedDecisions`

**Rules:**
- Maximum 15-18 elements
- Every container must have at least one inbound or outbound relationship
- Technology choices should be justified by NFRs (e.g., Redis cache because of latency NFR)
- Groups help visual readability — use 3-5 groups
- Every async relationship MUST have a payload and a why
- Every element that implements a pattern MUST document it
- Each system's containers are stored in `containers[""]` — not a single global container level

**Output:** Present the container diagram as a structured list with groups.

---

### Phase 6: Component Level (C4 Level 3)

**Goal:** Show the internal structure of 1-3 key containers. Each gets its own component view.

Ask the user: **Which containers are architecturally interesting?** (Usually the ones with the most business logic or the most complex patterns.)

For each selected container:
- Set `drillDown: "component:"` on the container element
- Create a `components[""]` entry with its own elements, relationships, and groups
- Use `cmp--` prefix for component IDs to avoid collisions

Decompose each container into layers:
1. **API Layer** — Controllers, route handlers, input validation
2. **Business Layer** — Domain services, use cases, business rules
3. **Background Workers** — Event consumers, scheduled jobs, relay processes
4. **Data Access Layer** — Repositories, data mappers, cache strategies

For each component, capture:
- Name, type (controller, service_class, repository, event_handler, background_worker, adapter)
- Key methods/responsibilities (as bullet list)
- Error handling strategy (what HTTP codes, what exceptions)

**Rules:**
- Maximum 12-15 elements per container decomposition
- Every component must connect to at least one other component
- Show the flow: API -> Service -> Repository -> DB
- Include error handling paths (e.g., OptimisticLockError -> 409 Conflict)

**Output:** Present each container's components as a layered list.

---

### Phase 7: Code Level (C4 Level 4)

**Goal:** Show concrete implementation for critical paths.

Identify code snippets for:
1. **Database schemas** — Table definitions, indexes, constraints that enforce NFRs
2. **Critical operations** — The core write path (e.g., reserve, book, release)
3. **Patterns** — Idempotency, caching, outbox, saga — whatever the architecture uses
4. **Error handling** — How does the system handle failures?

For each snippet:
- Language (SQL, TypeScript, Java, Go, etc.)
- Title describing what it shows
- **Why (required)** — One sentence explaining WHY this code is architecturally relevant. What design decision does it prove? What NFR does it enforce? Example: "Zeigt UNIQUE constraint der Idempotency-Key-Duplikate verhindert (DD-01)"
- **Annotations** — Mark 2-4 key lines with inline explanations (shown as `← hint` in the code overlay). Focus on the lines that implement the pattern or enforce the NFR.
- Link to the parent element it belongs to

**Rules:**
- Code snippets must be realistic and runnable (not pseudo-code)
- Every database container should have at least one schema snippet
- Every snippet MUST have a `why` field — code without context is useless
- Every snippet SHOULD have 2-4 line annotations for the architecturally significant lines
- Show the patterns that justify design decisions
- Maximum 8-10 snippets — focus on the interesting parts

**Output:** Present code snippets for review.

---

### Phase 8: Design Decisions

**Goal:** Document the key architectural decisions with trade-offs.

For each important decision:
1. **Title** — What was decided? (e.g., "Outbox Pattern for Event Publishing")
2. **Context** — What problem does this solve?
3. **Decision** — What was chosen and why?
4. **Trade-off** — What are the downsides?
5. **Alternatives** — What else was considered?
6. **Related NFRs** — Which NFRs drive this decision?
7. **Related FRs** — Which FRs does this decision support?
8. **Related Elements** — Which containers/components implement this?

**Rules:**
- Every NFR should be addressed by at least one design decision
- Every `must`-priority FR should be traceable to at least one element
- Decisions must reference concrete elements (not abstract concepts)
- Trade-offs must be honest — every decision has downsides
- Typical projects have 3-7 design decisions
- Every pattern used in Phase 5/6 MUST have a corresponding design decision

**Qualitäts-Szenario pro Decision:** Für jede Design Decision, formuliere mindestens ein Qualitäts-Szenario nach dem Template:
```
Wenn [Stimulus] unter [Bedingung] dann [erwartete Reaktion] gemessen an [Metrik]
```
Beispiel: "Wenn der Kafka-Broker ausfällt, unter normaler Last, dann bleiben Events in der Outbox und werden nach Recovery innerhalb von -`)
4. Ensure all relationships use `async: true/false` (boolean, not `protocol: "async"`)
5. Run ALL validation rules from `references/quality.md` (all 7 categories)
6. Fix any errors, warn about warnings
7. Write the validated `architecture.json` to disk

**Validation is not optional.** Every architecture must pass at minimum:
- All structural integrity rules (Category S) — zero errors
- All completeness rules (Category C) — zero errors, warnings acceptable
- All cross-level consistency rules (Category X) — warnings acceptable

---

### Phase 10: Render

**Goal:** Generate an interactive, draggable HTML visualization.

**Architecture:** All SVG content is rendered dynamically from a JavaScript `C4` data object. No hardcoded SVG paths. This enables drag & drop with auto-updating arrows and groups.

**Steps:**
1. Load `templates/base.html` as skeleton
2. Load `references/engine.js.md` — use the **complete rendering engine code** from this reference
3. Follow `references/render-spec.md` for all visual and interaction decisions
4. Build the `C4` JavaScript data object from architecture.json:
   - `C4.colors` — type-to-color mapping (from render-spec color palette)
   - `C4.levels.context` — elements with ALL fields (see render-spec JS data structure)
   - `C4.levels.containers[""]` — one entry per system, same structure
   - `C4.le

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [SeBastArt](https://github.com/SeBastArt)
- **Source:** [SeBastArt/c4-skill](https://github.com/SeBastArt/c4-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-sebastart-c4-skill-architect
- Seller: https://agentstack.voostack.com/s/sebastart
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.