motovaultpro/.claude/skills/mvp-architecture-contract/SKILL.md

name, description

name

description

mvp-architecture-contract

Load this before designing, extending, or reviewing any MotoVaultPro feature or refactor. It states the load-bearing architecture decisions (and WHY), the invariants that must hold, and the known-weak points. Symptoms that mean you need this skill; adding a new backend feature capsule or API route; a new route returns 401 everywhere or, worse, works WITHOUT a token; a migration "ran" but the table does not exist; a route registered fine but is missing the /api prefix; a new page works on desktop but is unreachable on mobile (or vice versa); a tier-gated feature is accessible to free users; wondering why this is Docker Compose and not Kubernetes; wondering whether userContext.userId is the Auth0 sub (it is not).

MotoVaultPro Architecture Contract

Authored 2026-07-07. Every code claim below was verified against the repo on that date. Where a doc contradicts this file, re-verify against code: code wins.

When to use / When NOT to use

Use this skill when you are about to add or modify a backend feature capsule, an API route, a repository, a migration, a frontend page, or tier gating — or when a change "works" but violates one of the failure symptoms in the description above.

Do NOT use this skill for:

• How to branch/commit/PR or what review rules apply: mvp-change-control
• Triage of a live failure: mvp-debugging-playbook
• Why a past decision was reverted, incident history: mvp-failure-archaeology
• Config/secret axes and how to add one: mvp-config-and-secrets
• Deploy, blue-green, rollback, backups: mvp-run-and-operate
• VIN/fuel/date domain math: mvp-vehicle-domain-reference
• Which docs to trust in full detail: mvp-docs-and-writing

Doc-trust rule (architecture facts)

For architecture facts: code > docs/CICD-DEPLOY.md and docs/LOGGING.md > everything else. docs/ARCHITECTURE-OVERVIEW.md and docs/DATABASE-SCHEMA.md are known-stale (DATABASE-SCHEMA.md still says "15 feature capsules" and a migration order starting with admin; reality is 21 capsules and an order starting with features/vehicles). Route to mvp-docs-and-writing for the full trust map. When this skill and the code disagree, the code changed after 2026-07-07 — update this skill.

Part 1: Load-bearing decisions and WHY

1.1 9-container single-tenant Docker Compose (Kubernetes was tried and abandoned)

9 containers: Traefik, Frontend (React/nginx), Backend (Fastify), OCR (Python), PostgreSQL, Redis + Loki, Alloy, Grafana. Base file docker-compose.yml; staging/prod/blue-green are overlay files.

WHY compose, not k8s: a Kubernetes-style redesign was planned and executed as a "Kubernetes-like Docker Compose" restructure — commit 040da4c ("k8s redesign complete", 2025-09-18) added K8S-STATUS.md (titled "Kubernetes-like Docker Compose Migration Status") plus compose/Makefile changes; no actual k8s manifests were ever committed anywhere in history (only Markdown planning docs). The status doc was demoted out of the repo root into docs/changes/ four days later (8fd7973, 2025-09-22) and deleted entirely on 2025-10-16 (5638d39). The product is single-tenant on VPS-class hardware; the k8s direction bought operational complexity with no scaling need. This is a settled battle — do not propose k8s again without new facts (see mvp-failure-archaeology).

Single-tenant means: one deployment per customer base is NOT the model — there is one user population in one database, all rows scoped per user (section 2.5).

1.2 Backend feature capsules

All application features are self-contained modules under backend/src/features/ — 21 capsule directories (the 22nd entry is CLAUDE.md). Canonical anatomy (fuel-logs is the reference):

backend/src/features/{name}/
  index.ts        # barrel export: routes + anything other capsules may import
  api/            # {name}.routes.ts (FastifyPluginAsync, per-route preHandlers),
                  # {name}.controller.ts, {name}.validators.ts
  domain/         # {name}.service.ts, {name}.types.ts (camelCase TS types)
  data/           # {name}.repository.ts (class taking pool; private mapRow())
  external/       # cross-feature or third-party clients
  migrations/     # NNN_name.sql, feature-owned schema
  tests/          # unit/ and integration/

