GainPath

What users get

• Unified product surfaces: Tracker, Workout, Profile, plus Food, Reporting, and Day views.
• A single health system where workout completion writes bridged activity events into shared energy totals.
• A mobile-first experience that still works when AI paths are unavailable or intentionally skipped.

Core behavior

• Chat orchestration persists structured records, recalculates totals, compares goals, and returns coaching plus missing-data prompts.
• Deterministic macro and calorie gauge services evaluate pace, daily status, and rolling 7-day patterns.
• Workout and food histories remain intentionally separate while feeding one coherent daily energy model.

AI augmentation

• One-call coach insight runs after deterministic recomputation and returns concise structured guidance.
• Food parsing supports item-level classification and tier-aware follow-up without forcing automatic lookup behavior.
• The database remains the source of truth, with AI supporting interpretation and language rather than replacing domain logic.

Operating model

• Vercel + Cloud Run + Neon gives a practical production stack with low operational overhead.
• Docker Compose supports full local iteration and reproducible environment setup.
• Import endpoints and docs exposure are explicitly gated by environment to reduce production risk.

Local-first product memory

The architecture uses Neon Postgres with local-first storage paths so the product can preserve user state reliably while staying responsive across web and future mobile clients. This design keeps durable memory at the center and avoids fragile, UI-only state patterns.

Feature isolation for faster iteration

The frontend is organized into route groups and feature-owned modules so changes stay localized instead of triggering broad rebuild risk. This reduces coupling across food, workout, reporting, and profile surfaces and keeps velocity high as the product grows.

Deterministic core with bounded AI

Totals, gauge status, and daily health logic run through deterministic services first. AI is used to interpret flexible input and phrase coaching output after structured calculations are complete, so essential behavior remains explainable, testable, and cost-aware.

Security and control boundaries

The app-facing boundary uses BFF patterns so backend credentials and verification stay server-side. Non-production import routes, environment-gated docs, and explicit auth boundaries keep operational risk lower while preserving development flexibility.

Guardrails for AI lookup

Food lookup is user-triggered, tier-aware, and staged before promotion into canonical food memory. Per-user rate limiting and anti-loop controls protect reliability and cost while still allowing AI-assisted enrichment when users choose it.