Glossary

Terms the docs and the code use without stopping to explain them. Each entry links to where the term is covered in full.

Data and deletion

Migration: a numbered file in backend/migrations/ (001_initial.ts onwards) that creates or changes tables. npm run migrate runs the ones your database has not run yet. Define the persistence layer.
Ghost deletion: how account deletion works. UsersService.ghostDelete keeps the users row and overwrites its identifying fields, so other rows that point at the user still resolve, and deletes or scrubs the user's data in the tables it names. What Ghost Deletion Erases.
DELETION_POLICY: the list in backend/src/users/deletion-policy.ts that says, for every table, what account deletion does to it: erases (and which method does it) or keeps (and why). Testing.
Erased / kept: for a table whose rows survive deletion, every column is listed as erased (the eraser overwrites it) or kept (every other column, ids, foreign keys and timestamps included). A kept column can still identify a person, such as the Stripe customer id in billing_disputed_customers; the table's keeps reason has to say why it stays. Recipe 1, step 6.
Eraser: a method named in ERASERS that performs deletion: ghostDelete in users.service.ts, or the worker's processDeletionQueue, both listed in backend/src/users/deletion-policy.ts.
DTO (data transfer object): the shape a route sends or receives, declared as a zod schema in the feature's *.schemas.ts file. Define schemas and DTOs.
DTO extractor: the function at the bottom of a *.schemas.ts file, named extractFooDtoFromRow, that turns a database row into a DTO. A field it leaves out never reaches the API. backend/CLAUDE.md.

Routes and access

Guard: a NestJS class that decides whether a request may reach a route. SessionGuard needs a signed-in user, AdminGuard an admin, and InternalApiTokenGuard the internal token. Backend: Validating the Token.
POLICY (in route-auth.spec.ts): one entry per controller, stating the guards each route requires or the reason it is public. A controller with classGuards states them once for all its routes; on any other controller, a route it does not list fails the spec. Testing.
Internal token: INTERNAL_API_TOKEN, a secret shared by the two halves. The frontend sends it as X-Internal-Token to the backend's /internal/* routes, which the browser never calls. Shared secrets.
Backoffice: the admin area at /backoffice. Anyone who is not an admin gets a 404 there. Make yourself an admin.
Magic link: a one-time sign-in link sent by email. The frontend sends it itself; in development it lands in MailDev, a local inbox at http://localhost:1080. Email.

Frontend

Server Component (RSC): a page or component that renders on the server and can fetch with the session. Server Action: a server function a form calls, kept in a colocated actions.ts. Client island: the small 'use client' component inside a server-rendered page. frontend/CLAUDE.md.
api / serverApi() / internalApi(): the three API clients in frontend/lib/api.ts. api makes public, unauthenticated calls. serverApi() runs only on the server and sends the user's session as a bearer token. internalApi() runs only on the server and sends the internal token. frontend/CLAUDE.md.
Split-horizon: API_URL_SERVER gives server-side code a different backend address than the browser's NEXT_PUBLIC_API_URL, for when the server reaches the backend over a private network. Frontend variables.

Billing

Entitlement: what BillingService.getEntitlement(userId) returns about a user's plan. Its paidAccess field is the one to branch on. Gate a feature behind a subscription.
Dormant billing: with no STRIPE_SECRET_KEY the billing module does nothing. /pricing is a 404 and every user is on the free plan. Billing.
Free-plan cap: the limit on items a free user may create, in ItemsService.create. The worked example of gating on paidAccess. Gating features.

MCP

MCP (Model Context Protocol): how an AI agent calls tools on a server. The backend's admin MCP server at /admin/mcp lets an agent operate the deployed app with ADMIN_MCP_API_KEY. Admin MCP Server.
Stateless transport: each MCP request builds a fresh server, answers, and is thrown away. There are no MCP sessions to store. Admin MCP Server.
get_server_info: the MCP tool that lists every other tool. Its list is kept by hand, and a spec fails when it drifts. Testing.

Checks and updates

./verify.sh: the one command that runs the format check, lint, knip, builds, tests and drift checks for both halves. Testing.
knip: the tool that fails on unused files, exports and dependencies. Troubleshooting.
Integration spec: a backend test named *.integration.spec.ts that runs real SQL. It skips without TEST_DATABASE_URL. Testing.
Drift: a generated file (openapi.json, frontend/types/api.d.ts) that no longer matches what the code generates. verify fails on it. Troubleshooting.
Upstream: the template repository your app was copied from. Updating from upstream.
Breaking / action required: the first list under each release in CHANGELOG.md: changes that merge cleanly and then need something done by hand. Changelog.

Home - Docs index

Data and deletion

