Skip to content

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

Fastify: put endpoints under the prefix their plugin is registered with

Richard Soares4e35b8de9482
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1ae1f14..9db4167 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,9 @@
# Changelog
+## Unreleased
+
+- **Fastify endpoints get their full address.** A plugin mounted with `app.register(plugin, { prefix: '/api/tickets' })` now puts its endpoints under that prefix, including plugins registered inside other plugins and ones loaded with `import()` or `require()`. Before, every plugin's endpoints sat at the root (`GET /`, `GET /:id`), so the website's requests were often matched to the wrong part of the server.
+
## 0.6.2 (2026-11-02)
- **Far fewer false alarms in Health** (thanks to @samuelpullen15-droid, who reported 13 of them from one site with the new **Not a problem** button):
diff --git a/README.md b/README.md
index e77ffd2..fed717f 100644
--- a/README.md
+++ b/README.md
@@ -239,7 +239,7 @@ flowchart LR
Scripts do the mechanical work: finding repos, parsing code in a dozen languages, matching web requests to endpoints, laying out the map. They're plain Node with no dependencies. Claude or Codex does the part only a reader can: deciding what the parts of your app *are*, and saying so plainly. Details in [How it works](docs/how-it-works.md).
**Languages:** TypeScript, JavaScript, Python, Go, Rust, Java, Kotlin, Scala, plus Vue, Svelte and Astro files, with lighter support for others.<br>
-**Endpoints:** Express, Koa, Hono, Next.js, Firebase Cloud Functions, Flask, FastAPI, Django, Go's net/http, Gin, Echo and chi, Actix, Axum, Spring.<br>
+**Endpoints:** Express, Fastify, Koa, Hono, Next.js, Firebase Cloud Functions, Flask, FastAPI, Django, Go's net/http, Gin, Echo and chi, Actix, Axum, Spring.<br>
**Screens:** Next.js, React Router, Vue, SvelteKit, Remix, Nuxt, Astro, Expo, Angular, TanStack.
## What it adds to your project
diff --git a/docs/development.md b/docs/development.md
index 1b07964..d84626a 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -83,6 +83,7 @@ The tests use Node's built-in test runner, so there's nothing to install (`npm t
| `health.test.mjs` | which endpoints Health calls open to anyone (FastAPI and Express samples in `fixtures/`) |
| `public-by-design.test.mjs` | what Health leaves alone because it's public on purpose (feeds, addresses a project publishes, cached responses, routes with nothing private, Payload CMS, tracker tokens, files a tool opens), each with a near miss it must still report |
| `stack-health.test.mjs` | Health's checks for Supabase row-level security, Firebase rules, Stripe webhook signatures, secret keys in public variables and CORS, with look-alikes each must leave alone, and a whole sample app done wrong and done right |
+| `fastify.test.mjs` | Fastify: plugins registered with a prefix, nested registers, and the website's requests reaching the right plugin (sample in `fixtures/`) |
| `firebase.test.mjs` | Firebase Cloud Functions: callables and onRequest functions as endpoints, the website's calls to them, Screens, Health, background functions (React + Firebase sample in `fixtures/`) |
| `blueprint.test.mjs` | a map planned from a PRD before any code exists: plan.json errors, endpoints and calls, Screens, the design review, refreshing and switching to the real code (sample PRD in `fixtures/`) |
| `blueprint-change.test.mjs` | changing a blueprint from the map: the agent's updated plan is checked, saved and highlighted, retried once when it fails the checks, and undone (stand-in CLI in `fixtures/fake-cli/`) |
diff --git a/docs/how-it-works.md b/docs/how-it-works.md
index 9c5ca02..59c2e1d 100644
--- a/docs/how-it-works.md
+++ b/docs/how-it-works.md
@@ -30,7 +30,7 @@ Supported languages: TypeScript and JavaScript (including Vue, Svelte and Astro
The most useful lines on the map connect a screen's web requests to the server code that answers them, often across repos. Floorplan:
-- **Finds endpoints** in Express, Koa, Hono, Next.js (route files and API routes), Firebase Cloud Functions, Flask, FastAPI, Django, Go (net/http, Gin, Echo, chi, Fiber), Actix, Axum and Spring.
+- **Finds endpoints** in Express, Fastify (plugin prefixes included), Koa, Hono, Next.js (route files and API routes), Firebase Cloud Functions, Flask, FastAPI, Django, Go (net/http, Gin, Echo, chi, Fiber), Actix, Axum and Spring.
- **Resolves prefixes**: Flask blueprints registered with a `url_prefix`, and Express routers mounted with `app.use('/api/users', usersRouter)`, including routers mounted inside other routers and mounts with middleware in front.
- **Finds requests** made with `fetch`, axios, ky, `requests` and similar, including:
- addresses built in a variable first: `const url = …; api.get(url)`;
diff --git a/skills/floorplan/SKILL.md b/skills/floorplan/SKILL.md
index c4b8e7b..34ce659 100644
--- a/skills/floorplan/SKILL.md
+++ b/skills/floorplan/SKILL.md
@@ -178,5 +178,5 @@ People can also use **Flows → Request a new flow** to have the agent trace som
- Paths are relative to the codebase root and use forward slashes. In a multi-repo root they start with the repo folder, e.g. `api-service/src/**`.
- Route keys in descriptions are `"METHOD /full/path"` exactly as the worksheet prints them.
- The map makes no outside requests: the build inlines the layout engine (ELK) and fonts from `${CLAUDE_SKILL_DIR}/assets/vendor/`, so it works offline.
-- HTTP edges come from matching URL strings at call sites (including URLs kept in a variable first, nested template strings, and small same-file helpers that add a path prefix) to route definitions (Flask, FastAPI, Express, Next.js, Spring, Go and others), with blueprint/router prefixes resolved, nested mounts included. Firebase callables are matched by name (`CALL /<name>`, from `httpsCallable`) and `onRequest` functions by URL; the summary's FIREBASE FUNCTIONS section lists scheduled and trigger functions, which belong in a `worker` node. Treat them as strong hints. If an important service-to-service link is missing, add it as an explicit edge.
+- HTTP edges come from matching URL strings at call sites (including URLs kept in a variable first, nested template strings, and small same-file helpers that add a path prefix) to route definitions (Flask, FastAPI, Express, Fastify, Next.js, Spring, Go and others), with blueprint/router/plugin prefixes resolved, nested mounts included. Firebase callables are matched by name (`CALL /<name>`, from `httpsCallable`) and `onRequest` functions by URL; the summary's FIREBASE FUNCTIONS section lists scheduled and trigger functions, which belong in a `worker` node. Treat them as strong hints. If an important service-to-service link is missing, add it as an explicit edge.
- Don't hand-edit graph.json or index.html; they're regenerated on every build.
diff --git a/skills/floorplan/scripts/lib/extract.mjs b/skills/floorplan/scripts/lib/extract.mjs
index 4b14efc..828f882 100644
--- a/skills/floorplan/scripts/lib/extract.mjs
+++ b/skills/floorplan/scripts/lib/extract.mjs
@@ -193,6 +193,14 @@ function extractJs(src, filePath) {
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), ...(args.length > 1 ? { mw: args.slice(0, -1).map((s) => s.split('.').pop()) } : {}) });
}
+ // Fastify plugins: app.register(ticketRoutes, { prefix: '/api/tickets' }), or register(import('./x.js'), …).
+ // Only an imported plugin counts: one defined in this file would put its prefix on every route here.
+ for (const m of all(/\.register\(\s*(?:await\s+)?(?:(?:import|require)\(\s*["']([^"'\n]+)["']\s*\)|([A-Za-z_$][\w$]*))\s*,\s*\{([^{}]*)\}/g, code)) {
+ const prefix = /\bprefix\s*:\s*["'`](\/[^"'`$]*)["'`]/.exec(m[3])?.[1];
+ if (prefix == null) continue;
+ if (m[1]) mounts.push({ prefix, spec: m[1], line: at(m.index) });
+ else if (imports.some((i) => i.locals && Object.hasOwn(i.locals, m[2]))) mounts.push({ prefix, var: m[2], line: at(m.index) });
+ }
// Next.js app/pages API routes, derived from the file path
const next = /(?:^|\/)(?:src\/)?app\/(.*?)\/?route\.(?:t|j)sx?$/.exec(filePath) || /(?:^|\/)(?:src\/)?pages\/(api\/.*?)(?:\/index)?\.(?:t|j)sx?$/.exec(filePath);
@@ -204,7 +212,8 @@ function extractJs(src, filePath) {
const triggers = /firebase-functions/.test(code) ? firebaseFunctions(code, at, routes, mounts) : [];
- const serverLine = /\b\w+\.(use|route)\(\s*["'`]\/|\b(?:app|server|fastify|hono|routes?|router|[a-z]+Router)\.(?:get|post|put|patch|delete|all|options|head)\(\s*["'`]\//;
+ // a mount's prefix (including Fastify's `prefix: '/api'` option, often on a line of its own) isn't a request
+ const serverLine = /\b\w+\.(use|route)\(\s*["'`]\/|\b(?:app|server|fastify|hono|routes?|router|[a-z]+Router)\.(?:get|post|put|patch|delete|all|options|head)\(\s*["'`]\/|\bprefix\s*:\s*["'`]\//;
const { calls, hosts } = extractCalls(code, at, { skip: serverLine });
const seenCall = new Set(calls.map((c) => `${c.line}|${c.path}`));
for (const c of wrapperCalls(code, at)) if (!seenCall.has(`${c.line}|${c.path}`)) calls.push(c);
diff --git a/tests/fastify.test.mjs b/tests/fastify.test.mjs
new file mode 100644
index 0000000..32bd630
--- /dev/null
+++ b/tests/fastify.test.mjs
@@ -0,0 +1,65 @@
+// Fastify: plugins mounted with app.register(plugin, { prefix }) put their routes under that prefix,
+// nested registers compose, and the website's requests reach the right plugin.
+import { test, before, after } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { REPO, lib, makeProject, run, readGraph, routeKeys, cleanup } from './helpers.mjs';
+
+const { extract } = await lib('extract.mjs');
+
+let root, graph;
+before(() => {
+ root = makeProject({}, { arch: {
+ project: { name: 'fastify-app', summary: 'Test fixture.' },
+ nodes: [
+ { id: 'web', label: 'Website', kind: 'ui', summary: 'The website.', paths: ['web/**'] },
+ { id: 'api', label: 'Server', kind: 'service', summary: 'The Fastify server.', paths: ['api/**'] },
+ ],
+ } });
+ fs.cpSync(path.join(REPO, 'tests', 'fixtures', 'fastify-app'), root, { recursive: true });
+ run('scan.mjs', root);
+ run('build.mjs', root, '--no-claude-md');
+ graph = readGraph(root);
+});
+after(() => cleanup(root));
+
+test('register(plugin, { prefix }) is a mount: imported by name, by import() or by require()', () => {
+ const r = extract([
+ `import ticketRoutes from './routes/tickets.js';`,
+ `import { inviteRoutes as invites } from './routes/invites.js';`,
+ `const legacy = require('./routes/legacy');`,
+ `async function local(app) { app.get('/x', h) }`,
+ `await app.register(ticketRoutes, { prefix: '/api/tickets' });`,
+ `await app.register(invites, {`,
+ ` prefix: '/api/invites',`,
+ `});`,
+ `app.register(import('./routes/health.js'), { prefix: '/health' });`,
+ `app.register(require('./routes/legacy'), { prefix: '/legacy' });`,
+ `app.register(local, { prefix: '/local' });`,
+ `app.register(cors, { origin: true });`,
+ 'app.register(ticketRoutes, { prefix: `/v${n}` });',
+ ].join('\n'), 'typescript', 'api/app.ts');
+ // a plugin defined in the same file, one with no prefix, and a prefix built at run time are left alone
+ assert.deepEqual(r.mounts.map((m) => `${m.prefix} ${m.var || m.spec}`), [
+ '/api/tickets ticketRoutes', '/api/invites invites', '/health ./routes/health.js', '/legacy ./routes/legacy',
+ ]);
+ // and a prefix isn't mistaken for a request the file makes
+ assert.deepEqual(r.calls, []);
+});
+
+test('endpoints get the prefix their plugin is registered under, through nested registers', () => {
+ assert.deepEqual(routeKeys(graph), [
+ 'GET /api/v1/buildings', 'GET /api/v1/buildings/:buildingId/faq', 'GET /api/v1/invites', 'GET /api/v1/tickets',
+ 'GET /api/v1/tickets/:id', 'GET /health', 'POST /api/v1/invites/accept', 'POST /api/v1/tickets/:id/accept',
+ ]);
+});
+
+test("the website's requests reach the plugin that answers them", () => {
+ const http = graph.links.filter((l) => l.k === 'http').map((l) => `${l.a.slice(2)} -> ${l.b.slice(2)} ${l.labels.join(', ')}`).sort();
+ assert.deepEqual(http, [
+ 'web/src/api.ts -> api/src/routes/buildings/faq.ts GET /api/v1/buildings/:buildingId/faq',
+ 'web/src/api.ts -> api/src/routes/invites.ts POST /api/v1/invites/accept',
+ 'web/src/api.ts -> api/src/routes/tickets.ts GET /api/v1/tickets, POST /api/v1/tickets/:id/accept',
+ ]);
+});
diff --git a/tests/fixtures/fastify-app/api/src/app.ts b/tests/fixtures/fastify-app/api/src/app.ts
new file mode 100644
index 0000000..d312049
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/app.ts
@@ -0,0 +1,18 @@
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import ticketRoutes from './routes/tickets.js';
+import { inviteRoutes } from './routes/invites.js';
+import buildingRoutes from './routes/buildings/index.js';
+
+export async function buildApp() {
+ const app = Fastify();
+ await app.register(cors, { origin: ['https://example.com'] });
+ await app.register(ticketRoutes, { prefix: '/api/v1/tickets' });
+ await app.register(inviteRoutes, {
+ prefix: '/api/v1/invites',
+ logLevel: 'warn',
+ });
+ await app.register(buildingRoutes, { prefix: '/api/v1/buildings' });
+ await app.register(import('./routes/health.js'), { prefix: '/health' });
+ return app;
+}
diff --git a/tests/fixtures/fastify-app/api/src/routes/buildings/faq.ts b/tests/fixtures/fastify-app/api/src/routes/buildings/faq.ts
new file mode 100644
index 0000000..7e3e98f
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/routes/buildings/faq.ts
@@ -0,0 +1,5 @@
+import type { FastifyInstance } from 'fastify';
+
+export default async function faqRoutes(app: FastifyInstance) {
+ app.get('/', async () => []);
+}
diff --git a/tests/fixtures/fastify-app/api/src/routes/buildings/index.ts b/tests/fixtures/fastify-app/api/src/routes/buildings/index.ts
new file mode 100644
index 0000000..a774021
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/routes/buildings/index.ts
@@ -0,0 +1,8 @@
+import type { FastifyInstance } from 'fastify';
+import faqRoutes from './faq.js';
+
+export default async function buildingRoutes(app: FastifyInstance) {
+ app.get('/', async () => []);
+ // a plugin registered inside a plugin: its routes sit under both prefixes
+ await app.register(faqRoutes, { prefix: '/:buildingId/faq' });
+}
diff --git a/tests/fixtures/fastify-app/api/src/routes/health.ts b/tests/fixtures/fastify-app/api/src/routes/health.ts
new file mode 100644
index 0000000..e70eb7f
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/routes/health.ts
@@ -0,0 +1,5 @@
+import type { FastifyInstance } from 'fastify';
+
+export default async function health(app: FastifyInstance) {
+ app.get('/', async () => ({ ok: true }));
+}
diff --git a/tests/fixtures/fastify-app/api/src/routes/invites.ts b/tests/fixtures/fastify-app/api/src/routes/invites.ts
new file mode 100644
index 0000000..07503c4
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/routes/invites.ts
@@ -0,0 +1,7 @@
+import type { FastifyInstance } from 'fastify';
+
+/** Invitations to join a building. */
+export async function inviteRoutes(fastify: FastifyInstance) {
+ fastify.get('/', async () => []);
+ fastify.post('/accept', async () => ({ ok: true }));
+}
diff --git a/tests/fixtures/fastify-app/api/src/routes/tickets.ts b/tests/fixtures/fastify-app/api/src/routes/tickets.ts
new file mode 100644
index 0000000..a35a0f8
--- /dev/null
+++ b/tests/fixtures/fastify-app/api/src/routes/tickets.ts
@@ -0,0 +1,8 @@
+import type { FastifyInstance } from 'fastify';
+
+/** Tickets residents raise about their building. */
+export default async function ticketRoutes(app: FastifyInstance) {
+ app.get('/', async () => []);
+ app.get('/:id', async () => ({}));
+ app.post('/:id/accept', async () => ({ ok: true }));
+}
diff --git a/tests/fixtures/fastify-app/web/src/api.ts b/tests/fixtures/fastify-app/web/src/api.ts
new file mode 100644
index 0000000..b3bf970
--- /dev/null
+++ b/tests/fixtures/fastify-app/web/src/api.ts
@@ -0,0 +1,6 @@
+const API = '/api/v1';
+
+export const listTickets = () => fetch(`${API}/tickets`).then((r) => r.json());
+export const acceptTicket = (id: string) => fetch(`${API}/tickets/${id}/accept`, { method: 'POST' });
+export const acceptInvite = () => fetch('/api/v1/invites/accept', { method: 'POST' });
+export const buildingFaq = (id: string) => fetch(`/api/v1/buildings/${id}/faq`).then((r) => r.json());