How to Build a Backend Picture Book
Clientthe diner APIthe waiter Logicthe kitchen DBthe pantry What a backend is responsible for receive requests · check who's asking · apply the rules read and write data · talk to other services stay up, stay fast, stay secure · tell you when it breaks
PLATE 0 — The user never sees the kitchen. They just expect the right dish, fast.
A picture book for grown-ups · with code

How to Build a Backend

Nine spreads, from an empty folder to a deployed, tested API with a database and logins. Examples use Node.js, Express and PostgreSQL. The ideas carry to Python, Go, Java, and the rest.

Say it like a pro

"A stateless REST API with validation, a database behind a data layer, token auth, structured logging, tests, and a container in CI."

Use the tabs or the ← → keys to turn pages.

Request logmiddleware authmiddleware validatemiddleware routehandler Service (rules) Data layer → DB JSON response + status Keep each layer to one job handler: parse request, call service, shape the response service: business rules (no HTTP, no SQL) data layer: the only code that knows the database
PLATE 1 — Every request walks the same road. Cross-cutting concerns live in middleware.
Chapter 1 · The request lifecycle

HTTP in, JSON out

A backend is a program that listens on a port and answers HTTP requests. Each request has a method, a path, headers, and maybe a body. Each response has a status code and usually JSON.

// The smallest possible backend (Node 20+)
const http = require('http');
http.createServer((req, res) => {
  if (req.method === 'GET' && req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json' });
    return res.end(JSON.stringify({ ok: true }));
  }
  res.writeHead(404); res.end();
}).listen(3000);
$ curl -i localhost:3000/health
stateless
keep nothing about a user in server memory between requests; that's how you scale to many copies
framework
Express, Fastify, Django, Spring: routing, parsing and middleware, so you don't hand-roll them
Say it like a pro

"Thin handlers, a service layer for the rules, and middleware for the cross-cutting stuff."

my-api/ ├─ src/ │ ├─ server.js starts listening │ ├─ app.js builds the Express app │ ├─ routes/ URL → handler │ ├─ services/ business rules │ ├─ db/ queries + pool │ ├─ middleware/ auth, errors, logging │ └─ config.js env vars, validated ├─ migrations/ schema changes ├─ test/ ├─ .env.example · .gitignore ├─ Dockerfile · package.json └─ README.md
PLATE 2 — A boring, predictable layout lets anyone find anything.
Chapter 2 · Project setup

From empty folder to "hello"

$ mkdir my-api && cd my-api && git init
$ npm init -y
$ npm install express pg zod bcrypt jsonwebtoken pino dotenv
$ npm install -D jest supertest nodemon
$ printf "node_modules\n.env\n" > .gitignore
src/app.js · src/server.js
// app.js: build the app (importable by tests)
const express = require('express');
const app = express();
app.use(express.json());
app.get('/health', (req, res) => res.json({ ok: true }));
module.exports = app;

// server.js: start listening
const app = require('./app');
const { port } = require('./config');
app.listen(port, () => console.log(`listening on ${port}`));
src/config.js · config from the environment
require('dotenv').config();
const need = (k) => { if (!process.env[k]) throw new Error(`missing ${k}`); return process.env[k]; };
module.exports = {
  port: Number(process.env.PORT) || 3000,
  databaseUrl: need('DATABASE_URL'),
  jwtSecret: need('JWT_SECRET'),
};
Say it like a pro

"Separate the app from the server so tests can import it, and fail fast if config is missing."

VerbPathActionSuccess GET/taskslist200 POST/taskscreate201 GET/tasks/:idread one200 / 404 PATCH/tasks/:idupdate200 DELETE/tasks/:idremove204 Conventions that save arguments nouns in paths, verbs in methods · plural collections filter and page with query strings: /tasks?done=false&limit=20
PLATE 3 — Five routes cover most of what an app needs for one resource.
Chapter 3 · Routes & REST

Resources, verbs, and status codes

// src/routes/tasks.js
const router = require('express').Router();
const tasks = require('../services/tasks');

router.get('/', async (req, res) => {
  res.json(await tasks.list(req.user.id, req.query));
});
router.post('/', async (req, res) => {
  res.status(201).json(await tasks.create(req.user.id, req.body));
});
router.get('/:id', async (req, res) => {
  const t = await tasks.get(req.user.id, req.params.id);
  if (!t) return res.sendStatus(404);
  res.json(t);
});
router.delete('/:id', async (req, res) => {
  await tasks.remove(req.user.id, req.params.id);
  res.sendStatus(204);
});
module.exports = router;

// app.js:  app.use('/api/v1/tasks', requireAuth, require('./routes/tasks'));
200 / 201 / 204
ok / created / ok, no body
400 / 401 / 403 / 404 / 409
bad input / not logged in / not allowed / not found / conflict
500
our bug. Log it, don't leak details.
versioning
/api/v1/… so you can evolve safely
Say it like a pro

