The App-Building Picture Book
1 Plan 2 Design 3 Build 4 Test 5 Ship 6 Observe your app, version n+1
PLATE 0 — An app is never finished. It goes around this loop again and again.
A picture book for grown-ups · with code

How Apps Get Built, from Idea to Production

Nine spreads. Each has a picture, the idea, and the commands or code you'd use. It's language-neutral, with small examples in JavaScript, SQL, and shell.

Say it like a pro

"We scoped the smallest useful version, modeled the data, built the API and UI, tested it, shipped through CI, and watch it in production."

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

User story As a shopper, I want to save items to a list, so that I can buy them later. Done when… □ add / remove item □ list survives reload □ works on phone Must havesign up · list · checkout Laterwishlists · sharing · badges MVP · ship in weeks
PLATE 1 — Decide what it must do first, and say what it won't do yet.
Chapter 1 · Plan

Start with the problem, not the framework

Most failed apps solved a problem nobody had. Write down who the user is, what they're trying to do, and how you'll know it works, before choosing any tools.

  1. Name the user and their one painful task.
  2. Write user stories with acceptance criteria.
  3. Split into must have and later. Ship the smallest useful version (MVP).
  4. Sketch screens on paper or in Figma. It's cheaper to erase a line than a feature.
functional
what it does: "user can reset a password"
non-functional
how well: fast, secure, accessible, available
scope creep
features sneaking in unplanned. Say no, or trade something out.
Say it like a pro

"What's the smallest thing a real user would pay for or use daily?"

Clientweb · mobile API serverrules · auth Database Cache · Redis Worker Start as one deployable ("monolith") split into services only when team or scale truly forces it
PLATE 2 — Client asks, server decides, database remembers.
Chapter 2 · Architecture

Who does what, and where the data lives

Keep responsibilities apart: the client shows things, the server enforces rules, the database stores truth. Never trust the client for security checks.

PieceJobCommon picks
ClientUI, inputReact, Vue, Swift, Kotlin
Serverlogic, auth, APINode, Python, Go, Java
Databasedurable dataPostgreSQL, MySQL, SQLite
Cachefast repeatsRedis
Queue/workerslow jobs: emails, reportsBullMQ, Celery
stateless
servers keep nothing between requests, so you can run many copies
monolith
one codebase and deploy. Simple, and right for most starts.
Say it like a pro

"Boring tech, a single deployable, and a clean boundary between the UI and the API."

usersid (PK)emailpw_hash ordersid (PK)user_id (FK)created_at productsid (PK)nameprice_cents 1:N order_itemsorder_id (FK)product_id (FK) PK identifies a row · FK points at another table · index = fast lookup
PLATE 3 — Tables are nouns. Foreign keys are the relationships between them.
Chapter 3 · Data

Model the nouns, then keep them consistent

List the things your app knows about, and how they relate. A relational database enforces those rules for you.

CREATE TABLE users (
  id         SERIAL PRIMARY KEY,
  email      TEXT UNIQUE NOT NULL,
  pw_hash    TEXT NOT NULL
);
CREATE TABLE orders (
  id         SERIAL PRIMARY KEY,
  user_id    INT NOT NULL REFERENCES users(id),
  created_at TIMESTAMPTZ DEFAULT now()
);
CREATE INDEX ON orders (user_id);

SELECT u.email, count(o.id) AS orders
FROM users u LEFT JOIN orders o ON o.user_id = u.id
GROUP BY u.email ORDER BY orders DESC;
migration
a versioned script that changes the schema, so every environment matches
money
store integer cents, never floats
transaction
all-or-nothing group of writes
Say it like a pro

"Constraints in the database, migrations in git, and an index on every foreign key I query by."

Request POST /api/orders Authorization: Bearer … Content-Type: application/json {"productId": 7, "qty": 2} Response 201 Created Content-Type: application/json {"id": 91, "total": 2400} 2xx ok 3xx moved 4xx your bad 5xx our bad verbs: GET read · POST create · PUT/PATCH change · DELETE remove
PLATE 4 — An API is a contract: send this, get that.
Chapter 4 · The API

Endpoints: the doors into your app

// Node + Express
const app = require('express')();
app.use(require('express').json());

app.post('/api/orders', requireAuth, async (req, res) => {
  const { productId, qty } = req.body;
  if (!Number.isInteger(qty) || qty < 1)
    return res.status(400).json({ error: 'qty must be >= 1' });
  const order = await db.createOrder(req.user.id, productId, qty);
  res.status(201).json(order);
});
app.listen(3000);
$ curl -s -X POST localhost:3000/api/orders \
    -H 'Authorization: Bearer $TOKEN' -H 'Content-Type: application/json' \
    -d '{"productId":7,"qty":2}'
validate
every input, on the server, always
idempotent
repeating it is safe (GET, PUT, DELETE)
version
/v1/…, so you can change without breaking clients
Say it like a pro

"Nouns in the path, verbs in the method, honest status codes, validated input."

