C4 Blueprint

C4 architecture diagrams for any project — a framework-agnostic agent module that reads your existing planning artifacts and guides you through building properly-leveled C4 model diagrams with strict abstraction boundary enforcement.

Works with BMAD, SpecKit, plain markdown, or custom documentation structures. No framework required.

What It Does

C4 Blueprint introduces Diana, a C4 Architecture Modeler agent who:

1. Detects your planning framework — BMAD, SpecKit, or plain markdown docs
2. Scans your planning artifacts — PRD personas become People, integrations become External Systems, tech stack becomes Container labels
3. Classifies every element by C4 level — enforces that databases don't leak onto System Context diagrams and modules don't appear as Containers
4. Shows you a draft diagram first — then asks about gaps, not everything from scratch
5. Produces Mermaid diagrams — saved as versioned artifacts that chain into each other

PRD ──→ Level 1: System Context  (people, system, external systems)
         ↓
Architecture ──→ Level 2: Container  (apps, APIs, databases, queues)
                  ↓
                 Level 3: Component  (modules within a container)

Epics/Stories ──→ Dynamic Diagrams   (interaction sequences)

Supported Frameworks

| Framework | Artifact Locations | Install Path | |-----------|-------------------|--------------| | BMAD Method | _bmad-output/, planning_artifacts/ | bmad/c4b/ | | SpecKit | specs/, .speckit/ | .speckit/modules/c4b/ | | Plain Markdown | docs/, project root | .c4-blueprint/ | | Custom | You define the paths | .c4-blueprint/ |

The installer auto-detects your framework. Each framework has an adapter that maps your documentation structure to C4 extraction patterns.

Installation

Quick Install (npm)

npx c4-blueprint install

The interactive installer will:

1. Detect your framework (BMAD, SpecKit, plain markdown) or let you choose
2. Auto-detect your IDE (Claude Code, Cursor, Windsurf)
3. Copy the module to the right location for your framework
4. Install IDE-specific commands with the right prefix
5. Create the c4/ output directory
6. Write c4/c4b-config.yaml recording your adapter choice

Install with Options

# Specify everything (non-interactive / CI)
npx c4-blueprint install -f bmad -t claude-code -y

# Choose framework, auto-detect IDE
npx c4-blueprint install --framework speckit

# Install into a specific project
npx c4-blueprint install --directory /path/to/project

# Plain markdown project, Cursor IDE
npx c4-blueprint install -f plain -t cursor

CLI Reference

npx c4-blueprint install [options]

Options:
  --directory, -d <path>       Target project directory (default: .)
  --framework, -f <framework>  bmad | speckit | plain | custom (default: auto-detect)
  --tools, -t <ide>            claude-code | cursor | windsurf (default: auto-detect)
  --yes, -y                    Non-interactive mode, accept all defaults
  --help, -h                   Show help

Install from Source

git clone https://github.com/YOUR-ORG/c4-blueprint.git
cd c4-blueprint
npm install
node bin/cli.js install --directory /path/to/project

Manual Install (No Node.js)

Pick your framework's install path, then copy files directly:

