AppMap — Architecture as Evidence

Static analysis shows what the code could do. Unit tests show whether expected assertions passed. AppMap shows what the software actually did when it ran — and a coding agent can now query that behavior over MCP, in the editor, attached to the pull request.

This repo is a self-contained walkthrough of that idea. Clone it, run one command, and watch a coding-agent query the AppMap behavioral model over MCP — the same moves the Wells Fargo demo uses, with no Java, Postgres, or cloud required.

Run it (≈2 min)

./smoke/bootstrap.sh

It installs the AppMap CLI locally, indexes a tiny sample recording, and drives appmap query mcp through the demo's actual moves: find_recordings → get_call_tree → find_calls(label="security.authentication"). Expected output is in smoke/EXPECTED-OUTPUT.md. make smoke does the same.

The sample recording is a FINOS Waltz-flavored GET /api/user/whoami — the endpoint at the center of the real JWT auth-forgery finding the demo is built on (see the runbook). You'll see the agent read the executed path, the auth call, and the SQL straight from the runtime model.

What's here

Path	What it is
docs/POSITIONING.md	The story: Architecture as Evidence. The 30 measurements and the 10 to lead with.
docs/DEMO-HANDOFF.md	The CTO runbook: the AppMap MCP, the Waltz sample app, the verified JWT scene, the 12-min script, the screenshot shot-list.
docs/SLIDES.md	The two discussion decks (NFR catalog + demo), with links to the editable Google Docs.
skill/	The NFR rule pack — a skill that turns ~50 architectural rules into runtime pass/fail measurements over the AppMap MCP. Start at skill/SKILL.md.
smoke/	The runnable smoke test: bootstrap.sh, the MCP driver scripts, and the sample AppMap app.

The AppMap MCP surface (verified)

Enumerated live from appmap query mcp → tools/list (CLI v3.199.1) — 13 tools:

Orient            list_endpoints · list_labels · find_recordings
Drill the request get_call_tree · find_requests · find_calls
Data & failures   find_queries · sql_hotspots · find_logs · find_exceptions
Compare           function_hotspots · find_related · compare_branches

Plus an MCP resource appmap://endpoints. There is no generic search tool — the surface is these specific verbs. get_call_tree returns a text tree with #event ids you drill via find_calls(event_id=[…]) for untruncated params and return values. compare_branches is the engine behind the per-PR behavioral delta.

The headline (what the demo proves)

A real, verified vulnerability in Waltz — a hardcoded JWT signing secret (JWTUtilities.SECRET = "secret") — lets anyone forge an admin token. A naive AI fix that externalizes the secret leaves every default-config environment with all authenticated traffic flipped to 403, and the waltz-web test suite stays green — while AppMap's golden traces catch it instantly. Tests said pass; the behavior says every authenticated user lost access. That (BREAKING, GREEN) gap is the whole thesis in one frame: only the runtime evidence saw it.

Connect the MCP to your editor

{ "mcpServers": { "appmap": { "command": "npx",
  "args": ["@appland/appmap", "query", "mcp", "-d", "."] } } }

Point -d at a project that has indexed AppMaps. Reference: https://appmap.io/docs/reference/appmap-mcp.html