c4

/c4 — Generate C4 Architecture Diagrams

Reads the target project's codebase and produces filled-in Level 1 (System Context) and Level 2 (Container) diagrams as Mermaid markdown. Saves the slog of filling in the templates by hand for a repo you already understand structurally.

This skill complements /handover (which seeds a stub L2 once at onboarding). Use /c4 whenever the architecture changes substantially and the diagrams need a refresh — or for a project that wasn't onboarded via /handover.

For projects that hit Mermaid's ceiling — L3 (component) precision, auto-zoom across levels, tags/perspectives — pass --dsl to emit a Structurizr DSL workspace instead. See "Escape hatch: Structurizr DSL (L3+)" below.

Path resolution

Read the registry path via portfolio_registry, the per-project docs dir via portfolio_projects_dir, and the ideas backlog via portfolio_ideas_backlog — all from .claude/hooks/_lib-portfolio-paths.sh. Source the helper at the top of any bash block that touches those paths:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
registry=$(portfolio_registry)

Defaults match today's single-fork layout (./apexyard.projects.yaml, ./projects, ./projects/ideas-backlog.md). Adopters in split-portfolio mode override the portfolio.{registry, projects_dir, ideas_backlog} keys in .claude/project-config.json. Don't hardcode literal apexyard.projects.yaml or projects/ paths in bash blocks — the helper resolves whichever mode the adopter is in. See docs/multi-project.md.

Usage

/c4                                    # current cwd, both levels
/c4 curios-dog                         # registered project, both levels
/c4 curios-dog --level=1               # only the L1 system-context diagram
/c4 . --level=2                        # only the L2 container diagram for cwd
/c4 curios-dog --force                 # overwrite existing diagrams
/c4 curios-dog --dsl                   # Structurizr DSL escape hatch (L3+), instead of Mermaid
/c4 curios-dog --dsl --force           # overwrite an existing workspace.dsl

Output location

Where the files land depends on where the skill is invoked from and what argument is passed:

The split mirrors the existing convention from docs/multi-project.md § "Architecture diagrams".

Process

1. Resolve the target

• If <project-name> is . → use cwd.
• If <project-name> is given and the registry has it → use workspace/<name>/ if it exists, otherwise fall back to ops-view-only mode (no codebase to scan; ask the user to clone or to provide a path).
• If no arg → use cwd; if cwd is the ops fork root, ask whether the diagram is framework-wide or for a registered project.

If the cwd / target doesn't have any of the detection signals listed below (no package.json, no Dockerfile, no template.yaml, etc.), stop and tell the user — there's nothing to scan.

2. Detect

Run these in parallel; collect findings into a structured proposal.

2a. Containers (L2)

A "container" in C4 is a deployable / runnable unit — a frontend, an API, a database, a queue, a worker, a CDN. Not a Docker container (confusing but standard).

Detection sources:

Hard cap: 9 containers max. If detection yields more, collapse the most-similar pair into a single container with a combined label, and surface the collapse to the user during step 3.

2b. External actors and systems (L1)

External actors fall into three buckets — Person (humans), System_Ext (third-party SaaS / APIs), and the System (the box being modelled).

Detection sources:

If a signal could match multiple personas (e.g., the API serves both end users and admins), surface both; the user can collapse during confirm.

Detection should also pull the project's one-sentence description from:

• The README's first non-heading paragraph
• The description field in package.json
• An existing projects/<name>/README.md if the registry has the project

If none of those exist, ask the user for one sentence in step 3.

3. Confirm with the user

Show the detected proposal in a compact table:

For <project>:

External actors (L1):
  [Person] End user — uses the public profile pages
  [Person] Admin — manages reports and users
  [Ext] AWS Cognito — authentication
  [Ext] Amazon Bedrock — text embeddings for similarity
  [Ext] PostHog EU — product analytics
  [Ext] DiceBear — avatar generation

Containers (L2, inside the system boundary):
  Web App         Next.js 16        — public profile pages, sign-in, dashboard
  Backend API     AWS Lambda + SAM  — Q&A endpoints, profiles, likes, search
  Admin App       Next.js + Cognito — moderation console
  DynamoDB        single-table      — questions, answers, profiles, likes
  S3 (uploads)    public-read       — avatar + answer-attachment storage
  CloudFront      asset CDN         — public-asset distribution

One-sentence description:
  "Public Q&A platform — anonymous askers, public answers, share-driven growth."

Edit? (a) accept · (e) edit list · (d) edit description · (q) quit
>

On e: open an interactive add/remove flow — one item per prompt, accept by Enter, or type add: <new item> / remove: <name>. On d: prompt for a one-sentence replacement description. On q: exit without writing. On a: proceed to step 4 (or step 4b if --dsl was passed).

4. Generate the Mermaid (skip if --dsl was passed — go to step 4b)

Resolve the C4 templates via the portfolio helper so adopter overrides win when present:

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-read-config.sh"
source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-portfolio-paths.sh"
context_template=$(portfolio_resolve_template architecture/c4-context.md)     # L1 skeleton
container_template=$(portfolio_resolve_template architecture/c4-container.md) # L2 skeleton

Single-fork adopters (no portfolio block) and adopters with no override fall straight through to templates/architecture/c4-{context,container}.md. Adopters who want a customised C4 shape drop their versions at <private_repo>/custom-templates/architecture/c4-{context,container}.md. See templates/README.md for the path-mirroring convention.

Keep the surrounding markdown sections from the resolved templates ("How to use this template" can be trimmed in the generated file since these are real diagrams, not templates).

For L1:

C4Context
    title System Context for {Project Name}

    Person(<id>, "<Display>", "<Description>")
    ...
    System(main, "{Project Name}", "<one-sentence description>")
    System_Ext(<id>, "<Name>", "<Tech / role>")
    ...
    Rel(<from>, <to>, "<Verb>", "<Protocol>")
    ...

For L2:

C4Container
    title Container Diagram for {Project Name}

    Pe

---

*Content truncated.*