# For BMAD projects:
cp -r src/c4b/ /path/to/project/bmad/c4b/
cp ide/claude-code/commands/bmad/*.md /path/to/project/.claude/commands/

# For non-BMAD projects:
cp -r src/c4b/ /path/to/project/.c4-blueprint/
cp ide/claude-code/commands/generic/*.md /path/to/project/.claude/commands/

# Both:
mkdir -p /path/to/project/c4/

Claude.ai (No Installation Needed)

1. Download src/c4b/agents/c4-architect.md
2. Upload it to a Claude.ai conversation
3. Diana activates — works without any project structure
4. Optionally upload your PRD or architecture doc for artifact-informed mode

Usage

Claude Code (BMAD projects)

| Command | Description | |---------|-------------| | /bmad-agent-c4b-architect | Load Diana (interactive agent mode) | | /bmad-c4b-system-context | Create Level 1 System Context diagram | | /bmad-c4b-container | Create Level 2 Container diagram | | /bmad-c4b-component | Create Level 3 Component diagram | | /bmad-c4b-extract | Scan artifacts, show C4 elements by level | | /bmad-c4b-review | Review existing diagrams against rules |

Claude Code (all other frameworks)

| Command | Description | |---------|-------------| | /c4b-architect | Load Diana (interactive agent mode) | | /c4b-system-context | Create Level 1 System Context diagram | | /c4b-container | Create Level 2 Container diagram | | /c4b-component | Create Level 3 Component diagram | | /c4b-extract | Scan artifacts, show C4 elements by level | | /c4b-review | Review existing diagrams against rules |

Cursor / Windsurf / Other IDEs

Load the agent file directly and instruct the AI to read and follow its activation instructions. The agent auto-detects its location and adapter config.

Recommended Workflow Order

1. extract            ← See what artifacts exist
2. system-context     ← Build Level 1 first
3. container          ← Then Level 2
4. component          ← Then Level 3 per container

How Adapters Work

Each framework adapter is a YAML file that tells Diana:

• Where to find artifacts — file paths for PRD, architecture doc, epics
• How to parse them — which markdown headings contain personas, integrations, etc.
• Where to install — module directory and command prefix

# Example: adapters/bmad.yaml (simplified)
adapter:
  id: bmad
  artifact_paths:
    prd:
      - _bmad-output/PRD.md
      - planning_artifacts/prd.md
    architecture:
      - _bmad-output/architecture.md
  prd_sections:
    personas: "## Personas|## User Types"
    integrations: "## External Integrations"

Custom Adapter

For projects with non-standard documentation:

1. Install with --framework custom
2. Edit adapters/custom.yaml in the installed module
3. Set your file paths and section headings
4. Diana uses your custom paths for extraction

What Gets Installed

BMAD Project Layout

your-project/
├── bmad/
│   └── c4b/                          # C4 Blueprint module
│       ├── config.yaml
│       ├── agents/
│       │   ├── c4-architect.md        # Generic agent
│       │   └── c4-architect.bmad.md   # BMAD v6 format agent
│       ├── workflows/                 # L1, L2, L3, Dynamic, Deploy, Review
│       ├── tasks/                     # Artifact extraction (adapter-aware)
│       ├── data/                      # Abstraction classification rules
│       ├── checklists/                # Quality gates
│       ├── templates/                 # Working model YAML
│       └── adapters/                  # Framework configs
│           ├── bmad.yaml
│           ├── speckit.yaml
│           ├── plain.yaml
│           └── custom.yaml
├── .claude/commands/                  # BMAD-prefixed slash commands
│   ├── bmad-agent-c4b-architect.md
│   └── bmad-c4b-*.md
└── c4/                                # Diagram output
    ├── c4b-config.yaml                # Runtime adapter config
    ├── 01-system-context.mmd          # (generated)
    ├── 02-container.mmd               # (generated)
    └── c4-working-model.yaml          # (generated)

Non-BMAD Project Layout

your-project/
├── .c4-blueprint/                     # C4 Blueprint module
│   ├── (same structure as above)
│   └── ...
├── .claude/commands/                  # Generic-prefixed slash commands
│   ├── c4b-architect.md
│   └── c4b-*.md
└── c4/                                # Diagram output
    └── ...

Architecture Concepts

Abstraction Boundary Enforcement

Every element is classified to exactly one level:

• "Would this exist without our system?" → External System (L1)
• "Is this separately deployable?" → Container (L2)
• "Is this a code module inside a deployable?" → Component (L3)

Level Chaining

Each diagram feeds the next. The working model carries deferred elements forward:

L1 confirms people + external systems
  → L2 inherits them as context, adds containers
    → L3 inherits containers as context, adds components

Differential Elicitation

Diana only asks about what she could NOT find in your planning documents. If your PRD says "integrates with Stripe" but does not specify protocol, she asks only about the protocol — not whether Stripe exists.

Current Status

| Component | Status | |-----------|--------| | Agent definition (Diana) — generic + BMAD format | ✅ Complete | | Framework adapters (BMAD, SpecKit, plain, custom) | ✅ Complete | | Abstraction classification rules | ✅ Complete | | Artifact extraction (adapter-aware) | ✅ Complete | | System Context workflow (L1) | ✅ Complete | | Container workflow (L2) | ✅ Complete | | Diagram review checklist | ✅ Complete | | Working model template | ✅ Complete | | npm installer (interactive + CI) | ✅ Complete | | Claude Code commands (BMAD + generic sets) | ✅ Complete | | Cursor / Windsurf rules | ✅ Complete | | Component workflow (L3) | 📋 Planned | | Dynamic diagram workflow | 📋 Planned | | Deployment diagram workflow | 📋 Planned | | Review workflow | 📋 Planned |

Upgrading

npx c4-blueprint install

The installer detects existing installations and prompts before overwriting. Your generated diagrams in c4/ are never touched.

Uninstalling

# BMAD projects
rm -rf bmad/c4b/
rm -f .claude/commands/bmad-c4b-*.md .claude/commands/bmad-agent-c4b-architect.md

# Non-BMAD projects
rm -rf .c4-blueprint/
rm -f .claude/commands/c4b-*.md

# Both: optionally remove generated diagrams
rm -rf c4/

About C4

The C4 model by Simon Brown provides four levels of abstraction for software architecture diagrams. C4 Blueprint automates the discipline of keeping each level clean — the hardest part of C4 in practice.

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE