AI Core & Features

🧠 AI Core & Features

FitTrack AI embeds generative artificial intelligence into every facet of daily health management via OpenRouter multi-model endpoints.

---

🤖 1. FitBot Personal Coach (/ai-assistant)

FitBot is a context-aware conversational AI coach trained to act as an encouraging, knowledgeable certified fitness trainer and sports nutritionist.

Context Injection Architecture

FitBot does not treat each message in isolation. When you open a chat session, the server gathers:

1. User Profile Context: Current weight, height, age, target goal (e.g. Hypertrophy, Fat Loss, Endurance), and daily calorie budget.
2. Daily Metrics Context: Total calories consumed today, total calories burned, and net caloric deficit/surplus.
3. Conversation Memory: Preserved chat history stored in MongoDB under the Chat model.

This allows FitBot to answer questions like "What should I have for dinner?" with precision:

"Looking at your log, you've consumed 1,450 kcal and 90g of protein out of your 2,000 kcal target. I recommend a dinner with ~40g of protein, like grilled chicken breast with roasted sweet potatoes and asparagus (approx. 450 kcal)."

🎙️ Hands-Free & Modern UX Capabilities

• Voice Input (Speech-to-Text): Speak naturally into FitBot using the browser's native Web Speech API (SpeechRecognition). Includes microphone pulsing animations and automatic transcription append.
• Voice Readout (Text-to-Speech): Tap the speaker icon to listen to FitBot read workout routines or nutritional advice aloud via window.speechSynthesis. Automatically strips markdown formatting for a clean, natural vocal delivery.
• Stop Generation Control: Cancel in-flight AI responses instantly with an AbortController-backed Stop button, preventing unnecessary token usage when questions are refined.
• Rich Markdown Tables & Cards: Formats multi-day workout splits and macro tables into responsive Tailwind tables and collapsible plan cards.
• Inline Error Retry: If network connectivity drops or the server reboots, FitBot renders an inline error card with a one-click "Retry Request" button.
• One-Click Conversation Export: Download the complete coaching conversation and tailored fitness plans directly to your device as a formatted .md Markdown document.
• Synthesized Audio Completion Cue: Gentle dual-tone Web Audio API chime alerts the user when FitBot finishes responding, complete with a quick header mute/unmute toggle.
• Ultra-Smooth 60fps Experience: Message history items and token stream animations are strictly memoized (React.memo) to eliminate re-render stagger on past conversation turns.
• Persistent Mobile Navigation & 100dvh Docking: The bottom navigation bar (BottomNav) remains active and persistent during chat sessions, paired with dynamic 100dvh viewport management and an uncluttered prompt input bar.

🛡️ AI Resilience, Guardrails & Token Protection

To prevent quota exhaustion, provider downtime, or runaway LLM token bills, the /api/ai-assistant/chat pipeline incorporates multiple protective layers:

• Transient Error Retry: Built-in exponential backoff (1–2 retries with 500ms/1000ms delay) on network timeouts, provider hiccups, and 429/5xx status codes.
• Automated Model Fallback: Failover to secondary models via OPENROUTER_FALLBACK_MODEL (e.g. google/gemini-2.0-flash-001) if the primary model fails.
• Dual-Tier Rate Limiting:
  • Per-IP Protection: Capped at 30 requests per minute via aiLimiter.
  • Per-User Protection: Capped at 20 requests per minute keyed on req.user.id (aiUserLimiter) to prevent NAT exhaustion.
• Sliding-Window Message Truncation: Bounded to the most recent 50 messages and 40,000 total characters without crashing ongoing sessions.
• In-Memory Query Cache: 5-minute TTL cache on identical prompt hashes to conserve API credits.
• Activity Planner JSON Repair Retry: Automated validation checking that model output is parseable JSON; if invalid, executes a repair prompt to ensure structured multi-day plans never fail.
• Graceful Degradation: On complete upstream outages, returns an operational 503 Service Unavailable with friendly status advice rather than exposing raw internal stack traces.

---

📸 2. AI Food Snap (Vision Analysis)

Upload or capture a photo of any meal directly from your smartphone or desktop:

• Endpoint: POST /api/image-analysis (Rate-limited: 20 req/min)
• Pipeline:
  1. The image is processed through Multer memory storage (2.4.x).
  2. The buffer is converted to a base64 Data URI.
  3. Dispatched to OpenRouter's vision models (such as openai/gpt-4o-mini or google/gemini-flash).
  4. The model identifies dish components, estimates portion sizes, and returns structured JSON containing:
     • Identified Dish Name
     • Estimated Calories (kcal)
     • Macronutrients: Protein (g), Carbohydrates (g), and Fats (g)
  5. The UI automatically populates the Food Log form, allowing one-tap verification and saving.

---

📝 3. Natural Language Nutrition Estimator

Type free-form meal descriptions into the Food Log:

• Example Input: "2 scrambled eggs with 2 slices of whole wheat toast and half an avocado"
• Endpoint: POST /api/food-estimate (Rate-limited: 20 req/min)
• Response: The LLM parses individual food items, aggregates weights, and returns structured nutritional totals.

---

🗓️ 4. Adaptive Workout & Meal Planners

AI Workout Planner (/activity-planner)

Generates tailored 3, 5, or 7-day workout splits based on:

• Training Focus: Fat Loss, Strength & Hypertrophy, Endurance, Balanced, or Mobility.
• Equipment Access: Full Gym, Home Dumbbells, or Bodyweight-Only.
• Fitness Level: Beginner, Intermediate, or Advanced.

AI Meal Planner (/meal-planner)

Constructs structured multi-day dietary plans matching caloric targets and dietary restrictions (Vegetarian, Vegan, Keto, High-Protein) with 1-Click Add to Log functionality.