Wiring: backend/src/app.ts imports each capsule's routes and registers every one with { prefix: '/api' } (lines ~136-159). Plugin registration order before routes: helmet, cors, logging, error, multipart, auth, admin-guard, tier-guard. Shared infra lives in backend/src/core/ (plugins, config, logging, middleware, scheduler, storage).

WHY: capsules keep each feature's schema, logic, and HTTP surface in one directory so an AI session can load one capsule instead of the whole backend — this is the project's stated AI-context-efficiency principle.

1.3 YAML config + file secrets, NOT env vars

backend/src/core/config/config-loader.ts loads a zod-validated YAML file (CONFIG_PATH, default /app/config/production.yml) plus file-based secrets from SECRETS_DIR (default /run/secrets). DB, Redis, Auth0, and CORS settings live in YAML. Env vars are the exception (Stripe price IDs, OCR_SERVICE_URL, MIGRATIONS_DIR, LOG_LEVEL, CONFIG_PATH/SECRETS_DIR themselves). Missing required config or secret = startup crash by design.

WHY: one schema-validated config document beats scattered env vars for auditability, and file secrets match Docker secret mounts. Do not add process.env.X for app config — add it to the zod schema and YAML. Full catalog: mvp-config-and-secrets.

1.4 Repository mapRow: snake_case to camelCase, MUST coerce numerics

