The layers of the API

In 1 minute

The API is a Fastify server with tRPC, and every request walks down the same three layers. A procedure checks the input and calls a service. A service holds the business rules. A query is the only code that touches Postgres or Redis, and a queue file is the only code that touches SNS. Each layer calls only the layer below, so every rule lives in exactly one place.

Picture it

flowchart TB
  R["HTTP request /trpc/bookings.create"] --> P["procedure<br/>validate input with Zod"]
  P --> S["service<br/>business rules, no HTTP, no SQL"]
  S --> Q["query<br/>Postgres, Redis"]
  S --> U["queue<br/>SNS"]

How it works

1. Procedure (procedures/<feature>.ts): validates the input with a shared Zod schema, picks the user from the session, calls one service function and returns. No logic.
2. Service (services/<feature>.ts): decides. “Is this a repeat booking? Is the key reused?” It knows no HTTP and no SQL; it throws plain errors like ConflictError.
3. Query (queries/<feature>.ts): reads and writes Postgres or Redis. No business rules.
4. Queue (queues/<feature>.ts): publishes messages to SNS. Like a query, no rules, and only services call it.

In MiniTickets

Booking, layer by layer:

Layer	File and function	Does
procedure	procedures/bookings.ts → create	BookTicketInput, rate limit, call service
service	apps/api/src/services/bookings.ts → bookTicket	replay or 409, clear caches
query	apps/api/src/queries/bookings.ts → createBookingTx	the locked transaction

The input schemas live in packages/shared, so the browser form and the server check the same rules. The web app imports only the router’s TypeScript type, never server code.

One deliberate exception: the three booking checks (event exists, not started, enough seats) sit in the query, because they must run on the locked row inside the transaction, and a service never holds a transaction.

From → to	What happens	What allows it
API ECS service → API apponly when computeEnabled = true	each api task runs the Fastify server on port 4000	config container api, HOST 0.0.0.0, PORT 4000createApiTask
Browser → API app	calls /trpc/* with the sid cookie	url same origin, so no CORS question; every mutation must carry the exact Origin (CSRF check, mutationAllowed)mutationAllowed
Web app → API app	server-side rendering of /events calls the api	service-connect makeServerTrpcClient uses API_INTERNAL_URL http://api:4000makeServerTrpcClient
API app → Sessions	reads the session of every request	code createContext reads the sid cookie and asks queries/sessions.tscreateContext
API app → Events list cache	events.list asks the cache first	code services/events.ts listUpcomingEvents → queries/events-cache.tslistUpcomingEvents
API app → Rate limiter	log-in and booking take a token first	code procedures call enforceRateLimit('login' | 'booking', ...)enforceRateLimit
API app → Inventory gate	a booking asks the gate before the database transaction	code services/bookings.ts bookTicket → createGatedBookingcreateGatedBooking
API app → RDS Postgresonly when dataEnabled = true	queries/*.ts run the SQL; a booking locks the event row (SELECT … FOR UPDATE)	code only queries/*.ts touch PostgrescreateBookingTx
API app → Transactional outbox	the booking and its outbox row are written in one transaction	code createBookingTx inserts the booking and the BookingConfirmedMessage row togethercreateBookingTx

See the API app on the map →

See it in AWS

Console

CloudWatch → Log groups → /minitickets/dev/api: each request line carries correlationId, responseTime and, for events.list, a cache field.

CLI

aws logs tail /minitickets/dev/api --since 10m

Code

The router that joins all procedures: apps/api/src/trpc/router.ts → appRouter.

Break it

Symptom	Cause	Where to look
A rule works in one route but not another	The rule was copied into a procedure	Move it into the service
The ALB keeps sending traffic while Postgres is down	By design: health checks use /health	/ready in apps/api/src/app.ts
A test needs a database to test a rule	Business logic leaked into a query	The service should decide

Say it in an interview

Say it like this (20-30 seconds)

The API has three layers. Procedures validate input with shared Zod schemas and call a service. Services hold all business logic and know nothing about HTTP or SQL. Queries are the only code that touches Postgres or Redis, and queue files the only code that publishes to SNS. Each layer calls only the one below, so a rule lives in one place and services can be unit-tested with the data layer mocked.

Follow-ups

Why not put the SQL straight into the procedure?

Then the same rule ends up in every procedure that needs it, and they drift apart. It also ties business rules to HTTP, so you cannot test or reuse them without a server.

Where do HTTP status codes come from, if services know no HTTP?

Services throw plain errors such as NotFoundError. One middleware, the error mapper, turns each kind into a tRPC code, which becomes the HTTP status. The Errors chapter shows it.

What is the cost of the strict layers?

More files and a little more code for small features. The booking checks had to break the rule once, on purpose, because they need the transaction.

Advanced: Health, readiness and the correlation id

GET /health only says the process is up; GET /ready also pings Postgres and Redis. Every request gets a correlation id, returned as x-correlation-id and written on every log line; the booking service puts it into the outbox message so the worker’s lines carry it too. The app is built in apps/api/src/app.ts → buildApp.

Checkpoint

Answer these without scrolling up. If one feels hard, reread that section.

1. What is the only job of a procedure?
2. Which layer decides that a reused idempotency key is a 409?
3. Which code may touch Redis, and which may publish to SNS?
4. Why do the booking checks break the layer rule, and where?
5. Where do the input schemas live, and why there?

Redraw it from memory: request → procedure → service → query and queue, with one job per box

Try this: open apps/api/src/procedures/bookings.ts and follow bookings.create down to the SQL, naming the layer of each file

Mark this page as read