1 Diagrams Drift from Code
Your architecture diagram says "pending records are created when an order
converts to invoice." But it doesn't say where.
Is it flow.py? order_to_invoice.py? Line 332 or 171?
You grep. You find six creation sites across three files. Next month someone refactors and the diagram is wrong again.
CodeMap fixes this. The diagram links directly to
order_to_invoice.py:332. When code moves, update one JSON file
and regenerate. The diagram is always right because it reads the mapping.
Before
After
2 Three Layers, One Source of Truth
One JSON mapping file — codemap.json — powers everything.
Edit it once. All three layers update.
codemap.json is the single source of truth for all three consumers
Layer 1: Enrich
Python script reads .dot + codemap.json.
Adds URL and tooltip attributes to every mapped node.
Graphviz renders clickable SVG — clicking opens VS Code at the right line.
Idempotent. Run anytime.
Layer 2: View
Browser-based viewer with a sidebar listing all flowcharts and their coverage counts. Click any node — a detail panel slides in showing functions, file:line links, pending deltas, GL impact, and schema fields.
Layer 3: API
Three manage actions: get_architecture_node (with fuzzy matching),
get_architecture_map, and list_architecture_flowcharts.
Alice uses these to answer architecture questions by walking the graph.
3 Click a Node, See the Code
Every mapped node shows its full code context. Functions with file:line that open in VS Code. Pending deltas color-coded — green increases, red decreases. Code gaps flagged in yellow so you know what's missing before it becomes a bug.
pending
Central hub for inventory quantity deltas. All quantity changes flow through Pending before updating Item.
purchase
Purchase order to vendor.
Pending.objects.create writes +on_po. Receipt writes -on_po
on arrival, but nothing incremented it. CodeMap surfaced this automatically
— the node has no function link for the +on_po delta.
4 Gaps Surface Automatically
When a diagram shows a flow but the mapping has no code for it, that's a gap. CodeMap flags it. You fix it before customers find it.
The +on_po pending record was never implemented — CodeMap found it by mapping diagram nodes to code
5 Live Example: Inventory Buckets
This is the actual enriched SVG from the WC3 codebase. 14 of 16 nodes mapped to code — 87.5% coverage. Hover any node for tooltips showing file:line and function context.
wc3-inventory-buckets — available = on_hand - on_so + on_po + on_wo
And the Big 4 Transactions — the core transaction lifecycle with line quantity fields and pending inventory flow. 16 of 19 nodes mapped (84%).
wc3-big4-transactions — line quantity flow and pending inventory
6 How to Use
Enrich all flowcharts and render SVGs:
# Reads codemap.json, adds URL/tooltip to .dot files, renders SVG python3 scripts/codemap_enrich.py --all --render
Open the interactive viewer:
# Serves on localhost:8787, opens your browser python3 scripts/codemap_serve.py
Query via API (Alice uses this):
# Get a specific node POST /wcapi/manage/ { "action": "get_architecture_node", "params": { "node": "pending" } } # Fuzzy matching — returns all three journalize functions { "action": "get_architecture_node", "params": { "node": "journal" } } # All mapped nodes in a flowchart { "action": "get_architecture_map", "params": { "flowchart": "wc3-inventory-buckets" } } # Coverage report for all flowcharts { "action": "list_architecture_flowcharts", "params": {} }
Update the mapping and sync:
# 1. Edit the single source of truth readmes/flowcharts/codemap.json # 2. Re-enrich all flowcharts python3 scripts/codemap_enrich.py --all --render # 3. Update WC3 Document records + revision headers python3 scripts/codemap_seed_documents.py --apply
7 Current Coverage
Every flowchart has a Document record in WC3 with
purpose="codemap-guru", tracking revision number, node count,
and coverage percentage. The mapping grows as nodes are added to
codemap.json — coverage increases automatically on
the next enrichment run.