CTO roadmap: harden, cache, and de-duplicate (P0–P3)

.context/adr/0001-bigquery-serving-layer.md

@@ -0,0 +1,55 @@
+# ADR 0001 — BigQuery as the serving layer (and when to add one)
+
+- **Status:** Accepted (deferred build)
+- **Date:** 2026-06-16
+- **Roadmap ref:** P3-22 / the "documented-but-unbuilt serving tier" in
+  [cto-review-roadmap.md](../cto-review-roadmap.md)
+
+## Context
+
+Stats pages read directly from **BigQuery**, an OLAP warehouse, on render.
+BigQuery has per-query latency (hundreds of ms to seconds) and bills by bytes
+scanned, so using it as an interactive app's serving database is, in principle,
+the wrong shape — and was the root cause behind the two search postmortems.
+
+**P0-1 mitigated this** by caching each stats page's query in front of BigQuery
+(`lib/cache.ts`, `unstable_cache`, 1h revalidate). That removes BigQuery from
+the hot path for repeat views and cuts cost/latency substantially.
+
+**Known limit of the current cache:** Next's Data Cache on Cloud Run is
+**per-instance** (in-memory + `.next/cache`), not shared across scaled-out
+instances, and is lost on cold starts. Each instance still serves repeat loads
+from cache within the revalidate window, but there is no single global cache.
+
+## Decision
+
+**Do not build a dedicated serving tier (Postgres / materialized views) now.**
+For a solo/volunteer-maintained app at current traffic, the per-instance cache
+is sufficient and a serving tier is maintenance the team shouldn't carry yet.
+Revisit when the triggers below fire.
+
+## Triggers to revisit (build the serving tier when any holds)
+
+- BigQuery spend becomes material (watch the budget alert from the ops runbook).
+- p95 page latency on cache misses is consistently user-visible, or cold
+  starts / many instances make per-instance caching ineffective.
+- Traffic grows enough that cache-miss query volume is a real cost or
+  rate-limit concern.
+
+## Sketch (if/when built)
+
+- Keep **BigQuery as the source of truth** and the place heavy aggregation runs.
+- Precompute the per-page aggregates the loaders need into a **serving store**
+  (Postgres, already a removed dependency we'd re-add — see P2-11 — or a managed
+  KV/edge cache) on a schedule (e.g. after the daily data refresh).
+- Loaders read from the serving store; BigQuery is queried only by the
+  precompute job. The `lib/cache.ts` seam stays in front for hot data.
+- Alternatively, a shared Next `cacheHandler` (e.g. Redis) gives a global cache
+  with far less work than a full serving tier — consider this first.
+
+## Consequences
+
+- Today: lowest maintenance; accept per-instance cache + occasional cache-miss
+  BigQuery latency.
+- Deferred: the migration is non-trivial (a precompute job + a store to operate),
+  which is exactly why it waits for evidence that it's needed.

.context/ops-runbook.md

