Note
    Updated Jun 1, 2026

    Maintain backend architecture

    Worker and Neon backend architecture for authenticated profile, range, weights, dose events, workouts, schedules, sync cursor, trends, and export flows.

    Dates

    Created
    Jun 1, 2026
    Last updated
    Jun 1, 2026

    Document Metadata

    • title: Backend Architecture
    • description: Current Worker/API design and implementation gaps
    • status: evolving
    • lastUpdated: "2026-05-14 05:24 ET (America/New_York)"
    • owner: Engineering

    Backend Architecture ## Current Shape - Cloudflare Worker entrypoint in backend/src/index. ts - Hono router in `backend/src/routes/v1.

    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

    Provenance