A TypeScript monorepo powering gAInplan — an AI-driven fitness coach that builds personalized workouts from your equipment, goals, and constraints, then guides you through set-by-set execution with real-time feedback.
Your gear. Your goals. Your plan — generated in seconds, grounded in a curated exercise database, and validated by a background audit agent before you train.
Source visibility: This repository is temporarily public for transparency and portfolio purposes. It is not open source — all rights are reserved, and no license is granted to use, copy, modify, or distribute the code. Third-party exercise data and imagery remain subject to their respective licenses; see Acknowledgments.
Onboarding with frictionless, anonymous start, plus email and social sign-in.
| Welcome screen | Sign in |
|---|---|
 |
 |
Four-step wizard to capture equipment, training focus, target area, and session details.
| Target area selection | Session details |
|---|---|
 |
 |
Streaming workflow progress, generated workout cards, and background audit verification.
| Live workflow stream | Audit-verified plan |
|---|---|
 |
 |
Guided execution with exercise imagery, set tracking, rest timers, and effort logging.
| Set-by-set tracking | Workout overview |
|---|---|
 |
 |
- 4-step planner wizard — equipment, training objectives, target area (with optional muscle-group refinement), duration, and free-form notes.
- Context-aware suggestions — target-area recommendations based on prior equipment selections.
- RAG-powered exercise retrieval — semantic search over a pgvector-indexed exercise catalog, constrained by available equipment.
- Structured output — every agent response validated through shared Zod schemas in
@repo/schema. - Live generation stream — NDJSON workflow events surfaced in the mobile UI (
plan→retrieve→compose).
- Detached audit workflow — critique agent evaluates duration and joint-safety constraints after the fast path returns.
- Smart repair loop — rejected exercises are swapped from the original movement pool without blocking the user.
- Realtime notifications — Supabase Realtime pushes audit results to the client when plans are updated.
- Durable outbox — Postgres-backed job queue with retries, dead-letter handling, and compensating scanner (no Redis required).
- Active workout mode — set-by-set progression with exercise imagery and coaching cues.
- Rest timer — automatic countdown between sets with optional progress capture.
- Effort & load logging — record actual reps, optional load (kg), and perceived effort per set.
- Session resume — pick up an in-progress workout from the overview screen.
- Workout completion — structured completion payloads persisted to the API.
- Frictionless onboarding — anonymous sessions with optional conversion to email, Google, or Apple sign-in.
- Profile preferences — equipment defaults and fitness level synced via authenticated API routes.
- Type-safe client — Hono RPC client shared between mobile and API for end-to-end TypeScript contracts.
gAInplan separates fast user-facing generation from slow background validation, orchestrated by Mastra workflows and specialized agents.
sequenceDiagram
participant User
participant App as Expo Mobile App
participant API as Hono API (Bun)
participant WF as generateWorkoutWorkflow
participant DB as Supabase (Postgres + pgvector)
participant LLM as LLM Provider
participant Outbox as Outbox Worker
participant Audit as backgroundAuditWorkflow
User->>App: Configure equipment, focus, target, duration, notes
App->>API: POST /api/v1/workout/generate-plan
API->>WF: plan → retrieve → compose
rect rgb(30, 40, 60)
note right of WF: Plan step
WF->>LLM: Planner agent — structural blueprint (movement patterns, sets, reps)
LLM-->>WF: Blueprint JSON
end
rect rgb(30, 50, 40)
note right of WF: Retrieve step
WF->>DB: pgvector hybrid search per movement pattern
DB-->>WF: Top-3 exercise candidates per pattern
end
rect rgb(50, 40, 30)
note right of WF: Compose step
WF->>LLM: Composer agent — select exercises from candidate pool
LLM-->>WF: Composed workout JSON
end
API->>DB: Persist draft workout (status: generated)
API->>Outbox: Enqueue audit job (best-effort)
API-->>App: Return workout immediately (~2–4s)
Outbox->>Audit: Critique → repair loop (if needed)
Audit->>LLM: Critique agent — duration & joint-safety audit
Audit->>DB: Update workout + audit metrics
DB-->>App: Realtime audit notification
| Agent | Role |
|---|---|
| Planner | Builds a biomechanical blueprint from user constraints — movement patterns, sets, and rep ranges — without naming specific exercises. |
| Composer | Selects exactly one database-backed exercise per pattern from the retrieved candidate pool and titles the session. |
| Critique | Audits the draft for duration overflow and joint/fatigue safety; flags specific exercises for replacement. |
- Never hallucinate exercises — the composer can only choose from pgvector-retrieved candidates with real database IDs.
- Return fast, validate async — users get a usable plan immediately; the audit agent refines it in the background.
- Shared contracts —
@repo/schemaZod types flow from API validation through agent structured output to the mobile client.
See also: docs/sequence-diagram-init.mmd, docs/sequence-diagram-outbox-worker.mmd, and apps/api/docs/outbox-worker-e2e.md.
| Layer | Technologies |
|---|---|
| Monorepo | Turborepo, Bun workspaces |
| Mobile | Expo 54, React Native, Expo Router, NativeWind, Zustand |
| API | Bun runtime, Hono, Drizzle ORM |
| Database | Supabase (Postgres, Auth, Realtime), pgvector |
| AI orchestration | Mastra, OpenAI embeddings & completions, structured output via Zod |
| Shared packages | @repo/schema (Zod contracts), @repo/ui, @repo/eslint-config, @repo/typescript-config |
| CI/CD | GitHub Actions, EAS Build for mobile |
kinetiq/
├── apps/
│ ├── mobile/ # gAInplan — Expo React Native app
│ ├── api/ # Hono API, Mastra workflows, outbox worker
│ ├── web/ # Next.js (scaffold)
│ └── docs/ # Next.js docs site (scaffold)
├── packages/
│ ├── schema/ # Shared Zod schemas & domain types
│ ├── ui/ # Shared React components
│ ├── eslint-config/
│ └── typescript-config/
├── assets/screenshots/ # App screenshots for documentation
└── docs/ # Architecture & sequence diagrams
- Bun
>= 1.3.14 - Node.js
>= 18 - Supabase project with Postgres + pgvector enabled
- OpenAI API key (embeddings + agent completions)
bun installCopy the example env files and fill in your own values:
cp apps/api/.env.example apps/api/.env
cp apps/mobile/.env.example apps/mobile/.envAt minimum the API requires:
DATABASE_URL,APP_USER_DATABASE_URLSUPABASE_URL,SUPABASE_ANON_KEY,SUPABASE_SERVICE_ROLE_KEYOPENAI_API_KEY,OPENAI_EMBEDDING_MODEL,OPENAI_COMPLETION_MODEL- Agent model overrides:
PLANNER_AGENT_MODEL,COMPOSE_AGENT_MODEL,CRITIQUE_AGENT_MODEL
See apps/api/.env.example and apps/mobile/.env.example for the full list of supported variables.
# Run all apps in parallel
bun run dev
# API only (http://localhost:4004)
bun run dev --filter=@kinetiq/api
# Mobile only
bun run dev --filter=mobilebun run lint
bun run check-types
bun run test:unitExercise data is imported from a JSON array matching the schema expected by the import script:
cd apps/api
bun run import:exercises ../exercise-data/exercises.json --dry-run
bun run import:exercises ../exercise-data/exercises.jsonSee apps/api/README.md for additional scripts (test tokens, embedding tests, planner agent debugging).
docker compose up --buildgAInplan would not be possible without the open datasets and tooling maintained by the following contributors.
Structured exercise metadata — names, muscle groups, equipment, instructions, and search summaries — is derived from the excellent free-exercise-db project by Jonas (@yuhonas), which in turn builds on the original exercises.json corpus by Ollie Jennings (@OllieJennings).
Thank you for making a high-quality, open exercise dataset available to the community.
Demonstration images shown during workouts are sourced from the free-exercise-db image collection and hosted via GitHub raw assets. gAInplan imports and stores these URLs alongside exercise records during the database seeding pipeline.
Thank you to Jonas and the upstream contributors who curated and published this imagery under an open license.
Planned and deferred work — not yet shipped, but on the radar:
- Workout library — evolve the Library tab from a component proving ground into a full saved-workout history with search and favorites.
- Progress analytics — volume tracking, trend charts, and longitudinal performance insights (surfaced on the welcome screen roadmap).
- Post-completion intelligence — async processing of completion data for adaptive coaching tips and preference learning.
- Expo home-screen widgets — glanceable active-session and rest-timer surfaces (noted in architecture diagrams).
- Retrieval tuning — dynamic pgvector similarity thresholds and optional force/mechanic filtering (push/pull, compound/isolation).
- Settings expansion — unit preferences (kg/lb), account deletion, and additional profile controls.
- Admin & recovery tooling — manual audit overrides and CDC-style catch-up for terminal audit states.
- Web client — production-ready Next.js experience beyond the current Turborepo scaffold.
All rights reserved. This repository is source-visible, not open source — no license is granted to use, copy, modify, or distribute the software. Third-party exercise data and imagery are subject to their respective open licenses; see Acknowledgments.