Home - Jashan-randhawa/AI-FitnessTracker1 GitHub Wiki

โšก 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](/Jashan-randhawa/AI-FitnessTracker1/wiki/Engineering-Audits-and-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

๐ŸŒŸ 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.