ADI Flow Nav
VS Code extension that turns AdInsure document status models into an interactive graph: states as nodes, transitions as colored edges. Read-only — it never edits documentFlow.json.
Install from Extensions (ADI Flow Nav) or build from this repo and load the VSIX.
Open a flow
You need a workspace with AdInsure document/* folders (both configuration.json and documentFlow.json).
Any of these works:
- Command Palette → ADI Flow Nav: Open
- Right-click a document folder → Open in ADI Flow Nav
- Right-click
documentFlow.json or configuration.json → Open in ADI Flow Nav
- Status bar → ADI Flow (opens last document or picker)
The panel remembers recent and pinned documents per workspace.
Working with the graph
| Control |
What it does |
| Document dropdown |
Switch between pinned / recent / all scanned documents |
| Pin / Clear recent |
Manage your document list |
| Actor |
Filter transitions by who can run them (configuration.json) |
| Search |
Find states and transitions; Esc clears |
| Auto / Studio |
Auto = ELK layout; Studio = coordinates from documentFlow.ui.json (if the file exists) |
| Labels |
Show transition names on edges (busy on large flows — toggle off for overview) |
| Diff |
Compare current documentFlow.json to git base (adiFlowNav.diffBase, default origin/master) |
| Fit / Export / Refresh |
Fit view, PNG/SVG export, reload graph and reset saved node positions |
Kind filters (second row)
Colored chips: Main, Errors, Returns, Discard, Self.
Practical default: keep Main + Errors on. That matches how most people read a lifecycle.
Turn on Returns or Discard when you are debugging a specific path — not for the first look. On heavy flows (e.g. MotorCascoLeasing, 47 transitions) all kinds at once will look messy on any layout engine; that is expected.
Canvas
- Click a state or transition → details in the right panel (Inspect tab)
- Drag nodes → position is saved per document in workspace state
- Drag a transition handle (blue dot on edge) → adjust route; saved as edge shift
- Click empty canvas → clear selection
- Path Finder (right panel) → shortest path between two states over currently visible kinds
Right panel tabs
| Tab |
Purpose |
| Doc |
Package, process, layout mode, links to JSON files |
| Inspect |
Selected state/transition, neighbors, open flowRule / ClientAction |
| Issues |
Consistency checks (orphan states, etc.) |
| Diff |
Changes vs git base |
Copy as Markdown buttons help when writing tickets or MR descriptions.
Export
PNG / SVG include kind legend, layout mode label, and extension version. Good for Confluence, chat, or QA without Studio access.
Layout: Auto (ELK) vs Studio
| Mode |
When to use |
| Auto (ELK) |
Default. Layered layout via ELK. Works without ui.json. Best for large cyclic flows (claims, policies). |
| Studio |
Only if documentFlow.ui.json exists next to the flow. Uses designer coordinates (scaled to our node size). |
After changing layout mode, use Refresh if positions look stale.
Development
Requirements
- Node.js 20+
- VS Code 1.85+
Setup
npm install
npm run build
Press F5 to launch Extension Development Host, open an AdInsure workspace, then ADI Flow Nav: Open.
For iterative work:
npm run watch # rebuild extension + webview on save
Also run Tailwind when you change globals.css:
npm run build:tailwind
(npm run build already runs Tailwind.)
Scripts
| Command |
Purpose |
npm run build |
Production build (Tailwind + esbuild) |
npm run watch |
Dev watch |
npm run smoke |
Fixture parse / NFR smoke test (no AdInsure checkout required) |
npm run lint |
ESLint + FSD import boundaries |
npm run package |
Produce .vsix |
Optional: point smoke at a real document folder:
ADI_FLOW_SMOKE_DOC=/path/to/document/MyPolicy npm run smoke
Project layout (FSD-lite)
src/
extension/ VS Code host: panel, commands, message bridge
shared/
domain/ Parser, layout (ELK), diff, search, models
ui/ Tailwind UI primitives (Button, Select, Tabs, …)
config/ Flow colors / kind labels
webview/
app/ React bootstrap + global styles
pages/flow/ FlowPage composition
widgets/ Toolbar, canvas, detail panel, legend, filters
features/ Hooks: extension-bridge, graph-build, search, panel-resize
entities/ StateNode, AdjustableEdge, shared selection types
export/ PNG / SVG
Import rules are enforced with eslint-plugin-boundaries (see eslint.config.js): e.g. features must not import sibling features, widgets may import features, etc.
Build output
dist/extension.js — extension host (~1.4 MB with bundled ELK)media/webview/main.js + main.css — webview bundle
Generated CSS: src/webview/app/styles/built.css (gitignored; produced by Tailwind CLI).
Configuration
| Setting |
Default |
Meaning |
adiFlowNav.diffBase |
origin/master |
Git ref for Diff mode |
License
MIT — see repository.