@@ -0,0 +1,61 @@
+# PAX-Vault Ops Runbook
+
+Operator checklist for the reliability/security items that live outside the
+codebase (GCP console, billing, secret management). These are **manual actions**
+— there is no code to deploy for them. Roadmap ref: P1-9.
+
+## 1. Secret hygiene
+
+**Problem:** production secrets currently sit in plaintext in `.env.firebase`
+on a developer laptop. That file is correctly git-ignored (not in the repo), but
+a laptop copy is still an exposure.
+
+- [ ] Treat **Google Secret Manager** as the source of truth for production
+      secrets (it already backs `apphosting.yaml`). Delete `.env.firebase` from
+      the laptop once confirmed; pull values on demand with
+      `gcloud secrets versions access` rather than keeping a local copy.
+- [ ] Keep `.env.local` (dev-only values) on the laptop — that's expected.
+- [ ] Confirm `.gitignore` still excludes `.env*` except `.env.example`
+      (it does today).
+
+### Rotate `SESSION_SECRET` (hygiene, ~quarterly or on suspicion)
+
+Rotating invalidates the HMAC on every existing `__session` cookie, so **all
+users are logged out and must sign in again** (low impact for this app).
+
+1. Generate a new secret: `openssl rand -hex 32`
+2. Add it as a new version in Secret Manager for the `SESSION_SECRET` secret.
+3. Trigger a rollout so App Hosting picks up the new version
+   (`npm run firebase:deploy`).
+4. Verify sign-in end-to-end after the rollout.
+
+## 2. Uptime check (catch "site is down")
+
+Use either option — both have free tiers. Target the **public** landing page
+(`/`) so the check doesn't need auth.
+
+- **Google Cloud Monitoring** → Uptime checks → Create:
+  - Protocol HTTPS, host `pax-vault.f3nation.com`, path `/`, check every 5 min.
+  - Alert policy → notify your email/Slack on failure.
+- **or UptimeRobot** (external): HTTPS monitor on the same URL, 5-min interval.
+
+## 3. BigQuery cost guardrail (catch "runaway query cost")
+
+Two complementary controls:
+
+- [ ] **Billing budget alert** (Cloud Billing → Budgets & alerts → Create
+      budget): scope to the `f3data` project (or the BigQuery service), set a
+      monthly amount, and alerts at 50/90/100%. This notifies; it does not cap.
+- [ ] **Custom query quota** (optional hard cap) — IAM & Admin → Quotas →
+      filter "BigQuery API: Query usage per day", set a per-day bytes ceiling so
+      a pathological query/loop can't run up an unbounded bill.
+
+> Pairs with the P0 caching work: cached page loads no longer issue BigQuery
+> jobs, so steady-state cost should be low and a sudden spike is a real signal.
+
+## 4. Error tracking (cross-ref P0-3)
+
+The provider-agnostic seam is already wired (`src/lib/observability.ts`,
+`reportError`). When you adopt a provider (e.g. Sentry), forward from the single
+`TODO(P0-3)` hook there and set its DSN as a Secret Manager secret — no call
+sites change.

.context/remaining-work.md