Every repository exposes data only through a private mapper (mapRow()), converting DB snake_case to TS camelCase. Critically: node-postgres returns NUMERIC/DECIMAL (OID 1700) as strings and this project does NOT override that parser globally — every mapper must coerce (parseFloat/Number) or the API leaks strings where numbers are typed. This caused a multi-incident bug train (issues #239, #241, #244). New repository with decimal columns = coerce in the mapper, no exceptions.

1.5 DATE columns are plain strings end-to-end

backend/src/core/config/database.ts line 12:

types.setTypeParser(1082, (val: string) => val);

DATE (OID 1082) values stay "YYYY-MM-DD" strings through repository, API, and frontend. WHY: pg's default returns a Date at local midnight, which shifts a day when serialized to UTC (issue #237). The full DATE-handling rules (dayjs display, lexicographic sort, the three historical traps) are canonical in mvp-vehicle-domain-reference section 3.

1.6 Auth: per-route preHandler; userId is the internal UUID, not the Auth0 sub

backend/src/core/plugins/auth.plugin.ts decorates fastify.authenticate (line 120): validates the Auth0 JWT (JWKS, issuer, audience), then loads/creates the user_profiles row and hydrates request.userContext.

userContext.userId is the internal user_profiles.id UUID, NOT the Auth0 sub (auth.plugin.ts line ~130 defaults to auth0Sub, overwritten with profile.id at line ~165). This is the post-#206 identity migration state (merged in PR #219). All repositories scope queries by this UUID.

There is NO global auth hook. Every protected route must list preHandler: [fastify.authenticate] itself (see section 2.1).

1.7 Migrations: feature-owned, hard-coded order, run at container start, NO rollback

• SQL files live in each capsule's migrations/ dir, executed in lexical order within a feature.
• Cross-feature order is the hard-coded MIGRATION_ORDER array in backend/src/_system/migrations/run-all.ts (17 entries; features/vehicles first because it defines update_updated_at_column() which later features depend on; core/identity-migration last).
• Execution is tracked in the _migrations table (UNIQUE(feature, file)); already-run files are skipped.
• Migrations run automatically on every backend container start (backend/Dockerfile CMD: node dist/_system/migrations/run-all.js && npm start), and manually via make migrate or cd backend && npm run migrate.
• There is no rollback. No down migrations. Recovery is restore-from-export (scripts/import-database.sh). WHY: single-tenant, small blast radius, and honest acknowledgment that untested down-migrations are worse than a restore path.

OWNER NON-NEGOTIABLE: no destructive database operation without a fresh backup — that includes schema migrations on staging/prod (./scripts/export-database.sh --env <env> first), make clean (destroys volumes), and import-database.sh --drop-existing. See mvp-change-control.

1.8 Redis: cache-aside with mvp: prefix; cache failure never breaks a request

backend/src/core/config/redis.ts: singleton ioredis client; CacheService prefixes every key with mvp: and wraps every operation in try/catch that logs and returns null/continues. A dead Redis degrades to cache-miss behavior, never a 500. DistributedLockService (prefix mvp:lock:, SET NX EX + Lua release) backs scheduled jobs. Follow this pattern: read cache, on miss hit DB and set with TTL, invalidate on write — and never let a cache error propagate.

1.9 Frontend dual navigation — deliberate but costly (the registration-checklist tax)

frontend/src/App.tsx forks the entire app at window.innerWidth <= 768 plus a UA regex (~lines 360-407):

• Desktop: react-router <Routes> under /garage/*, lazy-loaded features/*/pages/*Page.
• Mobile: NO router — a Zustand screen switcher (useNavigationStore().activeScreen) renders features/*/mobile/*MobileScreen components, with two-way URL sync via the routeToScreen / screenToRoute maps in frontend/src/core/store/navigation.ts.

WHY: the mobile experience is a purpose-built app shell (bottom nav, gesture transitions, error boundaries) rather than responsive pages. The cost is real and accepted: every new page must run the full registration checklist in invariant 2.7, and mobile+desktop are separate implementations that must BOTH be built and tested (hard project rule).

All frontend HTTP goes through the shared apiClient (frontend/src/core/api/client.ts), a queued axios wrapper that holds requests until the Auth0 gate reports ready — bypassing it with raw axios/fetch reintroduces the auth race it exists to solve.

Part 2: INVARIANTS — break these and here is what happens

#	Invariant	If you break it	Enforcing code path
2.1	Every protected route lists preHandler: [fastify.authenticate] explicitly	The route is PUBLIC. No global hook exists; nothing fails loudly. An unlisted route ships as an unauthenticated endpoint on the open internet	backend/src/core/plugins/auth.plugin.ts:120 (decorator only); routes files per capsule. Intentional public routes: canonical list lives in the header comment of .claude/skills/mvp-diagnostics-and-logging/scripts/check-route-auth.sh (webhooks + pre-auth signup routes in its allowlist, plus core-registered routes outside its scan scope: /health, /api/health, /auth/verify, GET /api/config/feature-tiers)
2.2	Every repository method returning rows goes through a mapper that coerces NUMERIC/DECIMAL	API returns "42.50" where the type says number; frontend .toFixed() crashes or renders garbage. This has shipped as a bug at least 3 times (#239, #241, #244)	No global parser for OID 1700 in backend/src/core/config/database.ts — coercion is per-mapper, by convention and review only
2.3	The DATE parser override stays	Dates shift one day for any user west of UTC (issue #237 regression)	backend/src/core/config/database.ts:12 types.setTypeParser(1082, ...)
2.4	A new capsule with migrations gets appended to MIGRATION_ORDER	Its migrations silently never run — no error, the runner only walks listed directories. First symptom is "relation does not exist" on staging	backend/src/_system/migrations/run-all.ts:17-35; also requires an image rebuild so the SQL is packaged into /app/migrations
2.5	All user data scoped by the user_profiles UUID (userContext.userId)	Cross-user data leak, or zero rows returned if you scope by the Auth0 sub. Post-#206, feature tables' user_id column is UUID type FK to user_profiles(id) ON DELETE CASCADE (the migration added user_profile_id, backfilled, dropped old VARCHAR user_id, then RENAMED user_profile_id back to user_id); admin_users keeps a separate user_profile_id column	backend/src/core/identity-migration/migrations/001_migrate_user_id_to_uuid.sql; auth.plugin.ts userContext hydration
2.6	Frontend API calls only via the shared queued apiClient	Requests fire before the Auth0 token interceptor is installed: intermittent 401s on first load, spurious error toasts	frontend/src/core/api/client.ts (createQueuedAxios, authReady gate); interceptor installed in frontend/src/core/auth/Auth0Provider.tsx
2.7	New pages registered at EVERY registration point. This is the CANONICAL checklist (other skills point here; do not trust any "4 places" shorthand — the full union is 7 steps): (1) desktop <Route> in App.tsx; (2) MobileScreen union type in navigation.ts; (3) routeToScreen map; (4) screenToRoute map; (5) lazy import of the *MobileScreen component in App.tsx; (6) mobile render block {activeScreen === "X" && ...} in App.tsx; (7) a navigation entry point (BottomNavigation.tsx or HamburgerDrawer.tsx item, or navigation from another screen)	Page unreachable on one platform; registered-but-unreachable on mobile (missing entry point or import); or URL/back-button desync (screen renders but URL lies, deep links break)	frontend/src/App.tsx (lazy imports + both render paths), frontend/src/core/store/navigation.ts (union line ~5; maps lines ~9, ~29), frontend/src/shared-minimal/components/mobile/
2.8	Tier-gated features registered in FEATURE_TIERS — unknown keys FAIL OPEN	A typo'd or unregistered featureKey on a plugin-guarded route silently grants access to ALL tiers. No error, no log at gate time	backend/src/core/config/feature-tiers.ts:57-62 (canAccessFeature returns true for unknown keys, by design). Registered-key and vehicle-limit literals: canonical catalog in mvp-config-and-secrets section 3
2.9	Capsule routes registered in app.ts with { prefix: '/api' } using the plain (non-fp) export	Route mounts at /thing instead of /api/thing; Traefik and the frontend both expect /api — the endpoint 404s in every deployed environment	backend/src/app.ts:136-159; see weak point 3.7 for the platform dual-export trap

New-capsule checklist (all must hold): barrel index.ts; routes registered in app.ts with /api prefix; every route lists its auth preHandler; repository mapper coerces numerics; migrations dir appended to MIGRATION_ORDER; queries scoped by the profile UUID; if tier-gated, key added to FEATURE_TIERS AND spelled identically at the gate site.

Part 3: Known-weak points (stated plainly — these are debt, not patterns to copy)

3.1 Tier gating fails open AND has two parallel mechanisms with different failure behavior — the middleware 500s on unknown keys, the plugin decorator fails open (full mechanics and the current key catalog are canonical in mvp-config-and-secrets section 3). Both are used, even mixed within one file (backend/src/features/ocr/api/ocr.routes.ts). The plugin's dependency check on the auth plugin was deliberately removed for testability — registration order is convention-only. When gating something new, prefer the plugin decorator with a key you have verified exists in FEATURE_TIERS.

3.2 Controllers string-match error messages for status codes. No typed error classes: catch blocks do error.message.includes('not found') -> 404, includes('Unauthorized') -> 403, else 500 (e.g. backend/src/features/fuel-logs/api/fuel-logs.controller.ts:30,36). Rewording a service error message silently changes an HTTP status. If you touch a service's thrown messages, grep the controller for includes( first.

3.3 Auth plugin is a per-request hot path to Auth0. Worst case per authenticated request: profile getOrCreate DB roundtrip, plus up to two Auth0 Management API getUser calls (email backfill when the JWT lacks email; verification re-check when the profile is unverified) plus the SDK's token grant — up to ~3 Auth0 HTTP calls. Failures fall back silently to JWT claims (auth.plugin.ts ~line 201). Latency and rate-limit exposure live here; do not add more per-request external calls to this plugin.

3.4 Dual fuel-logs schema, with a documented convention break. backend/src/features/fuel-logs/data/fuel-logs.repository.ts carries a legacy API (create/mapRow, gallons columns) and an enhanced API (createEnhanced/mapEnhancedRow, fuel_units/cost_per_unit, dual-writing legacy columns). mapEnhancedRow (line ~252) deliberately returns snake_case numeric-coerced rows, and the service's toEnhancedResponse (fuel-logs.service.ts:273) does the camelCase mapping — a known break from the mapRow convention, typed any throughout. Do not copy this pattern into new capsules; do not "fix" it casually either (dual-write compatibility is load-bearing).

3.5 App.tsx is a 1192-line god component (frontend/src/App.tsx): inline screen components, all mobile switching, auth routing, and global error suppression in one file. It violates the repo's own RULE 2. Changes here have wide blast radius; keep diffs surgical.

3.6 DB pool max is hard-coded 10 (backend/src/core/config/database.ts:16) while the config schema defines database.pool_size with default 20 (config-loader.ts:28) — the config value is not consumed by the pool. YAML pool tuning silently does nothing.

3.7 platform.routes.ts dual-export trap. backend/src/features/platform/api/platform.routes.ts:45-46 exports both a fastify-plugin-wrapped default AND a raw named export. app.ts imports the NAMED export, so the /api prefix applies. Switching the import to the fp-wrapped default would silently drop the prefix (fastify-plugin breaks encapsulation, so prefix is ignored) — every platform dropdown endpoint would move off /api with no error.

3.8 Two shared frontend trees with no boundary rule: frontend/src/shared/ and frontend/src/shared-minimal/ (theme, GlassCard, BottomNavigation live in shared-minimal). Check both before creating a "new" shared component.

3.9 (fastify as any).requireAdmin in backend/src/features/backup/api/backup.routes.ts (every route) — the admin-guard decorator is used through an any cast, so TypeScript would not catch the decorator being renamed or unregistered; the routes would throw at runtime instead.

Severity calibration: this is a pre-launch product heading toward paying users. 3.1 and invariant 2.1/2.8 are the security-shaped items — treat regressions there as RULE 0. The rest are RULE 1/2 debt: known, tolerated, but never to be silently extended.

Provenance and maintenance

Authored 2026-07-07 from direct repo inspection (file reads, greps, git history). Re-verify volatile facts before relying on them:

Fact (as of 2026-07-07)	Re-verify with
21 feature capsules	ls backend/src/features/ | grep -v CLAUDE.md | wc -l
Routes registered with /api prefix; platform uses named export	grep -n "prefix: '/api'" backend/src/app.ts | wc -l and grep -n "platformRoutes" backend/src/app.ts
DATE parser override present	grep -n "setTypeParser(1082" backend/src/core/config/database.ts
Pool max hard-coded 10; schema pool_size default 20	grep -n "max:" backend/src/core/config/database.ts; grep -n "pool_size" backend/src/core/config/config-loader.ts
MIGRATION_ORDER has 17 entries, vehicles first, identity-migration last	sed -n '17,36p' backend/src/_system/migrations/run-all.ts
Tier fail-open (key/limit catalog: mvp-config-and-secrets section 3)	grep -n "return true" backend/src/core/config/feature-tiers.ts; grep -n "minTier" backend/src/core/config/feature-tiers.ts
userContext.userId = profile UUID, not Auth0 sub	grep -n "userId = profile.id" backend/src/core/plugins/auth.plugin.ts
Feature tables' user_id is UUID (renamed from user_profile_id)	grep -n "RENAME COLUMN user_profile_id TO user_id" backend/src/core/identity-migration/migrations/001_migrate_user_id_to_uuid.sql
Redis mvp: prefix, errors swallowed	grep -n "prefix = 'mvp:'" backend/src/core/config/redis.ts
App.tsx 1192 lines; 768px fork	wc -l frontend/src/App.tsx; grep -n "768" frontend/src/App.tsx
Nav registration checklist (2.7 union)	grep -n "routeToScreen|screenToRoute|MobileScreen" frontend/src/core/store/navigation.ts; grep -n "activeScreen ===" frontend/src/App.tsx | head -3
Queued apiClient auth gate	grep -n "createQueuedAxios|authReady" frontend/src/core/api/client.ts
platform dual export	grep -n "export" backend/src/features/platform/api/platform.routes.ts | tail -2
requireAdmin any-cast in backup routes	grep -c "(fastify as any).requireAdmin" backend/src/features/backup/api/backup.routes.ts
k8s-style redesign tried/abandoned Sept-Oct 2025	git log --all --oneline -i --grep=k8s and git log --all --oneline --follow -- docs/changes/K8S-STATUS.md
Controller string-matching	grep -rn "includes('not found')" backend/src/features/*/api/*.controller.ts | head