"Plural nouns, correct verbs, honest status codes, and pagination from day one."

raw body schema checkzod / Joi service 400 One error shape for every failure { "error": { "code": "VALIDATION", "message": "title is required" } } clients can rely on it · stack traces stay in the logs Never trust the client check types, lengths, ranges, allowed values reject unknown fields · cap body size · parameterize SQL client-side validation is a courtesy, not a defence
PLATE 4 — Validate at the door. Handle errors in one place.
Chapter 4 · Validation & error handling

Say no early, and say it consistently

// src/middleware/validate.js
const { z } = require('zod');
const taskInput = z.object({
  title: z.string().trim().min(1).max(200),
  done:  z.boolean().default(false),
}).strict();

const validate = (schema) => (req, res, next) => {
  const r = schema.safeParse(req.body);
  if (!r.success)
    return res.status(400).json({ error: { code: 'VALIDATION', issues: r.error.issues } });
  req.body = r.data;
  next();
};
// router.post('/', validate(taskInput), handler)

// src/middleware/errors.js: register LAST
class HttpError extends Error { constructor(s, m) { super(m); this.status = s; } }
app.use((err, req, res, next) => {
  const status = err.status || 500;
  if (status === 500) req.log.error({ err }, 'unhandled');
  res.status(status).json({ error: { message: status === 500 ? 'Internal error' : err.message } });
});
async errors
Express 5 forwards rejected promises; on 4 wrap handlers or use express-async-errors
idempotency
for payments and similar, accept an Idempotency-Key so retries don't double-charge
Say it like a pro

"Schema validation at the edge, typed errors, and a single handler that never leaks internals."

many requests Poolmax ~10 PostgreSQL Why a pool opening a connection is slow and the database can only hold so many reuse a handful; requests queue briefly instead of crashing the DB always release connections · set statement and pool timeouts N instances × pool size must stay under max_connections
PLATE 5 — A small shared pool serves many requests.
Chapter 5 · The database layer

Pool, parameters, and migrations

// src/db/index.js
const { Pool } = require('pg');
const { databaseUrl } = require('../config');
const pool = new Pool({ connectionString: databaseUrl, max: 10 });
module.exports = { query: (text, params) => pool.query(text, params), pool };

// src/services/tasks.js: parameters only, scoped to the user
const db = require('../db');
exports.list = async (userId, { done, limit = 20 }) => {
  const { rows } = await db.query(
    `SELECT id, title, done FROM tasks
     WHERE user_id = $1 AND ($2::boolean IS NULL OR done = $2)
     ORDER BY id DESC LIMIT $3`,
    [userId, done === undefined ? null : done === 'true', Math.min(Number(limit), 100)]);
  return rows;
};
exports.create = async (userId, { title, done }) =>
  (await db.query(
    'INSERT INTO tasks (user_id, title, done) VALUES ($1,$2,$3) RETURNING *',
    [userId, title, done])).rows[0];
-- migrations/001_tasks.sql
CREATE TABLE tasks (
  id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  user_id BIGINT NOT NULL REFERENCES users(id),
  title TEXT NOT NULL, done BOOLEAN NOT NULL DEFAULT false,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now());
CREATE INDEX ON tasks (user_id, id DESC);
Say it like a pro

"Parameterized queries, a bounded pool, every query scoped by user, and migrations in version control."

Client POST /loginbcrypt.compare email+pw JWT userspw_hash only GET /api/v1/tasksAuthorization: Bearer eyJhbGciOi… A JWT is signed, not secret header.payload.signature · anyone can read the payload don't put secrets in it · short expiry (minutes) + refresh token or use server sessions with an httpOnly cookie: simpler to revoke
PLATE 6 — Prove identity once, then carry a signed pass on every request.
Chapter 6 · Authentication & authorization

Hash passwords, sign tokens, check every request

// src/routes/auth.js
const bcrypt = require('bcrypt'), jwt = require('jsonwebtoken');
const db = require('../db'), { jwtSecret } = require('../config');

router.post('/signup', validate(creds), async (req, res) => {
  const hash = await bcrypt.hash(req.body.password, 12);
  const { rows } = await db.query(
    'INSERT INTO users (email, pw_hash) VALUES ($1,$2) RETURNING id', [req.body.email, hash]);
  res.status(201).json({ id: rows[0].id });
});

router.post('/login', validate(creds), async (req, res) => {
  const { rows } = await db.query('SELECT * FROM users WHERE email=$1', [req.body.email]);
  const u = rows[0];
  if (!u || !(await bcrypt.compare(req.body.password, u.pw_hash)))
    return res.status(401).json({ error: { message: 'Invalid credentials' } });  // same msg both ways
  res.json({ token: jwt.sign({ sub: u.id }, jwtSecret, { expiresIn: '15m' }) });
});

