04 / ENGINEERING CASE STUDY
FitSpark
A workout planner that uses LangGraph and Pinecone RAG to generate weekly routines matched to your available equipment, adapting volume over time from logged workout history.
Data Ingestion Pipeline
A standalone Node.js pipeline on Cloud Build normalizes 800+ JSON exercises and shrinks images by 40% via `sharp` into GCS. It seeds NeonDB with the relational equipment catalog and Pinecone with vector embeddings.Zero Hallucination Verification
Zod enforces the JSON structure, while a programmatic `safetyEvaluator` node runs a strict JavaScript equality check against a `Set` built from the Pinecone RAG pool. Hallucinated exercises or injury risks trigger a graph retry.Automated Testing & Evals
Unit and E2E tested via Jest and Playwright. LangSmith runs LLM-as-a-judge evaluations (Gemini Flash) against the LangGraph state machine to strictly grade output for RAG hallucination and coach persona consistency.Serverless Container Deployment
A deployment script triggers Cloud Build to compile the Next.js app, package the Docker image into Artifact Registry, and deploy to Google Cloud Run. Secrets are securely injected at build time via Google Secret Manager.PRODUCT, IN PLAIN ENGLISH
FitSpark is a workout planner built on Next.js. Behind the scenes, it acts as a multi-agent AI fitness coach. Instead of relying on one massive, fragile prompt, it uses a state machine to map out your workout history and dynamically generate your next routine. It's backed by a custom Node.js ingestion pipeline that compresses 800+ exercise images via sharp into Google Cloud Storage, saves the relational data in NeonDB, and vectorizes the text into Pinecone. To keep the AI fast and reliable, a custom LangChain router automatically shifts inference traffic between Gemini Flash 3.6, 3.5, and 3.0.
REQUEST / EVENT LIFECYCLE
TECHNICAL ARCHITECTURE
How it is built.
A Next.js API route loads the user's history from NeonDB and initializes a LangGraph.js state machine. The `equipmentResolver` node filters Pinecone RAG results to match the user's home or gym equipment perfectly. The `muscleGapAnalyzer` and `skeletonArchitect` nodes design the weekly structure, then execute a Map-Reduce fan-out, spawning a concurrent `dailyPlanBuilder` agent for each day to cut latency. A LangChain LLM Router automatically routes inference between Gemini 3.6, 3.5, and 3.0 to manage rate limits.
FULL STACK / CLOUD / DEVOPS
The stack, organized
by responsibility.
Frontend & identity
Full Stack Next.js App Router, Tailwind, shadcn/ui. Clerk JWT auth protects routes. Handles interactive workout logging to feed progressive overload context.
AI planner & LLM Router
LangGraph.js Map-Reduce workflow. The LangChain LLM Router shifts traffic between Gemini Flash 3.6, 3.5, and 3.0. Pinecone handles vector search.
Data & media pipeline
800+ exercises normalized, NeonDB Postgres (serverless), Prisma ORM, Google Cloud Storage for compressed asset delivery.
GCP cloud architecture
Zero-downtime auto-scaling via Google Cloud Run. A one-click automated Cloud Build pipeline builds the Docker images, pushes them to Google Artifact Registry, and deploys to Cloud Run with GCP Secret Manager injecting zero-trust configs.
DevOps, Evals & Quality
Infrastructure in Terraform. Snyk secures dependencies. Playwright runs deterministic E2E simulations (Stripe, Auth). LangSmith and Jest evaluate RAG accuracy.
ENGINEERING DECISIONS
Why these choices matter.
FitSpark guarantees the LLM will not hallucinate workouts. The programmatic `safetyEvaluator` firewall extracts every generated exercise and runs a strict JavaScript equality check against an `allowedNames` Set built directly from the Pinecone RAG pool. If the LLM invents an exercise, it triggers a "RAG violation" and forces a graph retry. It also analyzes user injuries, blocking squats for bad knees. (Demo Tip: The Stripe checkout is in test mode - use card `4242 4242 4242 4242` with any future date).