c4m
Interactive C4 architecture diagrams (Simon Brown's model) for Claude Code. Five mode-driven workflows — Design (greenfield), Document-code
Open source Open in the app JSON README (API)
About
Interactive C4 architecture diagrams (Simon Brown's model) for Claude Code. Five mode-driven workflows — Design (greenfield), Document-code (retro-doc from a repo), Document-prose (from README/ADR/spec), Review (critique an existing diagram), Update (evolve one) — accessed via /c4m:auto, /c4m:design, /c4m:code, /c4m:prose, /c4m:review, /c4m:update. Output is one Markdown document per C4 level with embedded Mermaid; format negotiable (Structurizr DSL, PlantUML) and destination negotiable (filesystem or MCP — Notion, Linear, Drive). Enforces the editorial invariants: technology mandatory on every Container/Component, intent-specific relationship labels, protocol on inter-container links, assumptions kept explicit.
Details
- Kind
- Plugins
- Topic
- Media, design & games
- Publisher
- cheriftj
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 37
- Forks
- 2
- Last push
- 2026-04-25T08:23:10Z
- Repository state
- ativo
- Language
- Shell
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
cheriftj/c4-model-skill/c4m
README
# c4-model
A [Claude Code](https://claude.com/claude-code) skill for producing [C4 architecture diagrams](https://c4model.com) (Simon Brown's model), interactively.
[](https://github.com/cheriftj/c4-model-skill/actions/workflows/ci.yml)
[](./LICENSE)
## How it works
When you ask for an architecture diagram (or run `/c4m:auto`), the skill first figures out what you're actually doing. Designing a new system from a vague idea is a different job from retro-documenting an existing codebase, which is different again from reviewing someone else's diagram or updating one you already have.
Once the mode is clear, it runs the matching workflow: a structured dialogue, batches of no more than five questions at a time, with an explicit validation checkpoint at every level. Nothing gets written to disk until you say it's final.
If you already know which mode you want, a dedicated slash command skips the detection step (`/c4m:design`, `/c4m:code`, `/c4m:prose`, `/c4m:review`, `/c4m:update`). Or invoke `/c4m:auto` and let the router pick. See [The 5 modes](#the-5-modes) below.
By default the output is one Markdown document per C4 level (Context, Container, optionally Component) with the diagram embedded as Mermaid. Format and destination are negotiated at the start: Structurizr DSL, PlantUML, or an MCP destination (Notion, Linear, Google Drive) are all on the table.
See [`skills/c4-model/examples/`](./skills/c4-model/examples/) for a filled-out Context + Container pair built from Simon Brown's canonical Internet Banking System.
## Installation
### Claude Code plugin marketplace
```bash
/plugin marketplace add cheriftj/c4-model-skill
/plugin install c4m@c4-model-skill
```
### Copy into a single project
```bash
cp -r path/to/this-repo/skills/c4-model /your/project/.claude/skills/
```
Claude Code auto-discovers skills under `.claude/skills/` in the current project.
### Install for all your projects
```bash
cp -r path/to/this-repo/skills/c4-model ~/.claude/skills/
```
## The 5 modes
Each mode has a dedicated slash command. Claude Code namespaces commands under their plugin, so every command is prefixed with `/c4m:`. Use the auto variant if you want the router to pick the mode; use the mode-specific variants to skip detection.
| Mode | Slash command | Fires on | Flow |
|---|---|---|---|
| **Design** | `/c4m:design` | Vague idea, no code | Framing → Context → Container → optional Component → finalization |
| **Document-code** | `/c4m:code` | You point at a repo | Quick framing → scan (delegates to an Explore sub-agent on large repos) → review → dialogue → deliver |
| **Document-prose** | `/c4m:prose` | You paste a README / ADR / spec | Extraction → gap-filling dialogue → deliver |
| **Review** | `/c4m:review` | You paste a diagram + *"is this good?"* or *"explain this"* | Checklist critique (grouped by severity) or structured narration |
| **Update** | `/c4m:update` | You have a C4 + *"add / remove / change X"* | Read, clarify the diff, update every affected level |
| *(any / unsure)* | `/c4m:auto` | Any of the above | Detects the mode from what follows the invocation, then routes |
Supporting diagrams (System Landscape, C4Deployment, C4Dynamic) are offered on explicit request from within any mode.
## Example conversations
### Design mode (via `/c4m:design` or a natural prompt)
```text
You: /c4m:design I'm building an event-sourced order management system.
Claude: Before we draft anything, a few quick questions (max 5):
1. System name + one-line business intent?
2. Audience (tech team, stakeholder, onboarding)?
3. Which levels: Context only, Context + Container, deeper?
4. Output format? Default is Mermaid + Markdown; alternatives: Structurizr DSL, PlantUML.
5. Destination? Default docs/architecture/, or a Notion/Linear/Drive MCP if available.
You: Orders MS, greenfield. Tech team audience. Context + Container. Defaults.
Claude: Got it. For Context first: who interacts with this system, and what external systems does it depend on?
[... dialogue continues, diagram emerges, user validates each level ...]
You: Finalized, looks good.
Claude: Writing docs/architecture/01-context.md and docs/architecture/02-container.md now.
```
Without the slash command, the same flow is triggered by any architecture-design request (e.g. *"help me design an order management system"*) — the skill's router detects Design mode from the signal.
### Review mode (via `/c4m:review`)
```text
You: /c4m:review
```mermaid
C4Container
title My API
Container(api, "API", "Node")
ContainerDb(db, "DB")
Rel(api, db, "Uses")
```
Claude: 3 issues, grouped by severity.
BLOCKING
- Missing title scope ("My API" doesn't say which system).
- Container(db, "DB") has no technology — mandatory on every Container.
- Rel(api, db, "Uses") is a bare verb — state the intent and the protocol,
e.g. "Reads and writes orders to" with protocol "JDBC".
IMPORTANT
- No legend, no scope/description on the API.
NICE-TO-HAVE
- Consider a System_Boundary around the API + DB for visual grouping.
Want me to apply these corrections? That would switch us to /c4m:update.
```
Other modes (`/c4m:code`, `/c4m:prose`, `/c4m:update`) follow the same shape: explicit slash command, a short framing dialogue, then the deliverable.
## What makes it honest
- **Mode detection first.** Don't generate if we don't know what you want.
- **Simon Brown's golden rule.** Context + Container are enough for most teams; Component only on explicit request.
- **One Markdown document per level.** Never a bare Mermaid block.
- **Relation labels state intent.** *"Uses"*, *"Calls"*, *"Reads"* are banned on their own.
- **Technology is mandatory** on every Container and Component.
- **Assumptions stay explicit.** Inferences never slip silently into the diagram.
- **Grounded in authority.** The Mermaid syntax reference is rebuilt from [mermaid.js.org](https://mermaid.js.org/syntax/c4.html); the review checklist from [c4model.com](https://c4model.com/diagrams/checklist). Editorial additions are separated from sourced content.
## Contributing
Bug fixes, wording improvements, and new modes are all welcome. For anything larger than a typo, open an issue first so we can agree on scope before code is written. See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the editorial invariants, the PR checklist, and the release process. This project follows the [Contributor Covenant Code of Conduct](./CODE_OF_CONDUCT.md).
## License
MIT. See [LICENSE](./LICENSE).
## Credits
The [C4 model](https://c4model.com) is by [Simon Brown](https://simonbrown.je/); the example deliverables in this repo use his canonical [Internet Banking System](https://c4model.com/diagrams). The Mermaid C4 syntax comes from the [Mermaid](https://mermaid.js.org/) project.