Queue-North-Website/docs/architecture/README.md

Architecture — Queue North Website

Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: docs/architecture/**, server/index.js, scripts/** — the module
         boundaries, the database schema and the API response shapes
Review trigger: Any new module, any change to a module boundary or a data shape;
                any new table or column; any new external service the server
                calls; any change to how routes are prerendered

The shape of it

One Express process serves everything. There is no separate web server, no reverse proxy inside the container, and no second runtime.

browser
  |
  v
Cloudflare  ──  qn.isnull.dev
  |
  v
Express (server/index.js, port 3001)     ← the only process
  |
  +--> dist/            prerendered HTML + the React bundle, served static
  +--> /api/health      liveness, and a real SELECT against SQLite
  +--> /api/leads       POST → validate → SQLite → (fire and forget) Zoho
  +--> /api/support     POST → validate → SQLite → (fire and forget) Zoho Cases
  |
  +--> db/queuenorth.db  better-sqlite3, synchronous, single writer
  |
  +--> Google reCAPTCHA v3   verify, server-side, before any insert
  +--> Zoho CRM              WebToLead form post, or REST/OAuth as a standby

Module boundaries

src/ knows nothing about the database. It talks to three JSON endpoints through src/lib/api.js and nothing else. There is no ORM in the client, no shared schema module, and no import that crosses from src/ into server/.

server/index.js knows nothing about React. It serves dist/ as static files and falls through to dist/index.html for client routes. The one place this is not quite true is the privacy policy, below.

src/data/*.js is the content layer. Services, industries and the privacy policy text live there as plain data, imported by both the client pages and src/entry-server.jsx. Adding a service is a data edit, not a component edit.

scripts/prerender.js is a build step, not a runtime. It renders every route to static HTML at build time using src/entry-server.jsx. Nothing at request time renders React on the server.

The three boundaries worth knowing about

1. The privacy policy has two renderers, one source. src/data/privacyPolicy.js is the single source of truth; src/pages/PrivacyPolicy.jsx renders it in the SPA and the prerender step emits a static copy. This exists because Meta's crawler does not execute JavaScript, and a policy it cannot read is a policy that does not count. Do not add policy text to a component.

2. Zoho is an overlay, never a dependency. Every handler writes SQLite first and then calls the forwarder without awaiting it. A Zoho outage, a bad token or a network timeout costs a CRM record and never a lead. forwardLeadToZoho dispatches to forwardToZohoWebToLead or forwardToZoho on ZOHO_FORWARDING_MODE; both carry a 10 s AbortController.

3. reCAPTCHA is the one thing that runs before the insert. It is the only check that can reject a submission outright, so it is deliberately the only external call on the blocking path — with a 5 s timeout, and it fails open when RECAPTCHA_ENABLED is false.

Data shapes

server/index.js owns the schema and applies it at startup via initSchema(). There is no external migration runner; the one migration that exists rebuilds leads to add the UNIQUE constraint and is idempotent.

leads

Column	Type	Notes
id	INTEGER PK AUTOINCREMENT
company	TEXT NOT NULL	max 200 after sanitisation
name	TEXT NOT NULL	max 100. Split on the last space for Zoho's First_Name / Last_Name
email	TEXT NOT NULL UNIQUE	max 254 (RFC 5321). A duplicate answers 409, and the Zoho forward is still attempted — the local row existing does not mean the CRM record does
phone	TEXT
zip	TEXT	maps to Zoho Zip_Code
message	TEXT
service_interest	TEXT	normalised from empty to NULL. Maps to Zoho Description, not a custom field
created_at	DATETIME	CURRENT_TIMESTAMP

support_requests

Column	Type	Notes
id	INTEGER PK AUTOINCREMENT
name, company, email	TEXT NOT NULL	no UNIQUE — the same customer may raise many tickets
phone	TEXT
issue	TEXT NOT NULL	minimum 10 characters, enforced client and server side
priority	TEXT	defaults to medium
created_at	DATETIME	CURRENT_TIMESTAMP

The asymmetry between the two tables is deliberate. A lead is a person you want once; a support request is an event that recurs. Adding UNIQUE to support_requests.email would silently drop a customer's second ticket.

Every response shape the API produces

Status	Body	When
200	the resource, or {status, db, timestamp}	success
400	{error: 'Validation failed', fields: {…}}	Zod rejected it
403	{error}	reCAPTCHA below RECAPTCHA_MIN_SCORE
404	{error: 'Not found'}	unmatched /api/* only; other paths fall through to the SPA
409	{error}	duplicate leads.email
413	—	body over 1 MB
429	{error, message, retryAfter}	rate limiter
500	{error}	never a stack trace
503	{error, db: 'error'}	health check could not reach SQLite
504	{error: 'Request timeout'}	the 30 s request timeout fired

Documents here

• GUARDS.md — how to write a check that actually checks. Read it before adding a structural test or a probe; every rule in it was learned from a guard that had been green over something broken.
• zoho-setup.md — the CRM integration end to end: app setup, credentials, environment variables, and how to confirm a lead arrived.

What ships in scripts/

Ten scripts came from the template on 2026-08-18 and three were already here. The template's full catalogue is a menu, not an inventory — see ../TOOLS.md. This table is what this project actually has, and each row says what it does here.

Path	What it is
scripts/check-env.sh	which of the 17 Zoho / reCAPTCHA / CORS / rate-limit variables are set and plausible, before the server reads them. Exit 2 means nothing was checked
scripts/secrets.sh	credential shapes in a staged diff, and --tracked for a whole-tree audit. --built dist/ is the one that matters here: VITE_RECAPTCHA_SITE_KEY is inlined into the bundle at build time, so the repository scan cannot see what users receive
scripts/verify.sh	every check this project has, in one table. Honestly thin — there is no test suite, and it says so rather than printing a green row
scripts/doc-triggers.py	which documents a pending change fires, read from the Governs: headers. Run it before committing, not after
scripts/forgejo-issue.py	files and closes issues in the tracker convention, refusing malformed ones before they are filed
scripts/status.sh	what is running on nebula as qn-website-dev, its version and its restart count. Read-only
scripts/healthcheck.sh	a liveness tick against qn.isnull.dev, asserting HTTP 200 and "status":"ok" — a 503 with a JSON body is a real answer, not an outage
scripts/preflight.sh	headers and TLS against the live origin. No --auth checks: there are no accounts
scripts/backup.sh	a verified SQLite dump. Its ENGINE block was rewritten for better-sqlite3's online .backup() — see below
scripts/restore-check.sh	restores the newest dump into a scratch file, runs PRAGMA integrity_check, counts tables, and times it. A backup nobody has restored is a guess
scripts/docker-push.sh	builds and pushes queue-north-website:dev to the Forgejo registry. Predates the template
scripts/docker-test.sh	builds the image and runs it locally on 3001. Predates the template
scripts/prerender.js	the build step that emits static HTML for every route. Predates the template

Why backup.sh and restore-check.sh are not the template's originals. Both ship as PostgreSQL tools. backup.sh is built to be adapted — everything engine-specific is in one ENGINE block — so that block now calls better-sqlite3's .backup() inside the running container and verifies the result with sqlite3 before renaming it into place. restore-check.sh had no such seam: it is pg_restore and psql end to end, so the SQLite version is a rewrite that keeps the argument and replaces the mechanism.

What does not belong here

• Product intent — that is docs/planning/PROJECT_PLAN.md
• Engineering standards and the stack policy — that is docs/planning/REQUIREMENTS.md
• What it should look and sound like — that is docs/design/
• What happened while building it — that is docs/history/

A note on drift

Architecture docs go stale faster than any other kind, because code changes under them silently. This is exactly what the Review trigger line is for: name the change that should send somebody back here, and a reader can tell whether the trigger has fired.

The specific instance to avoid in this repository: BUILD_SUMMARY.md carried a copy of the SQL schema that predated the UNIQUE constraint on leads.email. It was not carried forward on adoption. server/index.js owns the schema; the tables above describe it and do not duplicate it.