17 KiB

Raw Blame History

Architecture — Queue North Website

Status: Current
Owner: _null
Last reviewed: 2026-08-18
Governs: docs/architecture/**, server/index.js, scripts/**, src/data/** — the
         module boundaries, the content layer, 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
  |
  +── queuenorth.com ──► nginx-proxy-manager (thor/exodus)  ┐   PRODUCTION
  |                                                          │
  +── qn.isnull.dev ───► Cloudflare ─────────────────────────┤
                                                             v
Express (server/index.js, port 3001) on nebula   ← the only process, one instance
  |
  +--> 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.

A service may carry a page object: owner-approved long-form copy, in src/data/serviceContent/<slug>.js, shaped as { seo, hero, sections, related } where each section is { id, title, kind?, blocks } and a block is one of p, h3, ul, ol, callout, image or links. A service without one keeps the short layout, so the two shapes coexist. Content files are leaf modules: they import nothing, because services.js imports them and the prerenderer imports that directly in Node, where Vite's resolution does not exist.

scripts/lib/content.js decides whether that data is publishable, and the build refuses when it is not. It is the only thing standing between the copy sheets' directions to the website manager ("Place an official screenshot", "Keep this factual:") and a customer-facing page, since those lines look exactly like copy. It also holds the rules that make a page quotable: a section opens with its direct answer, ids start with a letter and are unique, every link resolves, and no em dash, markdown or HTML tag survives into a string.

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.

It refuses to produce a page rather than produce a wrong one, and each refusal names its route:

a render that throws, so the build does not report a stack trace with no clue which of the nineteen pages produced it
a Suspense fallback (), because renderToString does not wait: a lazy import anywhere above a route would silently ship an empty page to every crawler
a template that already carries a canonical, which means the script is being run over its own output, since dist/index.html is both template and home page
content that does not hold together, checked by scripts/lib/content.js before a single page renders
a route the router declares that this build would not produce, which the server would answer with 404.html

Rules about what it moves, each bought with a defect:

Metadata React leaves inline is hoisted into <head>, except inside an inline <svg> (an SVG <title> labels a picture, not the page) and except <meta itemprop> microdata, which belongs beside the thing it describes.
JSON-LD is never hoisted. React hoists only async scripts with a src, so on the client the ld+json script stays in the body where its component renders it. Moving it to <head> made the prerendered DOM disagree with the client's first render, and React responded by discarding the whole prerendered page and re-rendering it, on every page, for months. Structured data is valid anywhere in the document.
The hero preload is keyed on the image React marked with a high fetch priority. Keying it on loading="eager" matched the header logo, so every page preloaded the logo and no page preloaded its own hero.

Hydration is real again, and it is measurable. Anything rendered only on the client, such as sonner's <Toaster>, mounts after hydration; rendering it in the first client pass puts a node in the tree that the prerendered HTML never had, which is a mismatch, and a mismatch costs the entire prerendered page.

The three boundaries worth knowing about

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.
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.
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. `npm run verify` runs both, as guard `20-secrets`. Every pattern is compiled before the scan, because a pattern grep cannot read produces the same silence as a clean tree (#235). A line that must show a credential shape carries `secrets-ok:` and its reason. Carries this project's own shapes, and one tightened pattern, described below
`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/validate-content.js`	the content check on its own, for proving it fails and for a fast answer while writing copy. `npm run build` runs the same check inside the prerenderer, so a clean run here is not a substitute for a build
`scripts/lib/`	shared, side-effect-free modules: `routes.js` (the one route list, and the drift check against the router's own table) and `content.js` (what must be true of `src/data/**` before a page is built from it)
`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 `queuenorth.com`, asserting HTTP 200 and `"status":"ok"` and `"db":"ok"` — a 503 with a JSON body is a real answer, not an outage. `HEALTHCHECK_BASE_URL` points it at the other front door
`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/release.sh`	publishes. Bump, guard, build, verify the image's own version label, push `:vX.Y.Z`, commit last, tag. Refuses to overwrite a published tag, to build on a dirty tree, or to build when the three hard-coded copies of the public origin disagree. Adapted from PrivacyLLC-Web's — see below
`scripts/deploy.sh`	deploys, and does not build. Points Portainer stack 58 at an already-published numbered version — it refuses a floating tag — taking a verified backup first and preserving the stack's twelve environment variables, then waits for health and checks both public origins. Reports the digest before and after

| scripts/docker-test.sh | builds the image and runs it locally on 3001. Predates the template | | scripts/qa-browser.mjs | renders the site in real Chromium at real viewports and measures it — horizontal scroll, broken images, elements past the right edge, CLS and LCP. Exit 2 if playwright is missing, because "could not check" is not a pass. Not in verify.sh: playwright is global here, not a project dependency | | scripts/prerender.js | the build step that emits static HTML for every route. Predates the template |

Why release.sh and deploy.sh are two scripts. Publishing an image and running it are separate decisions, which is the rule both the template and PrivacyLLC-Web's release script state and the reason neither of them deploys. The template's deploy.py does build, push and deploy; adopting it beside release.sh would have produced two commands that both build, a second image for the same code, and two answers to "what is running". So deploy.sh does only the half that was missing.

Three things about release.sh differ from the script it was adapted from, and each is a fact about this project rather than a preference:

It gates on verify.sh, not on a test suite, because there is not one. The original refuses to release on a half-run 1,600-test run; this one says out loud that a build, a secret scan and a doc-header check are not tests and that nothing in the gate exercised a route, a form or an API response.
It publishes one tag and does not move :dev. Both scripts follow the policy below: production always runs a numbered version, so nothing deploys a pointer and publishing one would only misrepresent what is running.
It checks the public origin in three files rather than one. The original passes its origin in as a build arg, so it has one copy to validate. Here https://queuenorth.com is written out in src/lib/seo.js, src/components/SEO.jsx and scripts/prerender.js, and it is baked into every canonical URL, og:url, sitemap.xml and robots.txt. The guard asks whether the three still agree, because a wrong origin cannot be corrected without another build and is invisible until somebody reads the page source.

Neither script prunes the registry. The original does, because it releases often enough for that to matter. This project has published thirteen tags in its life, deleting a published image is irreversible, and the one that matters is whichever the running container was created from — exactly what a newest-N rule gets wrong.

Why secrets.sh has a tightened pattern. Its user:pass@host in a URL rule excludes only /, @, : and whitespace in the template. That is right for source and wrong for this project's build output: every prerendered page carries schema.org JSON-LD, and //queuenorth.com"},"areaServed":{"@ parses as a host, a password and an @. Ten findings per --built run, one more for every page added — the noise that turns a scanner into something people mute. Quotes, braces, commas and angle brackets cannot occur in real userinfo, so excluding them costs nothing and was checked against three real credential URLs before being applied. The reasoning is in the script's own header.

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.

17 KiB Raw Blame History