API server

The API server starts with uvicorn.run() on port 8000 and is built around FastAPI, a web framework that handles HTTP requests asynchronously.^[1][2] Its main components are configuration and logging, database session management, service layer business logic, HTTP routers grouped by domain, and Pydantic request/response schemas.^[3]

Metrics and insights routers expose /metrics/overview, /metrics/daily, /metrics/readiness-summary, and /insights/daily to show Garmin readiness scores, HRV, sleep, and training load.^[4][5] System and admin routers expose /system/refresh-today to trigger background refresh jobs and /admin/ingest to manually start metrics and insight ingestion.^[6][7] Auth routers expose /auth/google/login, /auth/google/callback, /auth/me, and /auth/logout for Google OAuth and session management.^{[8][9][10][11][12]}

On startup, the startup_event() initializes the database and runs any pending migrations.^[13] The SecurityHeadersMiddleware adds standard security headers like Content-Security-Policy and X-Frame-Options to every response.^[14]

Auth endpoints are rate-limited using a KVStore-backed counter per client IP that increments on each attempt and resets after a 60-second window, raising HTTP 429 if the limit of 10 is exceeded.^[15] The POST /api/morning/brief endpoint builds a prompt from readiness, events, tasks, and reads signals, calls OpenAIResponsesClient.generate_text() with temperature 0.4 and max tokens 220, and returns the generated paragraph or HTTP 502 on failure.^[16]

The /metrics/overview endpoint queries MetricsRepository.list_metrics_since() with a configurable range (1–365 days), caches the result for 5 minutes with a bounded LRU eviction policy, and returns averaged deltas for HRV, sleep, and training load.^[17][18] The GET /time router returns the current time in US Eastern timezone as ISO 8601 and a computed moment (morning, noon, twilight, or night) based on the hour.^[19]

The /auth router handles Google OAuth via _exchange_code_for_tokens() and _verify_id_token_async(), which are called by the google_callback() endpoint; it stores sessions in the database via create_user_session() and validates them per request with get_current_user().^{[20][21][10][22][23]}

Authentication starts when a client calls GET /auth/google/login with an optional redirect URL; the server sets OAuth state and remember-me cookies and redirects to Google's authorization endpoint.^[24] Google redirects back to GET /auth/google/callback with an authorization code; the server exchanges it for tokens, verifies the ID token, upserts the user in the database, and returns a session token cookie.^[25]

On each request, get_current_user() extracts the session token from cookies, looks it up in the database, and returns the associated user if the session has not been revoked.^[26] Metrics flow from Garmin via the background job queue into DailyMetric rows; the /metrics router fetches them from the database and caches the result.^[17] Morning brief requests carry readiness, events, tasks, and reads as JSON; the router assembles them into a prompt, sends it to OpenAI, and streams back a generated paragraph.^[27]

• The /health endpoint was added on 7 June 2026 and returns {"status": "ok"} to support Fargate readiness and liveness probes.^[28]
• The morning brief endpoint was implemented on 7 June 2026 to synthesize readiness, schedule, tasks, and reads into a single LLM-generated paragraph.^[29]
• On 4 June 2026, the API was refactored to use Mangum as the AWS Lambda handler and KVStore-backed caching and rate limiting to support serverless deployment.^[30][31]
• Google OAuth was added on 13 January 2026 to enable multi-user authentication with role-based access control (admin vs. user).^[32]
• Auth endpoints were hardened on 24 March 2026 with rate limiting, strict cookie attributes, CORS method and header restrictions, and disabled loguru diagnose to prevent secret leakage in error logs.^[33][34][35]