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
Fastify: put endpoints under the prefix their plugin is registered with
Richard Soares4e35b8de9482
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.mdindex e77ffd2..fed717f 100644--- a/README.md+++ b/README.md@@ -239,7 +239,7 @@ flowchart LRScripts 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 projectdiff --git a/docs/development.md b/docs/development.mdindex 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.mdindex 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 AstroThe 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.mdindex 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.mjsindex 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 pathconst 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.mjsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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());