See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.
JavaScript ai-codingarchitecture-diagramclaudeclaude-codeclaude-code-plugincodebase-visualizationcodexcodex-plugindeveloper-toolsonboardingopenaivibe-coding
Floorplan 0.1.1: screenshots, more connections, fewer false alarms
Hayden Smithdd29998e90f9
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 6ef8ae8..1c509e7 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,6 +1,6 @@{"name": "floorplan",- "version": "0.1.0",+ "version": "0.1.1","description": "See how your app actually fits together: an interactive map of your codebase where every part, file and web request has a plain-English name and description, with a health check, screens, guided flows, questions answered on the map, and highlights of what was just worked on.","author": {"name": "Hayden Smith",diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 423e1e9..0f7309a 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -1,5 +1,15 @@# Changelog+## 0.1.1 (2026-10-27)++- **More connections found:** requests made through small helpers imported from an API client, like `post("/orders", …)` in a Python job, are now matched to the endpoints they reach.+- **Fewer false Health alarms:**+ - Express routers protected where they're mounted (`app.use('/admin', requireStaff, adminRouter)`), including routers nested inside them, are no longer reported as open to anyone.+ - Newsletter, contact and waitlist sign-ups are treated as public on purpose.+- **Flows:** the page heading fades out while a flow plays, so the flow bar no longer overlaps it.+- **Screens:** a screen's board is labelled "Screen" instead of "Answer".+- **README:** screenshots, from a demo app mapped end to end.+## 0.1.0 (2026-10-27)First release.diff --git a/README.md b/README.mdindex b52a8f5..8447675 100644--- a/README.md+++ b/README.md@@ -12,12 +12,12 @@Claude reads your codebase and draws an interactive map of it. Every part, file and web request gets a plain-English name, and every connection between them is shown.[](https://code.claude.com/docs/en/overview)-[](CHANGELOG.md)+[](CHANGELOG.md)[](LICENSE)[](https://nodejs.org)[](#how-it-works)-[Install](#install) · [Quick start](#quick-start) · [Features](#features) · [How it works](#how-it-works) · [Docs](docs/README.md) · [FAQ](#faq)+[Install](#install) · [Quick start](#quick-start) · [Features](#features) · [See it in action](#see-it-in-action) · [How it works](#how-it-works) · [Docs](docs/README.md) · [FAQ](#faq)</div>@@ -27,10 +27,10 @@ Claude reads your codebase and draws an interactive map of it. Every part, filelink. Put that link on its own line here (replacing this comment) and it plays inline.-->-<!--- SCREENSHOT: save it as docs/images/overview.png, then replace this comment with:- <p align="center"><img src="docs/images/overview.png" alt="A Floorplan map of a web app" width="100%"></p>--->+<p align="center">+ <img src="docs/images/overview.png" alt="A Floorplan map of Brewline, a coffee subscription app: the online shop, staff app, main server and background jobs, connected to Stripe, Shippo, SendGrid, the database and team chat, with recent work highlighted in green" width="100%">+</p>+<p align="center"><sub>Brewline, a demo coffee-subscription app built across four repos, mapped by Floorplan in one run.</sub></p>## Why Floorplan?@@ -105,6 +105,41 @@ Updates re-read only what changed, and an open map reloads itself. Everything ruPlus guided **flows** you can request in plain words, a one-minute **Start here** tour, search, keyboard shortcuts, and right-click actions on every card.+## See it in action++<table>+<tr>+<td width="50%" valign="top">+<img src="docs/images/ask.png" alt="An answer board: the gift subscription traced from the gift page to the friend's inbox, with numbered cards and a written walkthrough">+<p><b>Ask the map.</b> A real answer, from the Claude Code CLI in 31 seconds. It traced the gift from form to inbox across two repos, and spotted two bugs along the way.</p>+</td>+<td width="50%" valign="top">+<img src="docs/images/screens.png" alt="Everything behind the Gift page: its form, the requests it makes, the server code, the database, Stripe and SendGrid">+<p><b>Start from a screen.</b> Pick any page and see everything behind it, from the button down to the database and outside services.</p>+</td>+</tr>+<tr>+<td valign="top">+<img src="docs/images/recent.png" alt="The Recent work board for a gift subscriptions feature: what was asked, what was done, and a note on every changed card">+<p><b>Recent work.</b> What you asked for, what changed, and why each change was needed, on one board.</p>+</td>+<td valign="top">+<img src="docs/images/health.png" alt="The Health panel listing a secret key written into the code and an endpoint anyone can use, each with Show on map and Fix with Claude">+<p><b>Health check.</b> A password left in the code and an endpoint anyone can call, each with a one-click fix prompt.</p>+</td>+</tr>+<tr>+<td valign="top">+<img src="docs/images/inside.png" alt="Inside the Business rules part of the server: its files in the middle, what uses them on the left, and outside services on the right">+<p><b>Zoom in.</b> Inside any part: what's in it, what uses it, and what it relies on. Green tags mark what just changed.</p>+</td>+<td valign="top">+<img src="docs/images/flow.png" alt="A guided flow, step 4 of 6, showing the main server emailing the gift code through SendGrid">+<p><b>Guided flows.</b> Watch a request travel through the app step by step, or ask Claude to trace a new one.</p>+</td>+</tr>+</table>+## InstallYou need [Claude Code](https://code.claude.com/docs/en/overview) (the desktop app's Code tab or the CLI) and [Node.js 18+](https://nodejs.org).diff --git a/docs/images/ask.png b/docs/images/ask.pngnew file mode 100644index 0000000..38fca21Binary files /dev/null and b/docs/images/ask.png differdiff --git a/docs/images/flow.png b/docs/images/flow.pngnew file mode 100644index 0000000..3875b92Binary files /dev/null and b/docs/images/flow.png differdiff --git a/docs/images/health.png b/docs/images/health.pngnew file mode 100644index 0000000..6aa9fc3Binary files /dev/null and b/docs/images/health.png differdiff --git a/docs/images/inside.png b/docs/images/inside.pngnew file mode 100644index 0000000..c9ff84aBinary files /dev/null and b/docs/images/inside.png differdiff --git a/docs/images/overview.png b/docs/images/overview.pngnew file mode 100644index 0000000..9309176Binary files /dev/null and b/docs/images/overview.png differdiff --git a/docs/images/recent.png b/docs/images/recent.pngnew file mode 100644index 0000000..6fb652aBinary files /dev/null and b/docs/images/recent.png differdiff --git a/docs/images/screens.png b/docs/images/screens.pngnew file mode 100644index 0000000..dec5bcbBinary files /dev/null and b/docs/images/screens.png differdiff --git a/docs/using-the-map.md b/docs/using-the-map.mdindex e79e525..7947ee6 100644--- a/docs/using-the-map.md+++ b/docs/using-the-map.md@@ -31,6 +31,8 @@ The details on cards simplify as you zoom out: descriptions drop away and titlesDouble-click an outside card to jump there.+<img src="images/inside.png" alt="Inside a part of the server: what uses it on the left, its files in the middle, outside services on the right">+Hover over a card for a moment to see what kind of thing it is, where it lives, and how big it is. Hover over a line to see what it carries, for example which endpoints a screen calls.## The side panel@@ -71,6 +73,8 @@ Guided walkthroughs of the app's main jobs, like "Checkout" or "Sign up". A flow## Asking questions+<img src="images/ask.png" alt="An answer board with numbered cards and a written walkthrough">+Type into the Ask bar at the bottom and press **Enter**. Claude answers in a few sentences and shows an **answer board**: just the cards involved, how they connect, a short note on each, and a numbered walkthrough when the answer is a sequence. Follow-up suggestions appear under the answer. **Back to map** returns to where you were.- **Right-click → Ask about this** on any card or line adds it to your question as context.diff --git a/skills/floorplan/assets/ui/30-screens.js b/skills/floorplan/assets/ui/30-screens.jsindex e9f47e5..bdd1d0f 100644--- a/skills/floorplan/assets/ui/30-screens.js+++ b/skills/floorplan/assets/ui/30-screens.js@@ -46,7 +46,7 @@// a short walkthrough: the screen → its first request → the server code → where it ends upconst firstOf = (kind) => items.find((b) => b.kind === kind);const steps = [firstOf('screen'), firstOf('request'), firstOf('server'), firstOf('data') || firstOf('outside')].filter(Boolean);- SC.showBoard({ title: s.name, question: 'Everything behind ' + s.url, items, steps: steps.length >= 3 ? steps : [] });+ SC.showBoard({ kind: 'Screen', icon: 'ui', title: s.name, question: 'Everything behind ' + s.url, items, steps: steps.length >= 3 ? steps : [] });}// ---------- header menu ----------diff --git a/skills/floorplan/assets/viewer.html b/skills/floorplan/assets/viewer.htmlindex c24a8bf..d9a090b 100644--- a/skills/floorplan/assets/viewer.html+++ b/skills/floorplan/assets/viewer.html@@ -76,7 +76,9 @@ header > * { pointer-events: auto; }#svg.panning { cursor: grabbing; }#viewport { transform-origin: 0 0; }#viewport.anim { transition: transform .5s var(--ease), opacity .35s var(--ease); }-#context { position: absolute; left: 24px; top: 72px; max-width: min(520px, calc(100% - var(--pw) - 64px)); pointer-events: none; }+#context { position: absolute; left: 24px; top: 72px; max-width: min(520px, calc(100% - var(--pw) - 64px)); pointer-events: none; transition: opacity .3s var(--ease); }+/* the flow bar takes the heading's place while a flow plays */+body.in-flow #context { opacity: 0; }#context .k { display: inline-flex; align-items: center; gap: 8px; font-size: 12.5px; color: var(--text-3); }#context .k .ico { width: 20px; height: 20px; border-radius: 7px; }#context::before { content: ""; position: absolute; inset: -28px -60px -28px -40px; background: radial-gradient(closest-side, rgba(15, 15, 15, .9), rgba(15, 15, 15, 0)); z-index: -1; }@@ -1592,13 +1594,14 @@ $('#filters-btn').onclick = (ev) => { ev.stopPropagation(); fm.classList.remove(legendEl.addEventListener('click', (ev) => ev.stopPropagation());window.addEventListener('click', () => { fm.classList.remove('open'); legendEl.classList.remove('open'); });function startFlow(id) { const f = G.flows.find((x) => x.id === id); if (!f) return; state.flow = { f, i: 0 }; flowStep(); }-function stopFlow() { state.flow = null; $('#flowbar').hidden = true; vp.querySelectorAll('.flowfx').forEach((x) => x.remove()); select(null); }+function stopFlow() { state.flow = null; document.body.classList.remove('in-flow'); $('#flowbar').hidden = true; vp.querySelectorAll('.flowfx').forEach((x) => x.remove()); select(null); }function lcaContainer(a, b) {const cb = new Set(chain(b));for (const x of chain(a)) if (cb.has(x)) return (x === a || x === b) ? (parentOf.get(x) || 'root') : x;return 'root';}function flowStep() {+ document.body.classList.add('in-flow'); // answer walkthroughs and the tour play flows tooconst { f, i } = state.flow;const a = f.steps[i].ref, b = f.steps[i + 1]?.ref;const container = b ? lcaContainer(a, b) : parentOf.get(a) || 'root';diff --git a/skills/floorplan/scripts/lib/extract.mjs b/skills/floorplan/scripts/lib/extract.mjsindex cee1ae9..5da7e61 100644--- a/skills/floorplan/scripts/lib/extract.mjs+++ b/skills/floorplan/scripts/lib/extract.mjs@@ -22,7 +22,7 @@ const all = (re, s) => [...s.matchAll(re)];// ---------- HTTP call literals -----------const HTTP_CONTEXT = /\b(fetch|axios|ky|got|request|requests|httpx|aiohttp|session|client|http|https|api|Api|API|endpoint|Endpoint|url|Url|URL|BASE|base)\b|\.(get|post|put|patch|delete|head)\s*(<[^>]*>)?\s*\(/;+const HTTP_CONTEXT = /\b(fetch|axios|ky|got|request|requests|httpx|aiohttp|session|client|http|https|api|Api|API|endpoint|Endpoint|url|Url|URL|BASE|base)\b|\.(get|post|put|patch|delete|head)\s*(<[^>]*>)?\s*\(|(?<![.\w$])(get|post|put|patch|delete)\s*\(\s*[rf]?["'`]\//;const NAV_CONTEXT = /\b(router\.(push|replace|prefetch)|navigate|redirect|href|revalidatePath|pathname|Link|to=|location\.)\b|window\.location/;const STR_LITERAL = /(["'`])((?:\\.|(?!\1)[^\\\n])*)\1/g;const IGNORED_HOST = /^(localhost|127\.0\.0\.1|0\.0\.0\.0)(:\d+)?$|\.(test|example|invalid|local|localhost|internal)(:\d+)?$|(^|\.)example\.(com|org|net)$/;@@ -65,7 +65,8 @@ export function flattenTemplates(line) {return out;}-const METHOD_CALL = /\.(get|post|put|patch|delete)\s*(?:<[^>]*>)?\s*\(/i;+// `api.post(…)`, or a bare helper imported from an API client: `post("/orders", …)`+const METHOD_CALL = /(?:\.|(?<![\w$])(?=(?:get|post|put|patch|delete)\s*\(\s*[rf]?["'`]\/))(get|post|put|patch|delete)\s*(?:<[^>]*>)?\s*\(/i;const METHOD_OPT = /method\s*[:=]\s*["'`](\w+)/i;// `const url = …`, `url = f"…"`, `this.endpoint = …`: a URL kept in a variable for the call belowconst ASSIGN = /(?:\b(?:const|let|var)\s+|^\s*(?:self\.|this\.)?)([A-Za-z_$][\w$]*)\s*(?::\s*[\w<>[\]|. ]+?\s*)?=(?![=>])/;@@ -179,9 +180,10 @@ function extractJs(src, filePath) {}for (const m of all(/\b([A-Za-z_$][\w$]*)\.(use|route)\(\s*["'`](\/[^"'`]*)["'`]\s*,([^\n;]*)/g, code)) {const req = /require\(\s*["']([^"']+)["']\s*\)/.exec(m[4]);- if (req) { mounts.push({ prefix: m[3], spec: req[1], line: at(m.index) }); continue; }+ const mw = (m[4].split(',').map((s) => s.trim()).filter((s) => /^[A-Za-z_$][w$.]*$/.test(s))).map((s) => s.split('.').pop());+ if (req) { mounts.push({ prefix: m[3], spec: req[1], line: at(m.index), ...(mw.length ? { mw } : {}) }); continue; }const args = m[4].replace(/\)\s*$/, '').split(',').map((s) => s.trim()).filter((s) => /^[A-Za-z_$][\w$.]*$/.test(s));- if (args.length) mounts.push({ prefix: m[3], var: args[args.length - 1], line: at(m.index) });+ if (args.length) mounts.push({ prefix: m[3], var: args[args.length - 1], line: at(m.index), ...(args.length > 1 ? { mw: args.slice(0, -1).map((s) => s.split('.').pop()) } : {}) });}// Next.js app/pages API routes, derived from the file pathdiff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjsindex 47bc988..87c406e 100644--- a/skills/floorplan/scripts/lib/health.mjs+++ b/skills/floorplan/scripts/lib/health.mjs@@ -314,7 +314,7 @@ export function findIssues(src, f) {// ======================= build: turn findings into issues =======================const SEV_ORDER = { high: 0, medium: 1, low: 2 };-const PUBLIC_PATH = /(^|\/)(health|healthz|healthcheck|ping|status|ready|readiness|live|liveness|version|metrics|robots\.txt|sitemap[\w.]*|favicon[\w.]*|\.well-known|login|logout|signin|pair|sign-in|signout|signup|sign-up|register|forgot[\w-]*|reset[\w-]*|verify[\w-]*|oauth\w*|callback|auth|token|refresh|static|assets|public|openapi\.json|docs|swagger[\w.]*|i|images?)(\/|$)/i;+const PUBLIC_PATH = /(^|\/)(health|healthz|healthcheck|ping|status|ready|readiness|live|liveness|version|metrics|robots\.txt|sitemap[\w.]*|favicon[\w.]*|\.well-known|login|logout|signin|pair|sign-in|signout|signup|sign-up|register|forgot[\w-]*|reset[\w-]*|verify[\w-]*|oauth\w*|callback|auth|token|refresh|static|assets|public|newsletter|contact|waitlist|unsubscribe|openapi\.json|docs|swagger[\w.]*|i|images?)(\/|$)/i;const WEBHOOK_PATH = /webhook|\/hooks?\//i;// endpoints under a webhook URL that manage the webhooks (create, list, test…) rather than receive themconst WEBHOOK_ADMIN = /\/(manage|admin|setup|settings|config|list|create|register|delete|test[\w-]*)(\/|$)/i;@@ -459,6 +459,8 @@ export function buildHealth({ graph, scan, arch, root }) {if (x.k === 'global-guard' && !TEST_FILE.test(f.path) && !/(^|\/)(scripts?|tools|bin|examples?)\//.test(f.path) && !(fileByPath.has(f.path) && kinds(fileByPath.get(f.path).n).some((k) => NOT_USED_KINDS.has(k)))) { const k = f.repo ?? ''; if (!globalGuards.has(k)) globalGuards.set(k, []); globalGuards.get(k).push({ ...x, file: f.path }); }if (x.k === 'guard-def' && !TEST_FILE.test(f.path)) { if (!guardDefs.has(x.name)) guardDefs.set(x.name, []); guardDefs.get(x.name).push({ file: f.path, wrapper: !!x.wrapper }); }}+ // a sign-in check applied where the route's router is mounted: app.use('/admin', requireStaff, adminRouter)+ const mountGuard = new Map((scan.routes || []).filter((r) => r.mountMw?.some(isGuardName)).map((r) => [`${r.file}|${r.line}|${r.method}`, r.mountMw.find(isGuardName)]));const perRepo = new Map(); // repo -> { guarded, open: [], guardCounts }graph.routes.forEach((r, i) => {const fnd = routeFinding.get(`${r.f}|${r.l}|${r.m}`);@@ -472,9 +474,10 @@ export function buildHealth({ graph, scan, arch, root }) {const global = (globalGuards.get(repo) || []).find((g) => g.framework === 'flask' || g.framework === 'express' || (g.framework === 'next' && fnd.fn === r.m));// an unrecognised decorator that turns out to be an auth wrapper defined elsewhere in the projectconst viaWrapper = !fnd.via && fnd.decos?.find((d) => guardDefs.get(d)?.some((g) => (g.file.split('/')[0] === r.f.split('/')[0])));- if (fnd.via || global || viaWrapper) {+ const mounted = !fnd.via && mountGuard.get(`${r.f}|${r.l}|${r.m}`);+ if (fnd.via || global || viaWrapper || mounted) {pr.guarded++; pr.guardedIn.set(r.f, (pr.guardedIn.get(r.f) || 0) + 1);- const name = fnd.guard || viaWrapper;+ const name = fnd.guard || viaWrapper || mounted;if (name) {pr.guardCounts.set(name, (pr.guardCounts.get(name) || 0) + 1);if (!pr.fileGuards.has(r.f)) pr.fileGuards.set(r.f, new Map());diff --git a/skills/floorplan/scripts/lib/routes.mjs b/skills/floorplan/scripts/lib/routes.mjsindex a6eadfb..711962f 100644--- a/skills/floorplan/scripts/lib/routes.mjs+++ b/skills/floorplan/scripts/lib/routes.mjs@@ -41,7 +41,7 @@ export function resolveRoutes(files) {const t = mountTarget(f, mount);if (!t) continue;if (!mountsTo.has(t.file)) mountsTo.set(t.file, []);- mountsTo.get(t.file).push({ from: f.path, v: t.v, prefix: mount.prefix });+ mountsTo.get(t.file).push({ from: f.path, v: t.v, prefix: mount.prefix, mw: mount.mw || [] });}// Every prefix a file's routes live under, composing nested mounts (a router mounted into a router// that is itself mounted), e.g. app.use('/api', api) + api.use('/users', users) → /api/users.@@ -54,13 +54,25 @@ export function resolveRoutes(files) {return [...new Set(out)];};+ // Middleware applied where a file's routers are mounted, all the way up: app.use('/admin', requireStaff, admin)+ // then admin.use('/orders', orders) puts requireStaff in front of every route in orders.+ const mountMw = (file, v, seen = new Set()) => {+ const ms = (mountsTo.get(file) || []).filter((m) => v == null || m.v === '*' || m.v === v);+ if (!ms.length || seen.has(file)) return [];+ const next = new Set(seen).add(file);+ // a route is only as protected as its least-protected mount+ const each = ms.map((m) => [...m.mw, ...(m.from === file ? [] : mountMw(m.from, null, next))]);+ return each.reduce((a, b) => a.filter((x) => b.includes(x)));+ };+const routes = [];for (const f of files) {// Test files define throwaway apps and stub servers; their routes aren't part of the system.if (!f.routes?.length || TEST_FILE.test(f.path)) continue;for (const r of f.routes) {const defPrefix = (r.var && f.routers?.[r.var]) || '';- for (const mp of outerPrefixes(f.path, r.var)) routes.push({ file: f.path, method: r.method, path: joinPath(mp, defPrefix, r.path), line: r.line, ...(r.handler ? { handler: r.handler } : {}), ...(r.doc ? { doc: r.doc } : {}) });+ const mw = mountMw(f.path, r.var);+ for (const mp of outerPrefixes(f.path, r.var)) routes.push({ file: f.path, method: r.method, path: joinPath(mp, defPrefix, r.path), line: r.line, ...(r.handler ? { handler: r.handler } : {}), ...(r.doc ? { doc: r.doc } : {}), ...(mw.length ? { mountMw: mw } : {}) });}}return dedupe(routes, (r) => `${r.file}|${r.method}|${r.path}`);