Home

⚡ Welcome to the FitTrack AI Wiki

Welcome to the official developer documentation and technical wiki for FitTrack AI (Repository: Jashan-randhawa/AI-FitnessTracker1 • Live Demo: ai-fitness-tracker1.vercel.app).

FitTrack AI is a full-stack, intelligent health, nutrition, and fitness operating system powered by React 19.2, TypeScript 5.9, Tailwind CSS v4, Node.js (>=20.0.0), Express 4.19, MongoDB Atlas, and OpenRouter Generative AI.

---

🧭 Wiki Directory

Section	Description
🚀 Getting Started	Prerequisites, environment configuration, database setup, unit test execution, and local run guide
🏗️ Architecture & Tech Stack	System architecture, frontend/backend stack, rate limiting, CI/CD pipeline, and project layout
📦 Modular Packages	7 decoupled npm libraries published under @jashan-randhawa/* on GitHub Packages
📑 Engineering Audits & Changelog	Architecture audits, security reviews, CI failure RCA, and version release changelogs
🧠 AI Core & Features	FitBot personal coach, AI Food Snap (vision), NLP nutrition estimator, token guardrails, and planners
📊 Health Analytics & Tracking	Dynamic goal rings, interactive calendar heatmaps, activity streaks, net calories, and hydration
🏋️ Workout Studio & Media	In-app YouTube workout video streaming (authenticated proxy), Punjabi gym pump playlists, and weather/AQI
🔌 API Reference	Complete REST endpoint documentation, rate limit rules, request/response models, and JWT authentication
🌐 Deployment Guide	Production deployment strategies for Vercel, Render/Railway, MongoDB Atlas, and Brevo

---

⚡ System Architecture at a Glance

graph TD
    Client["Client (React 19.2 + TypeScript + Tailwind v4 + Vite 7)"]
    Server["Server (Node.js >=20 + Express 4.19 + Rate Limiter)"]
    DB[("Database (MongoDB Atlas)")]
    OpenRouter["OpenRouter AI (LLM / Multimodal Vision)"]
    OpenMeteo["Open-Meteo (Live Weather & AQI)"]
    Brevo["Brevo API (Transactional Password Reset)"]
    YouTube["RapidAPI (YouTube Video Streaming)"]

    Client -->|REST API / JWT Bearer| Server
    Client -->|Direct Weather Forecast & AQI| OpenMeteo
    Server -->|Mongoose 8 ODM| DB
    Server -->|Vision Analysis & FitBot Chat| OpenRouter
    Server -->|Password Reset Emails| Brevo
    Server -->|Workout Video Query| YouTube

Loading

---

🌟 Key Platform Highlights

• 🧠 Multimodal AI Vision & NLP: Upload a meal photo to calculate calories and macronutrients instantly via OpenRouter vision models, or describe meals in natural language.
• 💬 FitBot Context-Aware Coach: A personalized conversational coach referencing your daily calorie targets and workout metrics, fortified with exponential retries, automatic model fallback (OPENROUTER_FALLBACK_MODEL), in-memory query caching, sliding-window truncation, and Activity Planner JSON repair.
• 🔐 Unified Dual Sign-In Architecture (Google OAuth + Password): Sign in with Google, email + password, or both on a single unified account with automatic 6-case linking, security audit alerts, and single-execution useRef OAuth callback resilience with URL fragment scrubbing and explicit error handling.
• 🛡️ Brevo HTTPS Transactional Email with 5-Layer Resilience (F1–F5): Pure HTTPS Port 443 delivery with double-click interceptor, 60s active token debouncing, timeout disconnect safety, atomic Redis rate limiting, and end-to-end request tracing.
• ✉️ Signup & Profile Email Verification: 24-hour cryptographic verification tokens, anti-enumeration endpoints, 60-second rate-limited resend debouncing with live countdown timers, unverified account warning alerts, and mobile-responsive status chips (Verified / Pending Verification).
• 👤 Profile Customization & Sign-In Methods: Live editing of username with case-insensitive collision prevention, plus a symmetric mobile-responsive Sign-in Methods layout (Google Account link status + Password credentials + Email Verification).
• 📅 Interactive Calendar Heatmap: Contribution-style 90-day activity and nutrition heatmaps with 4-level color intensity scaling, streak tracking, and interactive date selection across Food Log and Activity Log.
• 🛡️ Hardened Security & Multi-Tier Rate Limiting: Dual-tier rate limiting (IP-based and per-user aiUserLimiter keyed on req.user.id), fragment-based Google OAuth token exchange (#access_token=), and generic anti-enumeration password reset flows.
• 📋 Structured Logging & Observability: Production JSON logger with secret scrubbing, X-Request-Id correlation tracing across all requests, Prometheus /metrics endpoint, and dedicated GET /api/health uptime and MongoDB connection monitoring.
• 📊 Responsive Health Analytics: Dynamic goal rings (Calories In, Calories Out, Active Minutes), activity streak tracker with confetti rewards, and interactive water intake log with quick-add volume presets.
• 📱 Mobile-First Architecture: Features a native-like fixed bottom navigation dock persisting cleanly across all views including FitBot AI Coach, dynamic 100dvh viewport height, safe-area insets (viewport-fit=cover), and responsive card layouts.
• 🏋️ Workout Studio & Punjabi Playlists: In-app embedded YouTube workout video player coupled with curated high-energy Punjabi gym pump mixes (Diljit Dosanjh, AP Dhillon, Sidhu Moosewala, Karan Aujla, Shubh).
• 🌤️ Outdoor Training Safety: Live Open-Meteo weather forecasts and real-time Air Quality Index (AQI) tracking for outdoor workouts.
• 📦 Modular Package Ecosystem: 7 standalone, decoupled npm libraries published under @jashan-randhawa/* on GitHub Packages.
• 🧪 Automated Testing & CI/CD: 139 unit and integration tests across 37 test suites running on Node's native test runner (node --test), backed by a dual-job GitHub Actions CI pipeline testing client builds and server syntax.