// src/middleware/auth.js
exports.requireAuth = (req, res, next) => {
  try {
    const t = (req.headers.authorization || '').replace('Bearer ', '');
    req.user = { id: jwt.verify(t, jwtSecret).sub };
    next();
  } catch { res.sendStatus(401); }
};
authz
every query filters by req.user.id, so users can't read each other's rows
also
rate-limit login · HTTPS only · helmet · CORS allowlist
Say it like a pro

"bcrypt hashes, short-lived tokens, a uniform login error, and ownership checks on every query."

API logs (JSON) metrics Dashboard+ alerts {"level":"info","reqId":"a1b2","method":"POST","path":"/tasks", "status":201,"ms":14,"userId":7} What to watch rate · errors · duration (p50/p95/p99) · saturation (pool, CPU, memory) log one line per request with a request ID you can follow end to end never log passwords, tokens or full card numbers /health for liveness · /ready checks the database
PLATE 7 — If you can't see it, you can't fix it at 3 a.m.
Chapter 7 · Logging & health checks

Make it observable from the first deploy

// src/app.js: structured logs with pino-http
const pino = require('pino-http')({ redact: ['req.headers.authorization'] });
app.use(pino);                          // adds req.log + a request id

app.get('/health', (req, res) => res.json({ ok: true }));        // liveness
app.get('/ready', async (req, res) => {                           // readiness
  try { await db.query('SELECT 1'); res.json({ ready: true }); }
  catch { res.status(503).json({ ready: false }); }
});

// graceful shutdown: finish in-flight requests, then exit
const server = app.listen(port);
process.on('SIGTERM', () => server.close(() => db.pool.end().then(() => process.exit(0))));
log levels
error needs action · warn odd · info normal · debug off in prod
correlation id
one ID per request, passed to downstream calls
rate limit
express-rate-limit protects login and expensive routes
Say it like a pro

"Structured logs with request IDs, liveness and readiness probes, and graceful shutdown."

Jesttest runner app (in memory)supertest test DB What to test ✔ happy path of each route ✔ bad input → 400 · no token → 401 · someone else's id → 404 ✔ business rules in services (pure functions are easy) ✔ one test per bug you fix Keep tests honest reset or roll back data between tests · no shared state real database in CI (a Postgres container) beats mocking SQL mock only the outside world: email, payments, third-party APIs
PLATE 8 — Tests run the real app, without a network or a browser.
Chapter 8 · Testing

Call your API like a client would

// test/tasks.test.js
const request = require('supertest');
const app = require('../src/app');
const db = require('../src/db');

let token;
beforeAll(async () => {
  await request(app).post('/api/v1/auth/signup').send({ email: 't@x.com', password: 'longpassword1' });
  token = (await request(app).post('/api/v1/auth/login')
            .send({ email: 't@x.com', password: 'longpassword1' })).body.token;
});
afterAll(() => db.pool.end());

test('create then list a task', async () => {
  const auth = { Authorization: `Bearer ${token}` };
  const c = await request(app).post('/api/v1/tasks').set(auth).send({ title: 'Ship it' });
  expect(c.status).toBe(201);
  const l = await request(app).get('/api/v1/tasks').set(auth);
  expect(l.body.map(t => t.title)).toContain('Ship it');
});

test('rejects missing token', async () => {
  expect((await request(app).get('/api/v1/tasks')).status).toBe(401);
});
$ npm test -- --coverage
Say it like a pro

"Integration tests over HTTP against a real test database, plus unit tests for the rules."

LB · HTTPS identical API instances Postgres Redis cache Queue Workers Scale in this order 1 index queries · 2 cache hot reads · 3 move slow work to a queue 4 add API instances (it's stateless) · 5 read replicas · 6 shard last measure first: the bottleneck is usually the database
PLATE 9 — Stateless servers scale sideways. Slow work goes to a queue.
Chapter 9 · Deploy & scale

Package it, ship it, grow it

Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY src ./src
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]
Checklist before going live
☐ config and secrets from env vars, not code       ☐ HTTPS and a reverse proxy / load balancer
☐ migrations run as a deploy step                   ☐ CORS limited to your front end's origin
☐ rate limits on login and write routes             ☐ helmet() headers, body size limit
☐ /health and /ready wired to the platform          ☐ backups of the database, restore tested
☐ logs shipped somewhere searchable + an alert      ☐ CI runs lint, tests, build, image scan
$ docker build -t my-api:1.0 . && docker run -p 3000:3000 --env-file .env my-api:1.0
cache
Redis for hot reads; set a TTL and know how you'll invalidate
queue
BullMQ / SQS: send the email later, return to the user now
next steps
OpenAPI docs, background jobs, pagination cursors, then metrics and tracing (OpenTelemetry)
Say it like a pro

"Stateless containers behind a load balancer, indexed queries, a cache for hot reads, and a queue for slow work."