Gymflow
Adaptive Training Scheduler & AI Coaching Engine
01. Context & Overview
Gymflow is an adaptive training scheduler and autonomous AI coaching engine built to solve a recurring real-world problem: gym class timetables frequently change mid-week, requiring tedious manual schedule reshuffling around work commutes and fatigue.
The application connects live with a private gym scheduling API via a reverse-engineered OTP authentication bridge, detects schedule cancellations by diffing weekly timetable snapshots in Upstash Redis, and triggers a stateful Gemini agent to dynamically replan the week around real-world constraints—including Work From Office (WFO) commute shifts, systemic fatigue, fueling nutrition, and combat sports sessions (Kickboxing, BJJ, Boxing Conditioning).
Built with Next.js 15 App Router, TypeScript strict mode, and the Google GenAI SDK, Gymflow operates on a $0/month serverless footprint while supporting full offline testability through a mock fixture adapter (GYM_USE_MOCK=true).
02. The Constraints & Needs
Automating dynamic athletic scheduling with production LLMs introduces distinct architectural requirements:
- Reverse-Engineered Third-Party Ingestion: Gym scheduling APIs lack official public developer webhooks and rely on mobile OTP SMS auth. The backend must securely proxy OTP exchanges and manage 24-hour bearer tokens in Upstash Redis without leaking credentials to client browsers.
- Automated Mid-Week Timetable Diffing: Timetable shifts occur unexpectedly. Ingested live schedules (
/member/schedules/by-tier) must be diffed against weekly Redis snapshots to immediately isolate canceled or shifted training sessions. - Deterministic Agent Replanning: Free-form LLM chat output is too volatile for calendar mutations. The system requires deterministic tool calling (
replan_week_schedule,log_constraint) enforced by strict Zod schema contracts rather than unconstrained text generation. - Spec-Driven Architecture & Zero Operational Cost: Built following Spec-Driven Development (SDD) blueprints (
specs/) and verified against deterministic evaluation harnesses (evals/), all while running on edge serverless infrastructure with zero monthly hosting costs.
03. System Architecture & Data Flow
Gymflow coordinates authentication, timetable ingestion, snapshot diffing, and agent execution across a clean serverless pipeline:
[ Next.js 15 App Router (Frontend UI + Edge API) ]
│
▼ (HttpOnly Session)
┌──────────────────────────────────────────────────────────────┐
│ BACKEND SERVICES & ORCHESTRATION │
├──────────────────────────────────────────────────────────────┤
│ 1. Auth Bridge ──► Proxies OTP / Exchanges Bearer JWT │
│ 2. Gym Ingestion ──► Fetches /member/schedules/by-tier │
│ 3. Diff Engine ──► Detects mid-week class shifts │
│ 4. Agent Tool Runner ──► Executes structured LLM tool calls │
└──────────────┬───────────────────────────────┬───────────────┘
│ │
▼ ▼
[ Upstash Redis ] [ Google GenAI SDK ]
(Tokens, Cache, Snapshots) (Gemini 2.5/3 Pro & Flash)Gymflow Live Sync & Adaptive Replanning Pipeline
Proxies OTP verification, exchanges third-party bearer JWT, and delegates 24-hour token refresh into Upstash Redis.
Queries gym endpoints (/member/schedules/by-tier) or loads fixtures/ when running in offline mock mode (GYM_USE_MOCK=true).
Compares freshly fetched timetable against the weekly schedule snapshot in Redis, identifying canceled or shifted training slots.
Feeds detected diffs alongside WFO commute hours and fatigue constraints into Gemini Pro/Flash to invoke replan_week_schedule.
Persists updated training week state into Redis and re-renders adaptive calendar views and fueling recommendations.
04. Protocol & Sequence Lifecycle
The trace below illustrates how Gymflow detects a mid-week cancellation (e.g. Kickboxing canceled on Tuesday) and autonomously coordinates with the Gemini agent to replan around office commute hours:
Timetable Diffing & Dynamic Replanning Trace
05. Benchmark & Evaluation Matrix
Key architecture trade-offs evaluated across the Gymflow system design:
Gymflow Architecture Decisions & Trade-Offs
Comparative evaluation across design constraints and implementations
| Technical Decision | Alternative Approach | Chosen Solution | Result & Trade-Off |
|---|---|---|---|
| Timetable Sync Strategy | Direct client polling on every page view | Edge proxy + Redis diff engine with 24h token cache | Zero token leakage to client; isolates diffs before invoking LLM |
| Agent Replanning Execution | Free-form text generation | Deterministic tool calling (Zod + GenAI SDK) | 100% Valid schema compliance; eliminates time-slot hallucinations |
| Development & Testing Velocity | Direct dependency on private gym API credentials | Offline mock fixture adapter (GYM_USE_MOCK=true) | Fully reproducible local development and CI eval testing |
| Operating Footprint | Dedicated always-on server ($20–$40/mo) | Next.js 15 Serverless Edge + Upstash REST Redis | $0.00/mo operating footprint |
06. Key Engineering Learnings
- Enforce Deterministic Tool Calling Over Raw Text: For calendar and booking workflows, never rely on conversational text generation. Using structured function calls (
replan_week_schedule,log_constraint) paired with Zod contracts guarantees schema integrity. - State Diffing Preserves Explanatory Context: Comparing live API responses against cached snapshots before calling the LLM allows the system to articulate precisely why a replan occurred (e.g., “Tuesday Kickboxing canceled; shifted to Boxing Conditioning to accommodate 60m WFO commute”).
- Protect Private Third-Party Tokens: Never expose reverse-engineered bearer tokens to frontend clients. Maintain an HttpOnly session boundary and delegate token refreshes to an edge Redis store.
- Spec-Driven Blueprints and Mock Fixtures Enable Reliable Evals: Designing architectural blueprints in
specs/and running automated eval suites (npm run evalagainstevals/test-scenarios.json) ensures prompt iterations never break core scheduling invariants.