nonobie — Real dev skills, explained like a friend would

What you'll build

By the end of this project you will have shipped:

A Node + Express + Prisma + Postgres
Two resources: /notes and /todos
with Zod, structured errors, request IDs, structured logging
A README, an OpenAPI spec, and a Postman collection

Why this project

Reading 10 chapters teaches you the words. Building one project teaches you the language. This is the bar for "I am a backend engineer" — not a senior one yet, but a real one.

This project applies every L1 chapter:

Chapter 1–2 — what backend is, environment.
Chapter 3 — vanilla HTTP (we'll use Express now).
Chapter 4 — routing.
Chapter 5 — .
Chapter 6 — / design.
Chapter 7 — validation + errors.
Chapter 8–10 — env vars, logging, testing (preview).

You should be able to finish this in 4–8 hours of focused work.

Spec — what we're building

Two resources:

`/notes` (we built a stub in chapter 6)

title (required, 1–200)
body (optional, ≤10,000)
tags (optional, ≤20)

`/todos`

title (required, 1–200)
done (boolean, defaults false)
dueDate (optional ISO date)
noteId (optional — linked to a note)

Endpoints

plaintext

POST    /api/v1/notes           201 + Location
GET     /api/v1/notes           200 (paginated, filterable by ?tag, ?q)
GET     /api/v1/notes/:id       200 / 404
PATCH   /api/v1/notes/:id       200 / 404 / 422
DELETE  /api/v1/notes/:id       204 / 404
 
POST    /api/v1/todos           201 + Location
GET     /api/v1/todos           200 (paginated, filterable by ?done, ?noteId)
GET     /api/v1/todos/:id       200 / 404
PATCH   /api/v1/todos/:id       200 / 404 / 422
DELETE  /api/v1/todos/:id       204 / 404

Cross-cutting

All requests get a X-Request-Id (echoed in response).
Validation errors return 422 with issues.
500s return { error, requestId } — no .
GET /health returns { status: 'ok' }.

Project layout

plaintext

notes-todo-api/
├── prisma/
│   └── schema.prisma
├── src/
│   ├── server.ts            # bootstrap (express + listen)
│   ├── app.ts               # express setup + middleware
│   ├── config.ts            # env vars (validated)
│   ├── lib/
│   │   ├── prisma.ts        # PrismaClient singleton
│   │   ├── logger.ts        # pino logger
│   │   └── error.ts         # ApiError class
│   ├── middleware/
│   │   ├── requestId.ts
│   │   ├── validate.ts
│   │   ├── asyncHandler.ts
│   │   └── errorHandler.ts
│   ├── modules/
│   │   ├── notes/
│   │   │   ├── notes.routes.ts
│   │   │   ├── notes.service.ts
│   │   │   ├── notes.schemas.ts
│   │   │   └── notes.test.ts
│   │   └── todos/
│   │       ├── todos.routes.ts
│   │       ├── todos.service.ts
│   │       ├── todos.schemas.ts
│   │       └── todos.test.ts
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Three-layer per resource: routes → service → DB. The route validates, the service holds business logic, the DB layer (Prisma) reads/writes.

Step-by-step build

1. Init

bash

mkdir notes-todo-api && cd notes-todo-api
npm init -y
npm install express zod pino pino-http prisma @prisma/client dotenv
npm install -D typescript tsx @types/express @types/node vitest supertest @types/supertest
npx tsc --init
npx prisma init --datasource-provider postgresql

Set up package.json scripts:

json

{
  "scripts": {
    "dev": "tsx watch src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js",
    "test": "vitest",
    "migrate:dev": "prisma migrate dev

2. Postgres in Docker

docker-compose.yml

yaml

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: secret
      POSTGRES_DB: notes_todo
    ports: ["5432:5432"]
    volumes: [pgdata:/var/lib/postgresql/data]
volumes: { pgdata: {} }

bash

docker compose up -d

3. Prisma schema

prisma/schema.prisma

prisma

generator client { provider = "prisma-client-js" }
datasource db { provider = "postgresql"; url = env("DATABASE_URL") }
 
model Note {
  id        String   @id @default(uuid())
  title     String
  body      String   @default("")
  tags      String

bash

echo 'DATABASE_URL="postgresql://postgres:secret@localhost:5432/notes_todo"' > .env
npm run migrate:dev -- --name init

4. Express app skeleton

src/app.ts

import express from 'express';
import helmet from 'helmet';
import cors from 'cors';
import pinoHttp from 'pino-http';
import { logger } from './lib/logger';
import

src/server.ts

import { buildApp } from './app';
import { logger } from './lib/logger';
 
const PORT = process.env.PORT || 3000;
const app = buildApp();
const

5. The Notes module

src/modules/notes/notes.schemas.ts

import { z } from 'zod';
 
export const createNote = z.object({
  title: z.string().min(1).max(200),
  body: z.

src/modules/notes/notes.service.ts

import { prisma } from '../../lib/prisma';
import { ApiError } from '../../lib/error';
 
export const notesService = {
  async create(data) { return prisma.note.create({

src/modules/notes/notes.routes.ts

import { Router } from 'express';
import { validate } from '../../middleware/validate';
import { asyncHandler } from '../../middleware/asyncHandler';
import { createNote, updateNote, listNotesQuery, idParam

6. The Todos module

Same shape, swap fields. Add done filter:

export const listTodosQuery = z.object({
  done: z.enum(['true','false']).transform(v => v === 'true').optional(),
  noteId: z

7. A test

src/modules/notes/notes.test.ts

import { describe, it, expect } from 'vitest';
import request from 'supertest';
import { buildApp } from '../../app';
 
const app = buildApp();
 
describe

Run: npm test.

8. Try it

bash

npm run dev
 
# Create
curl -X POST http://localhost:3000/api/v1/notes \
  -H "Content-Type: application/json" \
  -d '{"title":"Buy milk","tags":["grocery"]}'
 
# List
curl http://localhost:3000/api/v1/notes

Deliverables checklist

All 10 endpoints implemented (notes + todos × CRUD).
Validation with Zod, returning 422 + issues.
One global error handler.
Request IDs in every response.
Structured logs (pino).
Postgres migrations checked in.
At least 3 tests per module.
A README that explains how to run the project.
An .http file with example requests.

Extensions (optional but instructive)

Add ?tag=... filter using Prisma's tags: { has: tag }.
Add a GET /api/v1/notes/:id/todos endpoint that returns linked todos.
Add a soft-delete (deletedAt).
Write an OpenAPI spec by hand or use zod-to-openapi.
Deploy to fly.io and put the live URL in your README.

Common pitfalls

N+1 queries when listing notes with todos. Use include in Prisma.
Forgetting to await inside route handlers — silent hangs. Always await services.
Validating in the route but not the service. If you skip the route validator (e.g. in tests), bad data slips through. Defensive: validate at the boundary, trust downstream.
Returning the password / sensitive fields. Even though notes have none here, get in the habit of explicit field selection.

What you have at the end

A small but real backend. Postgres-backed. Validated. Logged. Tested. Containerized.

This is what every API at every SaaS looks like under the hood. The next levels (L2–L7) just expand on this template: more sophistication in DB design, security, scale, deployment, and AI.

If this clicked — you're a backend engineer. Welcome.

Summary

A two-resource, Postgres-backed Express API with validation, error handling, structured logging, and tests. The same shape powers nearly every SaaS product. Once you've built it, every concept in L2–L7 has somewhere familiar to land.

Project P1 — Notes & Todo API

Why this project

Spec — what we're building

/notes (we built a stub in chapter 6)

/todos

Endpoints

Cross-cutting

Project layout

Step-by-step build

1. Init

2. Postgres in Docker

3. Prisma schema

4. Express app skeleton

5. The Notes module

6. The Todos module

7. A test

8. Try it

Deliverables checklist

Extensions (optional but instructive)

Common pitfalls

What you have at the end

Summary

`/notes` (we built a stub in chapter 6)

`/todos`