Migration: a numbered file in backend/migrations/ (001_initial.ts onwards) that creates or changes tables. npm run migrate runs the ones your database has not run yet. Define the persistence layer.

Ghost deletion: how account deletion works. UsersService.ghostDelete keeps the users row and overwrites its identifying fields, so other rows that point at the user still resolve, and deletes or scrubs the user's data in the tables it names. What Ghost Deletion Erases.

DELETION_POLICY: the list in backend/src/users/deletion-policy.ts that says, for every table, what account deletion does to it: erases (and which method does it) or keeps (and why). Testing.

Erased / kept: for a table whose rows survive deletion, every column is listed as erased (the eraser overwrites it) or kept (every other column, ids, foreign keys and timestamps included). A kept column can still identify a person, such as the Stripe customer id in billing_disputed_customers; the table's keeps reason has to say why it stays. Recipe 1, step 6.

Eraser: a method named in ERASERS that performs deletion: ghostDelete in users.service.ts, or the worker's processDeletionQueue, both listed in backend/src/users/deletion-policy.ts.

DTO (data transfer object): the shape a route sends or receives, declared as a zod schema in the feature's *.schemas.ts file. Define schemas and DTOs.

DTO extractor: the function at the bottom of a *.schemas.ts file, named extractFooDtoFromRow, that turns a database row into a DTO. A field it leaves out never reaches the API. backend/CLAUDE.md.

Routes and access

Guard: a NestJS class that decides whether a request may reach a route. SessionGuard needs a signed-in user, AdminGuard an admin, and InternalApiTokenGuard the internal token. Backend: Validating the Token.

POLICY (in route-auth.spec.ts): one entry per controller, stating the guards each route requires or the reason it is public. A controller with classGuards states them once for all its routes; on any other controller, a route it does not list fails the spec. Testing.

Internal token: INTERNAL_API_TOKEN, a secret shared by the two halves. The frontend sends it as X-Internal-Token to the backend's /internal/* routes, which the browser never calls. Shared secrets.

Backoffice: the admin area at /backoffice. Anyone who is not an admin gets a 404 there. Make yourself an admin.

Magic link: a one-time sign-in link sent by email. The frontend sends it itself; in development it lands in MailDev, a local inbox at http://localhost:1080. Email.

Frontend

Server Component (RSC): a page or component that renders on the server and can fetch with the session. Server Action: a server function a form calls, kept in a colocated actions.ts. Client island: the small 'use client' component inside a server-rendered page. frontend/CLAUDE.md.

api / serverApi() / internalApi(): the three API clients in frontend/lib/api.ts. api makes public, unauthenticated calls. serverApi() runs only on the server and sends the user's session as a bearer token. internalApi() runs only on the server and sends the internal token. frontend/CLAUDE.md.

Split-horizon: API_URL_SERVER gives server-side code a different backend address than the browser's NEXT_PUBLIC_API_URL, for when the server reaches the backend over a private network. Frontend variables.

Billing

Entitlement: what BillingService.getEntitlement(userId) returns about a user's plan. Its paidAccess field is the one to branch on. Gate a feature behind a subscription.

Dormant billing: with no STRIPE_SECRET_KEY the billing module does nothing. /pricing is a 404 and every user is on the free plan. Billing.

Free-plan cap: the limit on items a free user may create, in ItemsService.create. The worked example of gating on paidAccess. Gating features.

MCP

MCP (Model Context Protocol): how an AI agent calls tools on a server. The backend's admin MCP server at /admin/mcp lets an agent operate the deployed app with ADMIN_MCP_API_KEY. Admin MCP Server.

Stateless transport: each MCP request builds a fresh server, answers, and is thrown away. There are no MCP sessions to store. Admin MCP Server.

get_server_info: the MCP tool that lists every other tool. Its list is kept by hand, and a spec fails when it drifts. Testing.

Checks and updates

./verify.sh: the one command that runs the format check, lint, knip, builds, tests and drift checks for both halves. Testing.

knip: the tool that fails on unused files, exports and dependencies. Troubleshooting.

Integration spec: a backend test named *.integration.spec.ts that runs real SQL. It skips without TEST_DATABASE_URL. Testing.

Drift: a generated file (openapi.json, frontend/types/api.d.ts) that no longer matches what the code generates. verify fails on it. Troubleshooting.

Upstream: the template repository your app was copied from. Updating from upstream.

Breaking / action required: the first list under each release in CHANGELOG.md: changes that merge cleanly and then need something done by hand. Changelog.

Glossary

Data and deletion

Routes and access

Frontend

Billing

MCP

Checks and updates

Related

Glossary

Data and deletion

Routes and access

Frontend

Billing

MCP

Checks and updates

Related