Engineering Audits & Changelog - Jashan-randhawa/AI-FitnessTracker1 GitHub Wiki

๐Ÿ“‘ Engineering Audits, RFCs & Changelog

This page documents the foundational engineering assessments, root-cause analyses (RCAs), security audits, and version release changelogs conducted on the FitTrack AI platform.

๐Ÿงญ Navigation

1. Release Changelog

Version 2.4.1 (2026-10-02) โ€” OAuth Callback Resilience, Mobile Chat Navigation & Profile Verification UI

  • ๐Ÿ›ก๏ธ Google OAuth Callback Single-Execution Guard: Frontend GoogleCallback utilizes a single-execution useRef lifecycle guard to eliminate duplicate OAuth code exchange triggers, timing-safe fragment scrubbing before React state changes, explicit URL parameter error code mapping (access_denied, google_state_invalid, oauth_failed), and an interactive fallback retry screen.
  • ๐Ÿ“ฑ Persistent Mobile Bottom Navigation & 100dvh Viewport: Bottom navigation bar remains anchored during FitBot AI Coach usage with smooth flex layout, dynamic 100dvh container height, safe-area inset protection, and blank prompt input placeholder.
  • โœ‰๏ธ Mobile Email Verification Layout & Symmetrical Sign-In Methods: Responsive mobile cards for authentication methods and email verification status chips (Verified / Pending Verification), 60s cooldown debouncing with live countdown timer, and unverified account alert banner.
  • ๐Ÿงช 139 Unit & Integration Tests Passing: 139/139 unit tests passing across 37 test suites with zero failures.

Version 2.4.0 (2026-10-01) โ€” Email Delivery Resilience (F1โ€“F5) & Profile Customization

  • ๐Ÿ›ก๏ธ 5-Layer Password Reset Resilience (F1โ€“F5):
    • F1 (Double-Click Interceptor): Synchronous useRef guard blocks rapid double-clicks on submit/resend before React state re-renders.
    • F2 (60s Token Debounce): Suppresses duplicate reset token generation and Brevo email dispatches if an active token was issued within 60 seconds, preserving the active link and avoiding inbox clutter.
    • F3 (Retry Hardening): Halts retry loops immediately on request timeouts to eliminate duplicate email dispatches after remote acceptance.
    • F4 (Distributed Rate Limiting): Atomic Redis rate limiting with automatic in-memory fallback.
    • F5 (Request Tracing): End-to-end requestId propagation across controllers, background dispatch, and security audit logs.
  • ๐Ÿ‘ค Profile Username Customization: Live username editing in Profile with length validation (3โ€“30 characters), case-insensitive MongoDB collision checks returning 409 Conflict, and zero-reload state synchronization.
  • ๐Ÿงช 134 Unit & Integration Tests Passing: 134/134 tests passing across 35 test suites with zero failures.

Version 2.3.0 (2026-10-01) โ€” Unified Dual Sign-In Architecture (Google OAuth + Password)

  • One Account, Two Sign-In Methods: Enables linking Google OAuth and standard password credentials to a single shared MongoDB record.
  • 6-Case Account Linking Matrix: Automated safe linking, mismatch rejection, and unverified account reclaiming.
  • Session Safety & Instant Revocation: Real-time token revocation on password change/reset via passwordChangedAt verification, plus 15-minute step-up authentication.
  • Unified Password Policy & History Prevention: Rolling 5-password history protection blocking password reuse.
  • Signup Email Verification Flow: Built-in 24-hour verification tokens with dedicated confirmation screens.

