CodeMap — Live Architecture Maps

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

Enriched diagram with file:line on every node

2 Three Layers, One Source of Truth

One JSON mapping file — codemap.json — powers everything. Edit it once. All three layers update.

Three-layer architecture: codemap.json feeds Enrich Script, Browser Viewer, and Architecture API

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.

Model

apps/core/models/pending.py:6

Functions (6)

Pending.objects.create @ order_to_invoice.py:332 // invoice creation Pending.objects.create @ proposal_to_order.py:171 // order +on_so Pending.objects.create @ proposal_to_order.py:200 // order -on_p Pending.objects.create @ flow.py:308 // receive_purchase Pending.objects.create @ flow.py:452 // complete_workorder Pending.objects.create @ flow.py:591 // adjust_inventory

Pending Deltas

on_hand: +qty on_so: -qty on_in: +qty

purchase

Purchase order to vendor.

Functions (2)

transfer_order_to_purchase @ order_to_purchase.py:14 transfer_proposal_to_purchase @ proposal_to_purchase.py:13

Pending Deltas

on_po: +qty (GAP: not implemented)

⚠ Code gap detected. The PO line is created but no 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.

Gap detection: missing +on_po pending record surfaces automatically

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 Bucket Flow — enriched with CodeMap

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 Big 4 Transactions — proposals, orders, purchases, invoices

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

Flowcharts

Mapped Nodes

Enriched SVGs

WC3 Documents

API Endpoints

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.