Architecture handbook

How this site is built, written down properly.

Thirty-four thousand words on a Next.js and Firestore application with no server between the browser and the database. Written to be studied in three sittings, and to be searched forever after.

29
documents
~3 h
cover to cover
15
diagrams
229
source files indexed

Read it in the reader, not on GitHub

The handbook ships with its own reader: full-text search across every section, a command palette, the source of all 229 indexed files with line-level links back into the prose, a link graph, and definitions on hover. It works offline once loaded.

Open the handbook→

Session 1 — orientation

45 min

Know what the system does and how it is shaped. Includes getting it running locally, which makes every later document mean more.

  1. Overview & PurposeWhat the app is, who uses it, the four primary flows, the directory map.9 min
  2. System ArchitectureThe client/server split, why every page is force-dynamic, and the trade-offs behind it.14 min

Session 2 — the data spine

40 min

Where data lives, who may touch it, how it moves. The most valuable session in the handbook — if you only ever read one, read this one.

  1. Data ModelEleven collections, their fields, and every clause of the security rules.13 min
  2. Data FlowThe four distinct paths: read, write, realtime, and privileged write.10 min
  3. Cross-Cutting ConcernsAuthentication and authorization in full, including the bridge and its state machine.14 min

Session 3 — the request

35 min

Trace one request end to end, by function name. After this you are productive; everything else is consulted, not studied.

  1. The Processing CycleOne scenario — a member likes a comment — followed from the edge to the re-render.10 min
  2. API ReferenceAll seven endpoints. Skim it; return when you need one.10 min
  3. Client Architecture, State & RoutingState (there is no state library), routing, SEO, accessibility.10 min

Reference

on demand

Not to be read front to back. Look things up in them — the reader's search and command palette exist for exactly this.

  1. Code-Level ReferenceA function's exact signature, its side effects, and its callers.20 min
  2. Build, Test, Run & DeployScripts, tests, deployment. Read the seeding section before running npm run seed — it is destructive.15 min
  3. Known Gaps & Open QuestionsSomething looks wrong? It may already be known. Worth ten minutes early.11 min
  4. Reverse IndexYou have a symbol name and want its location.11 min
  5. GlossaryA term of art is unfamiliar.8 min

Deep dives

as needed

Self-contained. Read one only when you are assigned work inside it.

  1. Component & Package ArchitectureThe component tree, and the Code Observatory's four-stage pipeline.9 min
  2. Module Design & CompositionHow the lib modules compose, and where the seams are.9 min
  3. Mathematical FoundationThe ranking score, exponential freshness decay, log-compressed node weighting, golden-angle phyllotaxis.15 min
  4. Reading Path — Start HereThe full path, with checkpoints to test your understanding and code to read alongside each document.13 min