FitnessHub

FitnessHub Project Documentation

Inspiration

We were inspired by the barrier to entry in fitness. Quality personal training costs $50-150 per session, putting professional guidance out of reach for most people. Generic workout apps don't account for individual needs—age-related joint concerns, dietary restrictions, or specific goals like strength vs. weight loss. We saw an opportunity to leverage Claude's advanced reasoning to democratize access to personalized, evidence-based fitness programming. Our vision was simple: everyone deserves a personal trainer, regardless of budget.

What it does

FitnessHub generates comprehensive 7-day workout and diet plans tailored to individual users in seconds. Users input four parameters—fitness goal (weight loss, strength, hypertrophy, yoga, or general fitness), training frequency (1-6 days/week), dietary preference (vegetarian, vegan, or non-vegetarian), and age. Claude AI then creates a complete plan with:

Daily workout schedules with specific exercises, sets, reps, and rest periods
Customized meal plans that respect dietary restrictions with protein guidance
Age-appropriate modifications (longer rest periods, joint-friendly exercises for 45+)
Goal-aligned programming (circuits for weight loss, heavy compounds for strength, volume for hypertrophy)

If the AI is unavailable, our intelligent fallback system instantly generates a science-backed plan, ensuring 100% uptime.

How we built it

Backend Architecture:

Built a Flask REST API with Python to handle user requests and orchestrate AI calls
Engineered detailed system prompts that instruct Claude to output strict JSON with safety constraints (rest periods 15-240s, sets 1-6)
Implemented Pydantic schemas with custom validators to normalize AI outputs—automatically clamping unsafe values and coercing type mismatches
Created a rule-based fallback system using exercise science principles (progressive overload, muscle group splits, macronutrient targets)

Frontend Design:

Developed a clean single-page interface with vanilla JavaScript for zero dependencies
Implemented tabbed navigation to separate workout and diet views
Designed a dark-themed, accessible UI with responsive layouts

Key Technical Decisions:

Chose Claude Haiku for speed and cost-efficiency (sub-second responses)
Used HTML table rendering server-side for simplicity and SEO
Stored no user data—fully stateless for privacy

Challenges we ran into

1. AI Output Reliability: Claude sometimes wrapped JSON in markdown code blocks (```json) or output invalid formats, causing parsing failures. We solved this by adding extensive error handling and Pydantic validators that strip markdown and normalize responses.

2. Safety Constraints: The AI occasionally suggested unsafe parameters like 0-second rest periods or 10+ sets per exercise. We implemented validator logic that automatically clamps values to evidence-based safe ranges without rejecting the entire plan.

3. Dietary Compliance: Ensuring strict adherence to dietary restrictions was critical—a vegan user receiving chicken recommendations would be unacceptable. We explicitly instructed Claude in the system prompt and added validation checks, with the fallback system using pre-vetted meal templates.

4. Age-Appropriate Programming: Older adults need modified training (longer rest, fewer high-impact movements). We encoded this both in AI prompts ("age >45 → joint-friendly options") and fallback logic (dynamic volume/rest calculation based on age).

5. Graceful Degradation: API failures couldn't leave users stranded. We built a sophisticated fallback that uses the same input parameters to generate scientifically-sound plans using pre-defined exercise splits, rep schemes, and meal templates.

Accomplishments that we're proud of

✅ 100% Uptime Guarantee: Our hybrid AI + rule-based system ensures users always get a usable plan, even during API outages or errors

✅ Safety-First Design: Automatic validation prevents unsafe training parameters that could lead to injury—every rest period, set count, and exercise is bounds-checked

✅ Real Personalization: Unlike template-based apps, our plans genuinely adapt to age (joint health), diet (strict compliance), and goals (rep schemes, exercise selection)

✅ Sub-Second Response Time: Users get complete 7-day plans in under 1 second thanks to Claude Haiku's speed

✅ Clean Architecture: Separation of concerns (prompt engineering, validation, rendering, fallback) makes the codebase maintainable and testable

✅ Accessibility: Free, no signup required, works on any device—truly democratizing fitness guidance

What we learned

Technical Insights:

Prompt engineering is critical: Small wording changes in system prompts drastically affected JSON compliance. We learned to be explicit about output format, use ALL CAPS for critical instructions, and provide concrete examples.
Defensive programming pays off: Validators that coerce and clamp rather than reject made the system resilient to AI quirks without sacrificing safety.
Fallbacks aren't just backups: Our rule-based system became a valuable feature for testing AI quality and ensuring consistency.

Domain Knowledge:

Exercise science is nuanced: We dove deep into periodization, volume landmarks (10-20 sets/muscle/week), rest period ranges by training goal, and age-related recovery needs.
Dietary restrictions are serious: Cultural and ethical food preferences require strict compliance—we learned to treat this as a safety issue, not just a feature.

Product Design:

Simple beats complex: Users want results fast. Four inputs → complete plan was more valuable than endless customization options.
Transparency builds trust: Showing when the fallback was used and exposing errors (in hackathon mode) helped users understand the system's reliability.

What's next for FitnessHub

Short-term (Next 3 months):

Progress Tracking: Allow users to log workouts and auto-adjust plans based on performance (progressive overload)
Exercise Library: Add video demonstrations and form cues for safety
Macronutrient Calculations: Provide specific calorie and macro targets based on TDEE and goals
Plan Export: Generate PDF downloads for gym use

Medium-term (6-12 months):

Multi-week Periodization: Generate 4-8 week training blocks with planned deloads and progression
Injury Accommodations: Allow users to specify limitations (e.g., "bad knee") and get modified exercises
Meal Prep Instructions: Include cooking directions and grocery lists
Mobile App: Native iOS/Android apps with offline mode

Long-term Vision:

Community Features: Users can share plans, rate effectiveness, and provide feedback to improve AI prompts
Wearable Integration: Import data from Apple Watch, Fitbit to auto-adjust training volume based on recovery metrics
Virtual Coaching: Multi-turn conversations with Claude for form checks, motivation, and answering fitness questions
Marketplace: Connect users with certified trainers for paid 1-on-1 sessions when they need human expertise

Monetization Strategy:

Keep basic plan generation free forever
Premium tier ($9.99/mo): progress tracking, unlimited plan regeneration, exercise videos, macro calculations
Enterprise/Gym licensing: White-label FitnessHub for fitness centers to offer members

Our ultimate goal: make professional-grade fitness guidance as accessible as asking a question to an AI. FitnessHub is just the beginning.