@@ -0,0 +1,52 @@
+# Remaining Work — after the CTO roadmap pass
+
+Status as of the `cto-review-roadmap` branch. The substantive roadmap
+([cto-review-roadmap.md](cto-review-roadmap.md)) is executed; this tracks what
+was **deliberately deferred**, **blocked on a decision**, or is an **operator
+action**. Nothing here is a pressing code defect.
+
+## Deferred by design (incremental / opportunistic / needs a visual pass)
+
+- **#17 — finish the big-component splits.** The `pageFilter` accordion drawer
+  (Region/AO/Tag/Type/Category sections, heavily `useState`-coupled) and
+  `events.tsx` (~36KB). Do incrementally when next editing them. Note: HeroUI
+  `<Accordion>` requires `<AccordionItem>` as direct children, so any section
+  extraction must return `AccordionItem` directly (not wrap it in a component).
+  _Already done:_ the active-filter chip subsystem was extracted to
+  `ActiveFilterChips.tsx`.
+- **#12 — finish the SummaryCard de-dup.** Unify the per-row markup into a
+  shared `StatRow` (region rows use `text-sm`, area/sector don't — normalizing
+  needs a visual check) and migrate the PAX `SummaryCard` (11 rows, structurally
+  different). `renderStat` + `HelpHint` are already shared.
+- **#20 — tighten the server/client seam.** Move static dashboard cards to
+  Server Components, pushing `"use client"` to interactive leaves. Real
+  bundle-size win, but a large refactor — do when next reworking the dashboard.
+- **#21 — file-naming consistency.** PascalCase components / camelCase utils.
+  Low value, churn-y; opportunistic only. (`nation/` needs no loader — it's a
+  static page.)
+
+## Blocked on a product decision
+
+- **Charts (#2 / #18 trend deltas).** Charts are intentionally hidden site-wide
+  (region/area/sector). "Ship charts properly" = un-hide all three consistently
+  **and** fix the chart-quality issues (readable labels, color-encoding), then
+  add trend deltas/CTAs. Real feature work — awaiting a go/no-go.
+- **#19 — warmer empty/celebration copy.** Subjective; pair on it if wanted.
+
+## Operator actions (not code — see [ops-runbook.md](ops-runbook.md))
+
+- Rotate `SESSION_SECRET`; move prod secrets off the laptop to Secret Manager.
+- Add an uptime check (public landing page) + a BigQuery billing budget alert.
+- Pick an error-tracking provider and wire the single `TODO(P0-3)` hook in
+  `src/lib/observability.ts` (set its DSN as a secret).
+- Run `npm run test:e2e` (local smoke suite) in your workflow; it needs
+  `npx playwright install chromium` once.
+
+## Done (for reference)
+
+P0–P3 executed: caching, error seam, full query parameterization, the filter
+contract, postmortem regression tests, mobile/height fixes, local smoke test,
+dead-code/dep cleanup, entity de-dup (empty-state / `renderStat` / `HelpHint` /
+breadcrumb), `normalizeDeep`, dashboard reorder, leaderboard ranks, mobile
+attendee collapse, focus-visible baseline, navbar F3 glyph, removable filter
+chips, ops runbook, and the serving-tier ADR.

.gitignore

@@ -53,4 +53,10 @@ pr.md
 
 # large log files in issue context
 .context/issues/**/*.json
-certificates
+certificates
+
+# Playwright (local-only e2e)
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/

e2e/smoke.spec.ts

@@ -0,0 +1,79 @@
+import { test, expect, type BrowserContext } from "@playwright/test";
+import { createHmac } from "crypto";
+
+/**
+ * Mint a `__session` cookie the same way src/lib/auth/session.ts does, so the
+ * smoke test can exercise authenticated pages without driving real OAuth.
+ * (Replicated here because Playwright does not resolve the app's "@/" alias.
+ * Keep in sync with createSessionValue / SESSION_COOKIE_NAME.)
+ */
+function mintSessionValue(email: string): string {
+  const secret = process.env.SESSION_SECRET;
+  if (!secret) {
+    throw new Error("SESSION_SECRET is required (load it from .env.local)");
+  }
+  const payload = {
+    sub: email,
+    email,
+    name: "Smoke Test",
+    iat: Math.floor(Date.now() / 1000),
+  };
+  const json = Buffer.from(JSON.stringify(payload)).toString("base64url");
+  const signature = createHmac("sha256", secret)
+    .update(json)
+    .digest("base64url");
+  return `${json}.${signature}`;
+}
+
+const BASE_URL = process.env.PLAYWRIGHT_BASE_URL ?? "https://localhost:3001";
+const SAMPLE_REGION = process.env.SAMPLE_REGION;
+
+async function signIn(context: BrowserContext) {
+  await context.addCookies([
+    {
+      name: "__session",
+      value: mintSessionValue("smoke@pax-vault.test"),
+      domain: new URL(BASE_URL).hostname,
+      path: "/",
+      httpOnly: true,
+      secure: true,
+      sameSite: "Lax",
+    },
+  ]);
+}
+
+test.describe("pax-vault smoke", () => {
+  test("public landing page renders", async ({ page }) => {
+    await page.goto("/");
+    await expect(page.getByText(/PAX Vault/i).first()).toBeVisible();
+  });
+
+  test("unauthenticated stats route redirects to landing", async ({ page }) => {
+    await page.goto(`/stats/region/${SAMPLE_REGION ?? "1"}`);
+    // Middleware bounces unauthenticated users back to "/".
+    await expect(page).toHaveURL(/\/(\?.*)?$/);
+  });
+
+  test("authenticated region dashboard loads", async ({ page, context }) => {
+    test.skip(!SAMPLE_REGION, "SAMPLE_REGION not set in .env.local");
+    await signIn(context);
+    await page.goto(`/stats/region/${SAMPLE_REGION}`);
+    await expect(page).toHaveURL(new RegExp(`/stats/region/${SAMPLE_REGION}`));
+    // Some dashboard chrome should render once the data resolves.
+    await expect(page.getByText(/Summary|Leaders/i).first()).toBeVisible({
+      timeout: 15000,
+    });
+  });
+
+  test("authenticated search API returns a well-formed 200", async ({
+    context,
+  }) => {
+    await signIn(context);
+    const res = await context.request.get("/api/search?q=no");
+    expect(res.status()).toBe(200);
+    const body = await res.json();
+    expect(body).toHaveProperty("regions");
+    expect(body).toHaveProperty("aos");
+    expect(body).toHaveProperty("pax");
+  });
+});