The Programmers Guide to the Galaxy

A reference on production systems.

224 entries. Each one covers what a thing is, how it works, and how it fails.

---

What this is

A short reference covering the parts of a production system that people are expected to know and rarely get taught directly: caching, replication, retries, deployment, observability, and the rest.

Every entry is two paragraphs. The first states what the thing is and how it works. The second covers how it fails, what the tradeoffs are, and which decisions are hard to reverse later.

Entries are self-contained. Nothing refers back to an earlier entry, so you can read one in isolation and stop there. That makes the guide usable as a lookup during an incident rather than as a book you work through in order.

The title is a reference to Douglas Adams. The content is not a parody.

Screenshots

Reader: snap-scrolling, one entry per screen

Search: full text, across titles and body copy

Responsive down to small screens

Features

• 224 entries across 21 categories, from rate limiting to CAP theorem to postmortems
• Random entry: press r to jump to one at random
• Full-text search over titles and body text, on / or Ctrl/Cmd+K
• Snap reader: one entry per viewport, keyboard navigable, with a draggable position rail
• Category filter to narrow the index to a single domain
• Resumes at the last entry read, stored in localStorage
• No backend. A static single-page app that runs on any file host
• Honors prefers-reduced-motion by skipping the transition animation
• Accessible: semantic landmarks, an ARIA slider on the rail, 44px minimum touch targets

Keyboard shortcuts

Key	Action
r	Open a random entry
/ or Ctrl/Cmd+K	Open search
j / ↓ / n	Next entry
k / ↑ / p	Previous entry
Home / End	First or last entry
i or Backspace	Return to the index
Esc	Close search, or leave the reader

Quick start

Requires Node.js 20.19+ or 22.12+.

git clone https://github.com/your-username/programmers-guide.git
cd programmers-guide
npm install
npm run dev

The dev server starts on http://localhost:5173 and opens your browser.

Scripts

Command	What it does
npm run dev	Start the dev server with hot module replacement
npm run build	Typecheck, then build to dist/
npm run preview	Serve the production build locally
npm run typecheck	Run tsc --noEmit
npm run lint	Run ESLint
npm run format	Format with Prettier

Project structure

programmers-guide/
├── index.html              # Vite entry: meta tags, font preconnects
├── vite.config.ts          # React and Tailwind plugins, @/ alias
├── src/
│   ├── main.tsx            # Mounts <FieldIndex />, which is the whole app
│   ├── styles.css          # Tailwind v4 @theme tokens and custom animations
│   ├── components/
│   │   ├── field-index.tsx   # Index, reader, and random jump
│   │   ├── search-overlay.tsx
│   │   ├── tick-rail.tsx     # Draggable rail marked at category boundaries
│   │   └── odometer.tsx      # Rolling-digit entry counter
│   ├── data/
│   │   ├── types.ts          # Category union, Topic type, slugify()
│   │   ├── topics.ts         # Flattens batches, assigns numbers and ids
│   │   └── batch-{a..f}.ts   # The 224 entries
│   └── lib/utils.ts        # cn(), wrapping clsx and tailwind-merge
└── public/                 # favicon, og image

Entry numbers (001 to 224) and URL-safe ids are derived at load time in src/data/topics.ts from array order. They are never written by hand. Insert an entry in the middle and everything after it renumbers automatically.

The categories

Category	Entries	Category	Entries
Security	28	Platform	11
Data	24	Survive	10
Runtime	19	Observe	9
Release	18	HTTP	9
Contracts	15	Consistency	8
Culture	14	Wire	7
Architecture	14	Messaging	7
Infra	7	Traffic	5
Resilience	5	Speed	4
Ship	4	Realtime	3
Edge	3	Total	224

Adding an entry

1. Open any src/data/batch-*.ts and add a TopicDraft object:

{
  title: "Backpressure",
  category: "Resilience",
  p1: "What it is and how it works.",
  p2: "How it fails and what the tradeoffs are.",
}

2. category must be one of the values in CATEGORIES. TypeScript rejects anything else.
3. Run npm run typecheck. The number, id, and index placement are automatic.

Writing style

Entries follow ASD-STE100 Simplified Technical English where it helps, and plain descriptive prose where a strict reading of it would not. The aim is text that a tired reader can parse correctly on the first pass.

Structure

• Two paragraphs, roughly 60 to 90 words each.
• First paragraph: what the thing is and how it works.
• Second paragraph: how it fails, the tradeoffs, and which choices are costly to reverse.

Sentences

• Keep sentences under 25 words. The current average is about 16.
• One idea per sentence.
• Use active voice and the present tense.
• Use the same term for the same concept every time. Do not introduce synonyms for variety.

Words

• Define a term before you rely on it.
• Prefer the specific to the general: status codes, header names, flags, algorithm names.
• No metaphor or analogy standing in for a description.
• No em dashes. Use a period, a colon, or a comma.
• No intensifiers, hyperbole, or jokes at the reader's expense.

Correctness comes before concision. If a sentence has to run long to stay accurate, let it run long.

Deployment

npm run build produces a static dist/. There is no server, no database, and no runtime environment variables, so any static host works.

Coolify

The repo includes a Dockerfile and nginx.conf. Use the Dockerfile build pack, which pins the Node and nginx versions instead of letting autodetection choose them.

Setting	Value
Build Pack	Dockerfile
Dockerfile Location	/Dockerfile
Base Directory	/
Ports Exposes	80
Health Check Path	/

Nothing else needs setting. The image builds the site and serves it from nginx, so no start command, port mapping, or persistent storage is required.

To use Nixpacks instead of the Dockerfile, set Build Pack to Nixpacks, enable the static site option, set the build command to npm run build, and set the publish directory to dist. Nixpacks reads the engines.node field in package.json to pick a Node version, so keep that field accurate.

One thing to set after the first deploy: og:image in index.html is a relative path. Most link preview scrapers require an absolute URL, so change it to your full domain once you know it, and add a matching og:url.

Other hosts

Vercel, Netlify, Cloudflare Pages

Build command npm run build, output directory dist. Framework preset Vite where one is offered.

GitHub Pages

Set base in vite.config.ts to "/<repo-name>/", then publish dist/ to the gh-pages branch.

Contributing

Contributions are welcome, particularly new entries and corrections to existing ones.

1. Fork and branch: git checkout -b entry/backpressure
2. Add or edit entries in src/data/batch-*.ts
3. Run npm run typecheck && npm run lint && npm run format
4. Open a pull request describing what you added and why it belongs

Useful contributions include a topic a working engineer would search for and not find, a correction where an entry is wrong or out of date, and a second paragraph that names a failure mode the current text misses.

Please do not submit product marketing, or entries padded to reach a length.

License

MIT, covering the code and the entry text alike.

Use it, change it, ship it, and no attribution is required. Forking the guide and taking it somewhere else is a fine outcome.

Acknowledgements

The title refers to The Hitchhiker's Guide to the Galaxy by Douglas Adams.

_{001 to 224}