Version 2.1.0 (2026-09-28) โ€” Modular Packages & Resilient AI Architecture

  • ๐Ÿ“ฆ Modular Packages Ecosystem: Published 7 decoupled, production-grade npm packages to GitHub Packages under @jashan-randhawa/*:
    • @jashan-randhawa/openrouter-resilient-client
    • @jashan-randhawa/express-ai-guard
    • @jashan-randhawa/react-calendar-heatmap-streaks
    • @jashan-randhawa/react-workout-tracker
    • @jashan-randhawa/react-motion-presets
    • @jashan-randhawa/fitness-utils
    • @jashan-randhawa/ai-nutrition-estimator
  • ๐Ÿง  FitBot Voice & UX Upgrades: Integrated Speech-to-Text (STT) voice input and Web Speech API Text-to-Speech (TTS) read-aloud playback, instant AbortController generation stopping, native Markdown tables, collapsible plan cards, and audio completion chimes.
  • ๐Ÿ›ก๏ธ Backend Reliability: OPENROUTER_FALLBACK_MODEL failover to Gemini 2.0 Flash, dual-tier rate limiting (30 req/min IP + 20 req/min user-keyed), production error masking (MongoServerError), X-Request-Id UUID correlation tracing, and automated secret scrubbing.
  • ๐Ÿงช 91 Passing Unit Tests: 35 server tests (node --test) + 56 package tests (Vitest).

Version 2.0.1 (2026-09-27) โ€” Critical Security & Dependency Audit

  • Critical CVE Patch: Bumped jspdf to ^4.2.1 in client, pulling patched [email protected] and resolving confirmed critical XSS advisory in the dependency tree.
  • Multer Upgrade: Bumped multer from 1.4.x to 2.4.0 resolving disclosed denial-of-service (DoS) advisories.
  • Rate Limiting Hardening: Installed [email protected] across auth routes (5 req/15m), password reset (3 req/15m), AI endpoints (30 req/m), and YouTube search proxy (30 req/m).
  • OAuth Token Security: Replaced query-string token transfer with secure URL fragment (#access_token=) and POST body exchange.
  • Anti-Enumeration Password Recovery: Unified responses across non-existent accounts, third-party OAuth providers, and upstream email errors.

Version 2.0.0 (2026-09-12) โ€” Mobile Redesign & Architecture Upgrade

  • Fixed bottom navigation bar with active micro-animations.
  • Safe-area notch padding (viewport-fit=cover and dynamic .safe-area-pb classes).
  • Full-height 100dvh mobile chat viewports.
  • Frontend upgrades: React 19.2, TypeScript 5.9, Vite 7, and Tailwind CSS v4.

2. Report 1: CI Failure Root Cause Analysis & Verified Fix

Problem

GitHub Actions CI failed at the Run unit tests step on node --test test/**/*.test.js.

Confirmed Root Cause

  1. Runner Shell: GitHub Actions executes /usr/bin/bash without the non-default globstar option enabled. Because test files reside directly in server/test/, bash treated ** as a single * matching only subfolders.
  2. Node 20 Runtime: Native CLI glob parsing in node --test arguments was only introduced in Node.js 21.0.0 (#47653). Since CI pinned Node.js 20 LTS, Node treated the unmatched glob string as a literal missing file path.

Resolution

Updated the test script in server/package.json to a single-level wildcard expanded universally by POSIX shells:

"test": "node --test test/*.test.js"

Result: 17/17 tests passing cleanly across all Node LTS releases.

3. Report 2: Maintenance Plan Verification & Security Audit

All 18 maintenance and security items were verified via independent byte-for-byte local reproductions:

  • Zero-Vulnerability Baseline: npm audit across client and server confirms 0 known vulnerabilities.
  • OAuth Token Leak Protection: Fragment-based OAuth #access_token= prevents tokens leaking into browser history and HTTP Referer headers.
  • Rate Limiting Protection: express-rate-limit prevents brute force on auth and credit exhaustion on OpenRouter endpoints.
  • Production Error Masking: MongoServerError and Mongoose internals masked with generic client messages when NODE_ENV === 'production'.

4. Report 3: FitBot AI Assistant Review, Logging & Maintenance Plan

  • Transient Error Retries: 1โ€“2 retries with randomized exponential backoff on 429/5xx and network timeouts.
  • Automatic Model Failover: Automatic fallback to Gemini 2.0 Flash (OPENROUTER_FALLBACK_MODEL) on primary model hiccups.
  • Structured JSON Logging: Standardized JSON logs with automated secret scrubbing (passwords, tokens, API keys).
  • Request Tracing: Persistent X-Request-Id headers assigned to every incoming request.
  • Sliding-Window History Truncation: Enforced 50-message cap, 8,000-char single-message limit, and graceful truncation above 40,000 chars.

5. Report 4: Package Release Assessment & Modular Monorepo Plan

7 decoupled packages were evaluated across Cohesion, Coupling, Reusability, Testability, and Uniqueness, and extracted to GitHub Packages:

  • Generic contribution heatmap with 4-level color scales and timezone-safe streak calculations.
  • Headless workout session hook managing volume math, sets, and rest timers.
  • Resilient OpenRouter client with automated model failover and JSON parsing.
  • Accessible Framer Motion presets with OS-level reduced motion support.
  • Multi-entrypoint fitness math, speech/audio hooks, and multi-page PDF reporting.