Transform a knowledge graph into Mermaid diagrams for architecture visualization, dependency mapping, and data flow analysis.
Transform .understand/knowledge-graph.json into Mermaid diagrams that render natively in GitHub, GitLab, Obsidian, and most markdown viewers. Produces architecture overviews, dependency graphs, data flow maps, and file organization trees.
codebase-understanding (knowledge graph exists)repo-augmentation pipeline (Stage 1.75, alongside docs-generation).understand/knowledge-graph.json must exist. Run codebase-understanding first if it doesn't.docs/
└── diagrams/
├── README.md # Index of all diagrams with descriptions
├── architecture.md # Layer overview diagram
├── dependencies.md # Module dependency graph
├── data-flow.md # How data flows through the system
└── file-map.md # File organization treemap
Step 1: READ knowledge graph
|
Step 2: GENERATE docs/diagrams/architecture.md
|
Step 3: GENERATE docs/diagrams/dependencies.md
|
Step 4: GENERATE docs/diagrams/data-flow.md
|
Step 5: GENERATE docs/diagrams/file-map.md
|
Step 6: GENERATE docs/diagrams/README.md (index)
Load .understand/knowledge-graph.json and extract:
layers[] → for architecture diagram
nodes[] → for all diagrams (files, classes, functions)
edges[] → for dependency and data-flow diagrams
tour[] → for highlighting entry points
metadata → for labels and titles
docs/diagrams/architecture.mdA top-down view of architectural layers and their relationships.
# Architecture Overview
> Auto-generated from knowledge graph. Commit: `<hash>`
## Layer Diagram
```mermaid
flowchart TD
subgraph <Layer1>[" <Layer1 Name> — <description snippet> "]
L1F1["<top file 1>"]
L1F2["<top file 2>"]
L1F3["<top file 3>"]
end
subgraph <Layer2>[" <Layer2 Name> — <description snippet> "]
L2F1["<top file 1>"]
L2F2["<top file 2>"]
end
<Layer1> --> <Layer2>
<Layer2> --> <Layer3>
`` `
## Layer Details
| Layer | Files | Description |
|-------|-------|-------------|
| <name> | <count> | <description> |
Construction rules:
subgraph per layer from layers[]imports/calls/depends_on edges--> for direct dependencies, -.-> for weak/optional dependencies...and N more nodedocs/diagrams/dependencies.mdA graph showing how modules/files depend on each other.
# Dependency Graph
> Shows import and dependency relationships between key files.
## Full Dependency Graph
```mermaid
graph LR
A["src/index.ts"] --> B["src/routes/api.ts"]
A --> C["src/config/db.ts"]
B --> D["src/services/userService.ts"]
B --> E["src/services/postService.ts"]
D --> F["src/models/User.ts"]
E --> F
E --> G["src/models/Post.ts"]
style A fill:#f9f,stroke:#333
style F fill:#bbf,stroke:#333
`` `
Construction rules:
imports, calls, depends_on, and routes_to edge typesgraph LR (left-to-right) for dependency flowPer-layer variant (for large codebases):
If total nodes > 40, generate additional focused diagrams:
## <Layer Name> Dependencies
```mermaid
graph LR
%% Only nodes in <Layer> and their direct dependencies
...
`` `
docs/diagrams/data-flow.mdShows how data moves through the system.
# Data Flow
> How data enters, transforms, and exits the system.
## Request Flow
```mermaid
flowchart LR
Client([Client]) --> Entry["Entry Point<br/><entry file>"]
Entry --> Router["Router<br/><router file>"]
Router --> Service["Service Layer<br/><service file>"]
Service --> Data["Data Layer<br/><model/db file>"]
Data --> DB[(Database)]
Service --> External["External API<br/><integration file>"]
`` `
Construction rules:
flowchart LR for left-to-right data flowimports → calls → reads_from/writes_to edge chains([...]) for external actors (Client, User)[(...)] for databases["..."] for internal components{{"..."}} for decision points:::className for styling if neededEvent-driven variant:
If subscribes/publishes edges are present:
## Event Flow
```mermaid
flowchart TD
Publisher["<publisher file>"] -->|publishes| EventBus{{Event Bus}}
EventBus -->|subscribes| HandlerA["<handler A>"]
EventBus -->|subscribes| HandlerB["<handler B>"]
`` `
docs/diagrams/file-map.mdA treemap/hierarchy showing file organization.
# File Organization
> Directory structure with architectural layer annotations.
## File Tree
```mermaid
flowchart TD
Root["<project-name>/"]
Root --> Src["src/"]
Root --> Config["config/"]
Root --> Tests["tests/"]
Src --> SrcAPI["api/ <br/> 🔵 API Layer"]
Src --> SrcSvc["services/ <br/> 🟢 Service Layer"]
Src --> SrcData["models/ <br/> 🟡 Data Layer"]
SrcAPI --> API1["routes.ts"]
SrcAPI --> API2["middleware.ts"]
SrcSvc --> Svc1["userService.ts"]
SrcSvc --> Svc2["postService.ts"]
SrcData --> Data1["User.ts"]
SrcData --> Data2["Post.ts"]
`` `
Construction rules:
flowchart TD (top-down) for tree hierarchy"controllers/ (15 files)"docs/diagrams/README.mdIndex page linking all diagrams:
# Diagrams
> Visual representations of the **<project name>** codebase.
> Generated from knowledge graph at commit `<hash>`.
## Available Diagrams
| Diagram | Description | Best For |
|---------|-------------|----------|
| [Architecture Overview](architecture.md) | Layer diagram showing system structure | Understanding the big picture |
| [Dependency Graph](dependencies.md) | Import/call relationships between files | Finding coupling and dependencies |
| [Data Flow](data-flow.md) | How data moves through the system | Understanding request/event lifecycle |
| [File Map](file-map.md) | Directory structure with layer annotations | Navigating the codebase |
## How to View
These diagrams use [Mermaid](https://mermaid.js.org/) syntax which renders natively in:
- GitHub / GitLab markdown preview
- Obsidian
- VS Code (with Mermaid extension)
- Notion (paste as code block, select Mermaid)
For other viewers, paste the mermaid code blocks into [mermaid.live](https://mermaid.live/).
Follow these rules to keep diagrams renderable and readable:
src/services/userService.ts → userService.ts (show full path in a table below the diagram).["..."] to avoid Mermaid parsing errors.src/api/routes.ts → src_api_routes_ts.graph LR for dependency/flow diagrams (left-to-right reads naturally).flowchart TD for hierarchies and architecture (top-down).style directives sparingly — only for entry points and high-complexity nodes.Generate deterministic IDs from file paths:
File path: src/api/routes.ts
Node ID: src_api_routes_ts
Label: ["routes.ts"]
This ensures:
Same strategy as docs-generation:
docs/diagrams/ existsdocs/diagrams/README.md with current knowledge graphBefore finalizing:
docs/diagrams/docs-generation skillRun alongside docs-generation. The docs can link to diagrams, and diagrams link back to docs:
docs/architecture.md can embed or link to docs/diagrams/architecture.mddocs/modules/<layer>.md can link to the relevant subgraph in the dependency diagramcodebase-understanding skillThis skill REQUIRES the knowledge graph as input. Always run codebase-understanding first.
repo-augmentation skillSlots in as Stage 1.75 alongside docs-generation. The updated pipeline: