Backend Architecture

Current Shape

• Cloudflare Worker entrypoint in backend/src/index.ts
• Hono router in backend/src/routes/v1.ts
• Repository abstraction in backend/src/lib/repository.ts
• Queue-based hooks for recommendations and exports
• Ordered SQL migrations in backend/migrations/
• Canonical migration runner in scripts/apply_backend_migrations.sh
• Read-only schema drift check in scripts/check_backend_drift.sh, with explicit database-query failure reporting before schema assertions
• Authenticated routes now exist for profile, maintenance range, weights, schedules, dose events, workouts, trends, and exports
• The profile sync contract persists display name, journey summary, maintenance range, and server-owned updatedAt
• GET /v1/sync-cursor exposes a server-owned cursor foundation by deriving current per-entity high-water marks from existing sync updated_at metadata
• The Neon-backed repository path is implemented for the main CRUD and export flows, while demo mode still provides seeded fallback behavior without a database URL

Modes

• Demo mode works without a database URL and returns seeded/demo data
• Live mode fails fast when DATABASE_URL is missing instead of silently serving demo sync data
• Live mode uses Neon Postgres plus bearer-token-authenticated requests validated against Neon Auth-compatible JWKS settings
• Seeded 143-anchored values are intentional demo/test fixtures only; they must stay confined to DEMO_MODE=true, backend tests, iOS UI-testing sample data, or unit/snapshot fixtures

Near-term Direction

• Tighten correctness and performance on the current live paths, especially auth caching, validation strictness, and sync efficiency
• Preserve the current route contracts while backlog hardening work is split into focused streams
• Expand coverage from route smoke tests into deeper authenticated and repository-level behavior
• Keep migration application and schema-drift verification explicit so live database state does not silently diverge from repo expectations