<App> state <Header> <TodoList> <Item> <Item> props ↓ events ↑ Every screen has four statesloading · empty · error · success. Design all four.
PLATE 5 — A screen is a tree of small parts. Data flows down, events flow up.
Chapter 5 · The frontend

Components, state, and talking to the API

// React
function TodoList() {
  const [items, setItems] = useState([]);
  const [status, setStatus] = useState('loading');

  useEffect(() => {
    fetch('/api/todos')
      .then(r => r.ok ? r.json() : Promise.reject(r.status))
      .then(d => { setItems(d); setStatus('ok'); })
      .catch(() => setStatus('error'));
  }, []);

  if (status === 'loading') return <p>Loading…</p>;
  if (status === 'error')   return <p>Couldn't load. Retry?</p>;
  if (!items.length)        return <p>Nothing yet.</p>;
  return <ul>{items.map(i => <li key={i.id}>{i.text}</li>)}</ul>;
}
responsive
design for a phone first, then widen
a11y
labels, keyboard focus, contrast: usable by everyone
never trust
hiding a button isn't security; the server must check
Say it like a pro

"State lives in one place, the UI is a function of it, and every fetch handles loading and failure."

User Serververify hash token 1 login 2 issue 3 sent with every request The short list that stops most breaches hash passwords (argon2/bcrypt) · HTTPS only · parameterized SQL authorize every request server-side · escape output (XSS) secrets in env vars, never in git · rate-limit logins keep dependencies patched · least privilege everywhere
PLATE 6 — Authentication asks "who are you?" Authorization asks "may you?"
Chapter 6 · Auth & security

Prove who they are, then check what they may do

const bcrypt = require('bcrypt');

// signup: store only the hash
const pw_hash = await bcrypt.hash(password, 12);

// login: compare, then issue a session
const ok = await bcrypt.compare(password, user.pw_hash);
if (!ok) return res.status(401).json({ error: 'bad credentials' });

// authorization: is this order theirs?
if (order.user_id !== req.user.id) return res.sendStatus(403);

// SQL: parameters, never string concatenation
db.query('SELECT * FROM users WHERE email = $1', [email]);
401 vs 403
401: not logged in · 403: logged in but not allowed
.env
config and secrets live here; add it to .gitignore
OAuth
"Sign in with Google": let someone else handle passwords
Say it like a pro

"Hashed passwords, HTTPS, parameterized queries, and an authorization check on every endpoint."

E2E Integration Unit few · slow · whole app many · fast · one function A red test is information, not an insultwrite one for every bug you fix so it never returns
PLATE 7 — Lots of small fast tests, a few big slow ones.
Chapter 7 · Testing

Make change safe

Tests let you change code without fear. They also document what the code is meant to do.

// total.test.js  (Jest)
const { orderTotal } = require('./total');

test('adds line items in cents', () => {
  expect(orderTotal([{ cents: 1200, qty: 2 }])).toBe(2400);
});
test('empty cart is zero', () => {
  expect(orderTotal([])).toBe(0);
});
test('rejects negative quantity', () => {
  expect(() => orderTotal([{ cents: 100, qty: -1 }])).toThrow();
});
$ npm test                  # run everything
$ npm test -- --watch       # rerun on save
$ npm test -- --coverage    # what's untested?
arrange-act-assert
set up, do the thing, check the result
mock
fake the slow or external parts (email, payment)
Say it like a pro

"The bug gets a failing test first, then the fix, so it stays fixed."

main feature/wishlist PR merged lint test build deploy red at any step → stop. Nothing broken reaches users. CI = integrate often · CD = deliver automatically
PLATE 8 — Small changes, checked by a robot before anyone sees them.
Chapter 8 · Git & CI/CD

Ship small, ship often, let the pipeline check

$ git switch -c feature/wishlist
$ git add -A && git commit -m "Add wishlist endpoint"
$ git push -u origin feature/wishlist
# open a pull request, get a review, merge to main
.github/workflows/ci.yml
name: ci
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run lint
      - run: npm test
      - run: npm run build
.gitignore
node_modules, .env, build output
review
a second pair of eyes catches what tests can't
Say it like a pro

"Trunk-based, short-lived branches, required checks on main, auto-deploy on green."

Imageapp + deps Load balancerHTTPS Logs · Metrics · Traceswhat is it doing? Alert → on-call rollback plan ready before every deploy
PLATE 9 — Shipping isn't the end. Watching it run is half the job.
Chapter 9 · Deploy & observe

Package it, run it, watch it

Dockerfile
FROM node:20-slim
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
EXPOSE 3000
USER node
CMD ["node", "server.js"]
$ docker build -t myapp:1.0 .
$ docker run -d -p 3000:3000 --env-file .env --name myapp myapp:1.0
$ docker logs -f myapp
$ curl -f localhost:3000/health || echo "unhealthy"
12-factor
config in env vars, logs to stdout, stateless processes
health check
a cheap endpoint the platform pings
rollback
redeploy the last good image in one command
SLO
a target like "99.9% of requests under 500 ms"
Say it like a pro

"Immutable image, config from the environment, health checks, and a one-step rollback."