Backend Development Guide
This guide explains how to work on the FF RESTaurent API in apps/api. It
reflects the current Fastify/Prisma backend shipped with v1.1.0.
Technology Stack
- Node.js with TypeScript and native ESM
- Fastify 5
@fastify/jwtfor bearer-token authentication@fastify/cors,@fastify/rate-limit,@fastify/multipart- Prisma 6 with PostgreSQL
- Zod request validation
- Swagger UI at
/api/docs - Supabase storage for restaurant media and payment QR images
@ff-restaurent/sharedfor shared enums, phone parsing, and bill-splitting math
Source Layout
apps/api/
|-- prisma/
| |-- schema.prisma
| |-- migrations/
| |-- seed.ts
| |-- seed-if-empty.ts
| |-- seed-popular-cuisines.ts
| |-- backfill-user-phones.ts
| |-- bootstrap-root-admin.ts
| |-- recover-root-admin.ts
| |-- verify-final-query-indexes.ts
| `-- verify-phase2-contract.ts
`-- src/
|-- app.ts
|-- server.ts
|-- config.ts
|-- prisma.ts
|-- roles.ts
|-- schemas.ts
|-- types.d.ts
|-- collection-service.ts
|-- restaurant-contract.ts
|-- root-admin-service.ts
|-- storage.ts
|-- phone-backfill.ts
|-- popular-cuisine-seed.ts
|-- pagination.ts
|-- search-normalization.ts
|-- catalog-normalization.ts
|-- address-directory.ts
|-- http/
| |-- auth-guards.ts
| `-- error-handler.ts
|-- routes/
| |-- auth-routes.ts
| |-- profile-routes.ts
| |-- member-routes.ts
| |-- restaurant-routes.ts
| |-- catalog-routes.ts
| |-- collection-routes.ts
| |-- feedback-routes.ts
| |-- media-routes.ts
| |-- bill-routes.ts
| |-- notification-routes.ts
| |-- participant-group-routes.ts
| |-- stats-routes.ts
| `-- address-routes.ts
`-- data/
`-- vietnam-wards-full.json
Tests are colocated with source files as *.test.ts.
Request Flow
The backend request flow should remain direct:
HTTP request
-> Fastify route
-> auth or role preHandler when required
-> Zod schema parse for request data
-> Prisma query or shared package calculation
-> serializer or response object
-> global error mapper when needed
src/app.ts is composition-only. It registers core plugins, Swagger, health
routes, the global error handler, and route modules. Do not move domain logic
back into app.ts.
src/server.ts owns process startup and graceful shutdown. Keep runtime
concerns there.
Route Modules
Route files under src/routes own one API area each. Keep request parsing,
resource ownership checks, Prisma query shape, and response shaping close to the
route when that logic is route-specific.
Use shared services only when logic is reused or has an independent domain contract:
collection-service.tsowns collection/favorite/recommended behavior.restaurant-contract.tsderives backward-compatible restaurant response aliases from normalized persistence.root-admin-service.tsowns root transfer behavior.storage.tsowns Supabase-backed media access.phone-backfill.tsandpopular-cuisine-seed.tssupport idempotent startup operations.
Validation and Errors
All request validation belongs in src/schemas.ts unless the schema has already
been moved into a more focused module. Route handlers should parse with Zod
instead of manually validating request bodies.
When changing request or response fields:
- Update the Zod schema.
- Update the route handler and Prisma select/include shape.
- Update serializers such as
restaurant-contract.tswhen relevant. - Update web API types in
apps/web/src/lib/api.ts. - Add or update focused tests.
The global error mapper in src/http/error-handler.ts should remain the place
where common API errors become consistent HTTP responses.
Roles and Authorization
Effective permissions ascend as:
CUSTOMER < SOUS_CHEF < HEAD_CHEF < ROOT_ADMIN
- CUSTOMER is represented by
chefRole: null. - SOUS_CHEF can create restaurants and bills and manage owned work.
- HEAD_CHEF adds global bill visibility and archive/restore capabilities.
- ROOT_ADMIN is the singleton
systemRole, inherits Head Chef capabilities, and exclusively manages member roles, root transfer, password-recovery administration, and other system controls.
chefRole and systemRole are independent. HEAD_CHEF must never change member
roles or ROOT_ADMIN ownership.
Use auth pre-handlers from src/http/auth-guards.ts for broad route access.
Use route-local checks for ownership rules that require loading the target
record, such as bill creator checks or participant payment checks.
Always sanitize users through the role/public-user helpers before returning user objects. Never serialize password hashes, reset-code hashes, or session-version internals.
Money and Bill Splitting
All persisted and API monetary values are integer cents. Never use float math for bill totals, participant shares, discounts, VAT, shipping, or vouchers.
Core calculation logic lives in:
packages/shared/src/bill-splitting.ts
The API should call calculateBillSplit() and persist the returned integer-cent
values. Do not duplicate allocation logic inside route handlers. If bill math
changes, update shared tests at the same time:
npm test --workspace @ff-restaurent/shared
Database and Phase 2 Contracts
Database models, enums, constraints, and relations live in:
apps/api/prisma/schema.prisma
For schema changes:
- Update
schema.prisma. - Create a Prisma migration.
- Regenerate the Prisma client.
- Update route query shapes and serializers.
- Update web API types.
- Update seed/backfill scripts when production or demo data needs coverage.
- Add focused API tests or migration verification as needed.
Use deploy mode for production:
npm run prisma:migrate:deploy --workspace @ff-restaurent/api
Do not run prisma migrate dev against production.
The v1.1.0 Phase 2 contract is complete:
- Collections are the sole persistence authority for Favorites and Recommended restaurants.
CuisineandRestaurantCuisineare the cuisine authority.RestaurantPlatformLinkrows are the platform-link authority.- Legacy restaurant response aliases are derived by
restaurant-contract.ts. - The deprecated
linkswrite input is still accepted and translated to normalized platform links.
Verify the normalized restaurant contract against a live database with:
npm run prisma:phase2:contract:verify --workspace @ff-restaurent/api
Phone, Password, and Root Operations
Vietnamese phone parsing is shared, but the API is authoritative. Optional phone numbers persist as canonical E.164 values. Startup runs the idempotent phone backfill after migrations.
JWTs carry sessionVersion. Password changes, assisted password resets, and
root transfers invalidate affected older sessions.
Production root bootstrap uses ROOT_ADMIN_USERNAME only when no root exists.
Emergency root recovery is interactive and operator-only:
npm run prisma:root:recover --workspace @ff-restaurent/api
Do not expose root recovery through HTTP or web UI.
Local Development
Run the full stack with Docker:
docker compose up --build
Expected local endpoints:
API: http://localhost:4000
Health: http://localhost:4000/health
Ready: http://localhost:4000/ready
Swagger: http://localhost:4000/api/docs
Web: http://localhost:5173
Run only the API:
npm run dev --workspace @ff-restaurent/api
API typecheck, build, and Prisma commands load apps/api/prisma.config.ts and
therefore require DATABASE_URL, even when they do not query the database.
State clearly when database-backed verification was skipped.
Verification
For API-only changes:
npm run typecheck --workspace @ff-restaurent/api
npm run lint --workspace @ff-restaurent/api
npm test --workspace @ff-restaurent/api
npm run build --workspace @ff-restaurent/api
For Prisma or contract changes:
npm run prisma:generate --workspace @ff-restaurent/api
npm run prisma:indexes:verify --workspace @ff-restaurent/api
npm run prisma:phase2:contract:verify --workspace @ff-restaurent/api
For shared bill math or shared types:
npm test --workspace @ff-restaurent/shared
npm run build --workspace @ff-restaurent/shared
For broad changes before review:
npm run typecheck
npm run lint
npm test
npm run build
Backend Change Checklist
- Put endpoints in the route module that owns the resource.
- Use
requireAuthenticatedUserbefore readingrequest.currentUser. - Use role pre-handlers for broad access gates and route-local checks for ownership.
- Parse request data with Zod schemas.
- Use Prisma for persistence.
- Keep money as integer cents and delegate split math to
packages/shared. - Return sanitized users only.
- Preserve ROOT_ADMIN-only governance.
- Preserve Phase 2 normalized restaurant persistence contracts.
- Update web API types when API response contracts change.
- Add focused tests before broad verification.