c4-architecture
Generate C4 model architecture diagrams (System Context -> Container -> Component -> Code) as Mermaid, derived from codebase analysis with our own tools (read, astGrep, grep) — no external packages or cloud. Ports the C4 idea from deepwiki-rs / Litho but implemented originally on our stack. Validates every diagram with the mermaid-fixer skill and stores results via context-mode_ctx_index. Trigger: "generate C4", "C4 diagram", "system context diagram", "container diagram", "document architecture with C4", "adapt deepwiki c4", when onboarding to a codebase or writing architecture docs.
- License 许可
- MIT
- 最近更新
- 2026-08-26
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- c4-architecture
- license
- MIT
- metadata
- { "author": "adapted-from-deepwiki-rs", "version": "1.0" }
- description
- Generate C4 model architecture diagrams (System Context -> Container -> Component -> Code) as Mermaid, derived from codebase analysis with our own tools (read, astGrep, grep) — no external packages or cloud. Ports the C4 idea from deepwiki-rs / Litho but implemented originally on our stack. Validates every diagram with the mermaid-fixer skill and stores results via context-mode_ctx_index. Trigger: "generate C4", "C4 diagram", "system context diagram", "container diagram", "document architecture with C4", "adapt deepwiki c4", when onboarding to a codebase or writing architecture docs.
02 资源文件 1
- 资产文件assets/c4-templates.md3.0 KB
03 SKILL.md 正文
C4 Architecture (original, local-first)
Produce a C4 model of any codebase in four levels of detail. The diagrams are
generated by analyzing the repo ourselves (README, entry points, dependency
manifests, astGrep for module boundaries) and emitted as Mermaid — never by
installing a third-party tool. Every diagram is validated with mermaid-fixer
and indexed with context-mode for later retrieval.
The four levels
| Level | Diagram | Answers | Mermaid type |
|---|---|---|---|
| 1 | System Context | Who/what interacts with the system at the boundary? | C4Context |
| 2 | Container | What deployable units (apps, services, DBs, queues) make it up? | C4Container |
| 3 | Component | What modules/components live inside the main container? | C4Component |
| 4 | Code | Key classes/interfaces of the most important component? | classDiagram* |
* Mermaid has no C4Code primitive; level 4 uses a classDiagram
(relationships = associations/dependencies).
How to derive each level from the code (our tools only)
Level 1 — System Context
- Read
README.md, top-level dirs, and config for external signals: CORS origins, OAuth providers,API_URLenv vars, webhook endpoints. - Each external actor (user role, other system) becomes a
Person/System_Ext. - The system under study is one
System/System_Boundary.
Level 2 — Container
- Scan dependency manifests & infra for deployable units:
package.json/Cargo.toml/pom.xml/requirements.txt→ language/runtimeDockerfile,docker-compose.yml,Procfile→ services- DB drivers, Redis, message brokers in deps →
ContainerDb/ContainerQueue
- Each unit = a
Containerinside aSystem_BoundaryorContainer_Boundary.
Level 3 — Component
- For the main container,
astGrep/read to find module boundaries:src/**/, exported modules, route handlers,controller/service/repositorydirs. - Each cohesive module = a
Componentinside aContainer_Boundary.
Level 4 — Code
- Pick the single most important component from level 3.
astGrepfor class/interface/struct/type definitions and their relationships.- Emit a
classDiagram(do not try to diagram the whole codebase — one component only).
Mermaid C4 syntax
See assets/c4-templates.md for copy-paste scaffolds of all four levels.
Minimal examples:
C4Context
title System Context — <system>
Person(user, "User", "Primary operator")
System(sys, "<system>", "What it does")
System_Ext(ext, "External API", "Upstream dependency")
Rel(user, sys, "Uses")
Rel(sys, ext, "Calls", "HTTPS")
C4Container
title Container — <system>
Person(user, "User")
Container_Boundary(b, "<system>") {
Container(web, "Web App", "TypeScript/Next", "UI + API gateway")
ContainerDb(db, "Database", "Postgres", "Persistence")
}
Rel(user, web, "Uses", "HTTPS")
Rel(web, db, "Reads/Writes", "SQL")
Workflow (the gate)
- Analyze the repo per the level-1..4 signals above. Do NOT dump the whole
tree into context — use
context-architecturescaling (README + entry + targetedastGrep). - Generate one
.mmdper level under.c4/:.c4/context.mmd,.c4/container.mmd,.c4/component.mmd,.c4/code.mmd. - Validate — run the
mermaid-fixerskill's validator:
Fix every reported error and re-run until exit codenode <mermaid-fixer-skill-dir>/assets/validate-mermaid.mjs .c4/*.mmd0. - Index for retrieval (feeds
context-architectureS1 tier):
Tag all four withcontext-mode_ctx_index(path: ".c4/context.mmd", source: "architecture")source: "architecture"soctx_search(queries:[...], source:"architecture")surfaces them to agents. - Wrap (optional): write
.c4/README.mdlinking the four levels, then pointcavekit-docgen'sarchitecture.mdat it.
Integration
| Skill | Relationship |
|---|---|
mermaid-fixer |
Mandatory validation gate (step 3). |
context-architecture |
C4 diagrams populate the S1 (ARCHITECTURE) tier. |
cavekit-docgen |
architecture.md references the generated C4 set. |
doc-knowledge-base |
For externally-sourced architecture docs, tag source:"architecture". |
Principles
- Local-first: no
npm install, no cloud. Pure analysis + Mermaid. - Progressive disclosure: level 1 is always safe to show; deeper levels only when the reader needs them.
- Valid or not shipped: a diagram that fails
mermaid-fixeris a broken diagram — never commit it.
04 同仓库更多 Skills
zustand-5
Zustand 5 state management patterns. Trigger: When managing React state with Zustand.
zod-4
Zod 4 schema validation patterns. Trigger: When using Zod for validation - breaking changes from v3.
x-bookmark-quote-posts
Workflow para revisar bookmarks de X/Twitter y convertirlos en drafts de quote posts. Accede a la sección de bookmarks vía browser headless, extrae posts recientes, y genera drafts con voz personal del usuario. No publica ni muta X — solo genera contenido para revisión. Trigger: X bookmarks, Twitter bookmarks, quote posts, bookmark automation, crear quote posts, revisar bookmarks, growth content X.
writing-skills
Use when creating new skills, editing existing skills, or verifying skills work before deployment
writing-plans
Use when you have a spec or requirements for a multi-step task, before touching code
work-unit-commits
Plan commits as reviewable work units. Trigger: implementation, commit splitting, chained PRs, or keeping tests and docs with code.