refactor: harden data access, caching, and CI coverage

.github/workflows/ci.yml

@@ -0,0 +1,109 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quality:
+    name: Lint, typecheck, test, and build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Audit production dependencies
+        run: npm audit --omit=dev --audit-level=high
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Typecheck
+        run: npm run typecheck
+
+      - name: Test
+        run: npm test
+
+      - name: Build
+        run: npm run build
+
+  database:
+    name: Reset database migrations
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install Supabase CLI
+        uses: supabase/setup-cli@v3
+        with:
+          version: 2.118.0
+
+      - name: Start a fresh local database
+        run: supabase db start
+
+      - name: Replay all migrations
+        run: supabase db reset --local --no-seed
+
+      - name: Verify generated database types
+        run: npm run db:types:check
+
+  browser:
+    name: Critical browser flows
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 22
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start the local application services
+        run: npm run db:start:e2e
+
+      - name: Replay all migrations
+        run: npm run db:reset
+
+      - name: Install the Playwright browser
+        run: npx playwright install --with-deps chromium
+
+      - name: Run critical browser flows
+        run: npm run test:e2e
+
+      - name: Stop local services
+        if: always()
+        run: npm run db:stop

AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

README.md

@@ -24,6 +24,45 @@ npm run dev
 Create `.env.local` from `.env.example` before wiring Supabase auth or database
 features.
 
+## Validate Database Migrations Locally
+
+Docker Desktop must be running. The Supabase CLI version is pinned in
+`package.json`, and the local database settings live in `supabase/config.toml`.
+
+```bash
+npm install
+npm run db:start
+npm run db:reset
+npm run db:types
+npm run db:stop
+```
+
+`db:start` creates a fresh local Postgres database and applies every migration.
+`db:reset` drops the local schemas and replays the complete migration history.
+`db:types` regenerates the TypeScript database contract after schema changes.
+These commands do not connect to or modify the hosted Supabase project.
+
+## Run Critical Browser Tests Locally
+
+The Playwright suite uses two deterministic local profiles and the ephemeral
+ES256 key generated by the local Supabase Auth container. It covers signed-out
+routing, starting a timer, creating a group, and a private-group RLS denial.
+It never connects to MAC Auth or the hosted Supabase project.
+
+Docker Desktop and Google Chrome must be available on Windows. Run:
+
+```bash
+npm run db:start:e2e
+npm run db:reset
+npm run test:e2e
+npm run db:stop
+```
+
+`db:start:e2e` starts only the local services required by the browser suite.
+The generated browser sessions and traces are written under `test-results/`,
+which is ignored by Git. CI installs its own Playwright Chromium browser and
+runs the same suite against a freshly reset database.
+
 ## Deploy And Test On Phone
 
 The production app is deployed through Dokploy at
@@ -95,6 +134,7 @@ npm run dev
 npm run build
 npm run typecheck
 npm run test
+npm run test:e2e
 npm run lint
 ```
 

docs/plans/2026-09-28-architecture-hardening.md

@@ -0,0 +1,62 @@
+# Architecture hardening plan
+
+This checklist is the review record for the architecture work. Work stops after each phase so the completed phase can be reviewed before the next phase begins.
+
+## Phase checklist
+
+- [x] **Phase 1 — CI quality gates**
+  - Commit: `ci: enforce quality and dependency checks`
+  - [x] Run on every push and pull request.
+  - [x] Install from the lockfile with Node.js 22.
+  - [x] Reject high or critical production dependency vulnerabilities.
+  - [x] Run lint, typecheck, unit tests, and the production build.
+  - [x] Cancel superseded runs on the same branch.
+  - [x] Validate all workflow commands locally.
+- [x] **Phase 2 — Repeatable local database**
+  - Commit: `build: add repeatable Supabase migration checks`
+  - [x] Add and document the local Supabase configuration.
+  - [x] Prove all migrations apply to an empty database with `supabase db reset`.
+  - [x] Add the migration reset check to CI.
+  - [x] Resolve migration ordering, extension, seed, port, or environment assumptions found by the reset.
+- [x] **Phase 3 — Generated database types**
+  - Commit: `refactor: add generated Supabase database types`
+  - [x] Generate TypeScript types from the reset schema.
+  - [x] Parameterize every existing browser, server, and admin Supabase client (there is no Supabase middleware client).
+  - [x] Replace handwritten database row types where generated types are authoritative.
+  - [x] Add a repeatable type-generation command and a stale-types check.
+- [x] **Phase 4 — Feature data modules**
+  - Commit: `refactor: split app data by feature`
+  - [x] Split `app-data.ts` into timer, units, groups, friends, chat, and notifications modules.
+  - [x] Keep authorization and server-only boundaries explicit.
+  - [x] Remove duplicated subject reads and preserve all 69 existing public exports during migration.
+  - [x] Review extracted logic and access rules; no new behavior required additional focused tests.
+- [x] **Phase 5 — Focused reads and cache correctness**
+  - Commit: `perf: replace broad reads and harden cache invalidation`
+  - [x] Inventory every consumer of the broad social snapshot.
+  - [x] Replace it with focused RPCs, pagination, and aggregate queries.
+  - [x] Add or verify supporting indexes with query evidence.
+  - [x] Add freshness timestamps and mutation/realtime invalidation to client caches.
+  - [x] Verify stale data is not retained after relevant writes.
+  - [x] Follow-up: scope every persisted cache entry to its signed-in user.
+  - [x] Follow-up: deduplicate concurrent remote requests per user and feature.
+  - [x] Follow-up: replace per-dashboard realtime channels with one app channel.
+  - [x] Follow-up: pause remote loading and refresh listeners for hidden dashboards.
+  - [x] Follow-up: notify the active consumer after mutations and realtime changes.
+  - [x] Follow-up: keep navigation unread badges current at the app-shell level.
+  - [x] Follow-up commit: `fix: scope and coordinate client data caching`
+- [x] **Phase 6 — Critical browser coverage**
+  - Commit: `test: add critical Playwright coverage`
+  - [x] Cover authentication routing.
+  - [x] Cover starting a timer.
+  - [x] Cover creating a group.
+  - [x] Cover an RLS-sensitive access denial.
+  - [x] Run the Playwright suite in CI and document required test data/environment.
+
+## Current review gate
+
+- [x] Review Phase 1 and approve starting Phase 2.
+- [x] Review Phase 2 and approve starting Phase 3.
+- [x] Review Phase 3 and approve starting Phase 4.
+- [x] Review Phase 4 and approve starting Phase 5.
+- [x] Review Phase 5 and approve starting Phase 6.
+- [ ] Review Phase 6.

next-env.d.ts

@@ -1,6 +1,7 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
 import "./.next/dev/types/routes.d.ts";
+import "./.next/types/root-params.d.ts";
 
 // NOTE: This file should not be edited
 // see https://nextjs.org/docs/app/api-reference/config/typescript for more information.