C4 Architect

Generate C4 model diagrams for the current project. Output: Mermaid .md files in docs/architecture/.

What to generate

Invocation modes

Workflow

1. Read existing diagrams in docs/architecture/ (if any)
2. Scan the project to build the architecture model:
   • Package.json / Gemfile / pyproject.toml → tech stack
   • Directory structure → containers and components
   • API routes, DB schemas, external service calls → relationships
   • Environment variables → external dependencies
   • Existing CLAUDE.md / README → documented architecture
3. Diff against existing diagrams — only regenerate what changed
4. Generate Mermaid using C4 notation (see reference/mermaid-c4.md)
5. Write files to docs/architecture/
6. Report what changed and why — flag any arrows that were added/removed

Diagram format

Each file follows this template:

# C[N] [Level Name] — [Project Name]

> Auto-generated by c4-architect. Last updated: YYYY-MM-DD
> Manual edits will be overwritten on next refresh.

```mermaid
C4Context
  title System Context — [Project]
  ...
`` `

## What changed
- [bullet list of changes since last generation, or "Initial generation"]

Rules

• Never remove a node without confirming it's actually gone from the codebase
• Preserve manual annotations — if a diagram has %% MANUAL: comments, keep them
• Flag uncertainty — if you can't determine a relationship direction, add %% UNCERTAIN: comment
• One component diagram per container — don't combine multiple containers in one C3
• Keep diagrams readable — max ~15 nodes per diagram. Split if larger.
• Use docs/architecture/ relative to project root. Create if missing.
• Include a docs/architecture/README.md index linking all diagrams

Post-commit hook behavior

When triggered automatically after a commit (via hook):

1. Check if the commit touches structural files (new dirs, schema files, route files, package deps, docker/infra)
2. If yes → run refresh mode silently
3. If the refresh produces changes → commit them as docs: update C4 diagrams
4. If no structural changes → skip silently

Reference

See reference/mermaid-c4.md for Mermaid C4 syntax and examples.