Skip to content

See how your app actually fits together. An interactive, plain-English map of your codebase, drawn by Claude or Codex.

Floorplan 0.1.1: screenshots, more connections, fewer false alarms

Hayden Smithdd29998e90f9
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index 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.md
index 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.md
index 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.
[![Claude Code plugin](https://img.shields.io/badge/Claude%20Code-plugin-D97757?style=flat-square)](https://code.claude.com/docs/en/overview)
-[![Version](https://img.shields.io/badge/version-0.1.0-111?style=flat-square)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.1.1-111?style=flat-square)](CHANGELOG.md)
[![License: MIT](https://img.shields.io/badge/license-MIT-111?style=flat-square)](LICENSE)
[![Node 18+](https://img.shields.io/badge/node-%E2%89%A518-111?style=flat-square)](https://nodejs.org)
[![Zero dependencies](https://img.shields.io/badge/dependencies-0-111?style=flat-square)](#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, file
link. 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 ru
Plus 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>
+
## Install
You 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.png
new file mode 100644
index 0000000..38fca21
Binary files /dev/null and b/docs/images/ask.png differ
diff --git a/docs/images/flow.png b/docs/images/flow.png
new file mode 100644
index 0000000..3875b92
Binary files /dev/null and b/docs/images/flow.png differ
diff --git a/docs/images/health.png b/docs/images/health.png
new file mode 100644
index 0000000..6aa9fc3
Binary files /dev/null and b/docs/images/health.png differ
diff --git a/docs/images/inside.png b/docs/images/inside.png
new file mode 100644
index 0000000..c9ff84a
Binary files /dev/null and b/docs/images/inside.png differ
diff --git a/docs/images/overview.png b/docs/images/overview.png
new file mode 100644
index 0000000..9309176
Binary files /dev/null and b/docs/images/overview.png differ
diff --git a/docs/images/recent.png b/docs/images/recent.png
new file mode 100644
index 0000000..6fb652a
Binary files /dev/null and b/docs/images/recent.png differ
diff --git a/docs/images/screens.png b/docs/images/screens.png
new file mode 100644
index 0000000..dec5bcb
Binary files /dev/null and b/docs/images/screens.png differ
diff --git a/docs/using-the-map.md b/docs/using-the-map.md
index 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 titles
Double-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.js
index 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 up
const 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.html
index 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 too
const { 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.mjs
index 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 below
const 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 path
diff --git a/skills/floorplan/scripts/lib/health.mjs b/skills/floorplan/scripts/lib/health.mjs
index 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 them
const 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 project
const 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.mjs
index 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}`);