Goodreads

// Problem

The catalogue had to survive a typo. Of six common misspellings, four returned nothing at all from the source data, and adding a search cluster for 9,021 books would have been a second system to run, deploy and keep in sync.

// Decision

Hybrid search inside PostgreSQL: full text first, trigram similarity as a fallback, and a prefix path for very short queries. No Elasticsearch.

// Implementation

An ISBN is detected and looked up exactly, because full text can never match it. Otherwise a tsvector index answers exact, partial, author, punctuation and accent queries. When that returns nothing the query is retried: under about five characters against a prefix index, and otherwise against a pg_trgm similarity index at an explicit low threshold. Normalisation (lowercase, accents, typographic apostrophes) happens in generated columns, so the database owns it and the query cannot forget it.

// Result

Verified against PostgreSQL 17.11: full text 0.083 ms, trigram 3.689 ms at 10,488 rows, and all four typos the source data missed return the right book first. A recovered query comes back with the text it corrected from, so the interface says 'showing results for a close match to…' instead of silently changing what was asked.

// Problem

The catalogue comes from Open Library, and the obvious build calls it per request. The spike measured a 2.17 s median for a single cover fetch, and the API asks callers to identify themselves and stay under a rate limit, neither belongs in a page load.

// Decision

Ingest the catalogue offline into our own PostgreSQL, and serve nothing from anyone else's API at request time.

// Implementation

A resumable, idempotent pipeline: harvest, filter, select, hydrate, normalise, map genres, fetch covers, validate, upsert. Every raw response is written to disk before anything touches it, so a re-run replays instead of re-fetching. API calls are serialised through one lock at one request per 350 ms with the contact address in the User-Agent; cover downloads take a separate path, eight threads with a 40 ms floor, because they are latency-bound rather than rate-bound. Quality gates are absolute, a title, an author, English, a real cover that downloads, 40–2000 pages, a mapped genre, and every rejection is counted by reason.

// Result

9,021 books with their authors, genres and three cover derivatives each, held entirely by us. Serving a reader never leaves our own infrastructure, and a book with no cover is rejected rather than shown with a hole in it.

// Problem

Book data is published per edition. Grouping them under a canonical work was the plan, an edition picker under each book, and the fallback for missing page counts was to recover them from an edition that had one.

// Decision

One Open Library work is one book row, with the primary edition's fields denormalised onto it. No edition table, no picker.

// Implementation

The measurement killed the fallback before it was built: page-count recovery from editions was 0 of 35, because the work-level figure is derived from editions in the first place, when it is absent, no edition has one. Edition-level completeness is worse than work level, and physical_format is free text with 29 distinct values across 835 records.

// Result

The duplicate-results problem disappears rather than being solved: the source returns works, so nothing ever fans out. book.source_key remains the join point if editions are ever worth adding, and the catalogue's own numbers say what would have to change first.

// Problem

A reader's library is private, the deployment target scales to zero, and a self-contained token cannot be revoked before it expires.

// Decision

Server-side sessions in PostgreSQL behind an opaque HttpOnly cookie. No JWT, nothing in localStorage, and CSRF protection on everything, including login.

// Implementation

Spring Session JDBC keeps sessions in the database that is already running, so a cold start does not sign every reader out and no Redis joins the stack. Passwords are hashed with Argon2id under a length-only policy. The session id and the CSRF token are both rotated on login, against fixation. CSRF is cookie-to-header: a cross-origin attacker can cause the cookie to be sent but cannot read it, so cannot produce the header. Exempting login is common and wrong, login-CSRF signs a victim into the attacker's account, so nothing is exempt. A wrong password and an unknown account return byte-identical responses.

// Result

The whole authentication loop is covered end to end on desktop and mobile viewports, including hostile returnTo targets and keyboard-only completion. The demo reader signs in with no password at all: the server authenticates a known identity whose stored hash no submitted password can produce, so a shared credential never exists to leak.

// Problem

The frontend is on Vercel and the API is on another host. Left alone that makes every authenticated request cross-site, and a SameSite=Lax cookie is simply not sent on a cross-site XHR. Reaching for SameSite=None turns the session into a third-party cookie, which browsers increasingly refuse outright.

// Decision

The browser never addresses the API host. It calls /api/v1/… and /covers/… on the frontend's own origin, and Next.js rewrites those to the API.

// Implementation

Two rewrite rules and one server-only environment variable. Nothing about the API is NEXT_PUBLIC_, deliberately: a NEXT_PUBLIC_ value is compiled into the browser bundle, and exposing the API host there is exactly what makes the cookie third-party. Server Components bypass the proxy and call the API origin directly, because a server calling its own public URL would loop back through the edge for nothing.

// Result

The session cookie is first-party, the CSRF cookie is readable by our own JavaScript because it is our own origin, and there is no CORS preflight on credentialed requests at all. Local development uses the same path, so what is tested is what ships. It is routing, not a second backend: the rewrite forwards bytes and has no request handler behind it.