Milestone 8: polish — client-smoke, Dockerfile, compose, architecture doc

[rodrigobnogueira]

Summary

• Brief §12 milestone 8: the artifacts that turn the working app into something a team could actually adopt.
• All eight milestones from the brief are now complete.
• 45/45 tests pass; npm run ci exits 0 locally (and now includes client-smoke:typecheck).

Changes

• client-smoke/ — typed tRPC client workspace per brief §5. Own tsconfig.json (no npm workspaces). client-smoke/client.ts imports AppRouter from src/@generated/server.ts, boots the app in-process, seeds the DB, and runs three procedures against 127.0.0.1 via @trpc/client's createTRPCClient + httpBatchLink:
  • ping (unauth query)
  • auth.login (mutation)
  • users.me with Authorization: Bearer <token> (auth-protected query)
    Output:

  ping → pong
  auth.login → user=admin@acme.test org=#1 token=…UOGJW6B8
  users.me → #1 admin@acme.test
  client-smoke: ok
  

  npm run client-smoke runs it. npm run client-smoke:typecheck is added to npm run ci.
• Dockerfile — multi-stage production build. Stage 1 installs full deps (with python + g++ so better-sqlite3's prebuild fallback succeeds on slim images), generates the tRPC schema, runs tsc. Stage 2 ships dist/ + production deps + migrations + scripts on a slim Node base, with a /data volume for SQLite persistence. The same image runs either the API (default CMD) or the worker (node dist/scripts/start-worker.js override).
• docker-compose.yml — two-process stack (api + worker) on a shared SQLite volume, with an HTTP healthcheck on api and a 15s stop_grace_period on the worker. A Postgres service section is committed commented as the production swap recipe; uncomment + flip DATABASE_URL to switch.
• docs/architecture.md — one-sitting tour: module graph, request lifecycle (Express auth middleware + tRPC + request-scoped DI), authentication (scrypt + JWT), the central @Transactional workflow, why the custom SyncDrizzleTransactionalAdapter exists (better-sqlite3's sync tx model), outbox flow, worker process, layout map, test map, production deployment recipe.
• README finalized — reflects the v0.1 state across all eight milestones; status badge bumped from bootstrap to v0.1.

Modules Touched

• organizations / users / memberships
• projects
• audit-log
• outbox
• auth / context
• trpc
• database
• Tooling / CI / docs only

Public Surface (libraries)

• No use of library internals introduced.
• client-smoke/ consumes only the generated AppRouter type — the supported public surface of nest-trpc-native. No TrpcRouter reach-through, no Nest internals.

Security Review

• Auth bypass risk — n/a; this milestone adds tooling, not surface.
• Input validation — client-smoke/client.ts uses literal inputs against the seeded admin; no untrusted data path.
• Injection / path traversal / unsafe dynamic execution / unsafe deserialization — n/a.
• Secret leakage — Dockerfile and docker-compose use ${AUTH_SECRET:?…} to refuse to start if AUTH_SECRET is unset; the client-smoke script uses a clearly-marked test secret only.
• Transport assumptions — docker-compose's api healthcheck uses 127.0.0.1 from inside the container, not the published port; no extra surface exposed.
• Supply chain — @trpc/client is a devDep on the same line of the tRPC ecosystem as @trpc/server (already in dependencies); same release cadence.
• No unresolved high-risk security finding remains.

Dependency Review

• @trpc/client@11.17.0 — devDep, consumed only by client-smoke/. Not pulled into the app's runtime bundle. Required to demonstrate that the generated AppRouter is consumable by a typed client. Justification documented in CHANGELOG.md. No preinstall/install/postinstall/prepare scripts.
• No other dependency or lockfile changes (only the @trpc/client addition and its transitive package-lock entries).
• No unapproved Git/URL dependencies.

Migrations

• No schema changes.

Validation

• npm run typecheck
• npm run client-smoke:typecheck (new in CI)
• npm run lint
• npm run complexity:check
• npm run test:cov — 45/45 tests; 91.43% statements / 95.55% functions
• npm run security:audit — exits 0 (4 moderate dev-only findings unchanged)
• npm run build
• npm run smoke
• npm run client-smoke — printed expected output end-to-end

Validation Notes

• The Dockerfile and docker-compose.yml are documented recipes; they were not built/run in this PR's CI. Brief §4 lists Postgres as a documented optional recipe rather than a tested code path.

Release Notes

• Release impact: CHANGELOG.md updated under [Unreleased] with milestone-8 entry + the @trpc/client justification.

This is the last brief-defined milestone. After merge, suggest tagging v0.1.0 per brief §14's "definition of done."