Skip to content

Somil450/spectrax_1

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

320 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

🎯 SpectraX

AI-Powered Fitness Tracker & Real-Time Pose Visualization

GSSoC 2026 TypeScript React Three.js Socket.io Firebase Vite License: MIT

An advanced AI-driven fitness companion that tracks workouts, analyzes form in real time, and visualizes your body in 3D β€” all from a browser webcam. No wearables, no external hardware.

Proudly participating in GirlScript Summer of Code 2026!

Features Β· Demo Β· Quick Start Β· Architecture Β· Tech Stack Β· Contributing Β· FAQ


πŸ“– Overview

SpectraX is a full-stack fitness application that uses MediaPipe Pose Detection, Three.js, and WebSockets to deliver real-time workout tracking, intelligent form analysis, and immersive 3D body visualization β€” entirely in the browser.

It doesn't just track your body; it understands your movement. SpectraX counts reps, detects which exercise you're performing, scores your form, identifies anomalies with ML algorithms, and renders a live 3D skeleton that mirrors your every move.

Why SpectraX?

Traditional Fitness Trackers SpectraX
Requires wearable hardware Uses only a webcam
Basic step/heart-rate counting Intelligent rep counting with form scoring
Manual exercise logging Auto-detects exercise type via AI
2D dashboards Real-time 3D body skeleton visualization
No posture feedback Real-time posture correction & anomaly detection

✨ Features

Core Workout Engine

Feature Description
πŸ‹οΈ Intelligent Rep Counting Automatically counts reps for squats, push-ups, bicep curls, shoulder press, lunges, flutter kicks, and more
πŸ“ Real-Time Form Analysis Scores each rep based on joint angles and posture accuracy
πŸ” Auto-Exercise Detection AI classifies which exercise you're performing without manual selection
πŸŽ₯ 3D Body Mapping Real-time skeleton rendered with Three.js and WebGL, with dynamic joint-angle vector shaders

Intelligent Feedback

Feature Description
🧠 Anomaly Detection Pure-TypeScript ML engine (Z-Score, Modified Z-Score, Isolation Forest) flags form deviations
πŸ’¬ AI Recommendations Post-workout improvement suggestions powered by the feedback engine
🎯 Biomechanical Stress Visualization Volumetric fog and stress-vector shaders highlight muscle engagement during replay

Tracking & Gamification

Feature Description
πŸ“Š Workout Summary Post-session analytics with rep streaks, duration, calorie estimates, and accuracy breakdowns
πŸ”„ Session Replay Review your workout with full 3D replay, complete with camera orbit controls locked to pelvis tracking
πŸ† Badge & Achievement System Earn trophies and track workout streaks
πŸ“ˆ Leveling System Gain XP and level up as you work out consistently

Platform & Infrastructure

Feature Description
⚑ Real-Time Sync Low-latency WebSocket communication with authenticated socket connections, rate limiting, and CORS hardening
πŸ” Firebase Auth Full authentication flow (signup, login, forgot password) with App Check anti-abuse protection
πŸ“΄ Offline Support PWA with service worker caching and offline queue for workout data
πŸ–₯️ FPS Monitoring Built-in performance overlay with adaptive throttling for lower-end devices

πŸ“Έ Screenshots

Welcome Screen

Welcome Screen Initialize your session, sign in, or browse workout history.

Exercise Selection β€” Bodyweight Squats

Squats Select from multiple exercises with live camera preview.

Exercise Selection β€” Bicep Curls

Bicep Curls Real-time pose detection ready for bicep curl tracking.

Exercise Selection β€” Plank

Plank Plank hold detection with live camera feed.

Exercise Selection β€” Push-Ups

Push-Ups Push-up rep counting with form analysis.

Session History

Session History Review past workout sessions and track your progress over time.


🧠 Architecture

graph TB
    subgraph Browser["Browser - Client"]
        CAM["Webcam Feed"]
        MP["MediaPipe Pose - 33 Landmarks"]
        EE["Exercise Engine - Rep Counting and Form Scoring"]
        AD["Anomaly Detection - Z-Score / MAD / Isolation Forest"]
        THREE["Three.js Renderer - 3D Skeleton + Shaders"]
        UI["React 18 UI - Workout / Summary / Replay"]
        SW["Service Worker - PWA + Offline Queue"]
        FB["Firebase Auth + Firestore"]
    end

    subgraph Server["Backend - Node.js"]
        EXPRESS["Express.js - REST API + Health"]
        SOCKET["Socket.io - Real-Time Sync"]
        PROC["Pose Processor - Angle Calculations"]
        FEED["Feedback Engine - Recommendations"]
        STORE["Session Storage - File-Based"]
    end

    CAM --> MP
    MP --> EE
    EE --> AD
    EE --> THREE
    EE --> UI
    AD --> UI
    THREE --> UI
    UI --> SW
    UI --> FB
    UI <--> SOCKET
    SOCKET <--> PROC
    PROC --> FEED
    PROC --> STORE
    EXPRESS --> STORE
Loading

Data Flow

  1. πŸ“· Capture β€” Camera frames are captured in real time via the browser's MediaDevices API
  2. 🦴 Pose Estimation β€” MediaPipe Pose extracts 33 body landmarks with 3D coordinates
  3. πŸ“ Angle Calculation β€” Joint angles are computed using landmark coordinates (with optional GPU-accelerated calculations)
  4. πŸ€– Exercise Classification β€” AI logic auto-detects the current exercise using the activity classification service
  5. πŸ”’ Rep Counting β€” State-machine-based algorithms track movement cycles with depth classifiers per exercise
  6. 🎯 Form Scoring β€” Posture accuracy is evaluated in real time; anomaly detection flags deviations post-session
  7. πŸŽ₯ 3D Rendering β€” Three.js renders a live skeleton with volumetric fog and biomechanical stress shaders
  8. ⚑ Sync β€” Socket.io synchronizes workout data between client and server with auth, rate limiting, and CORS hardening

πŸ› οΈ Tech Stack

Category Technologies
Frontend React 18, TypeScript, Vite
3D Rendering Three.js, WebGL, GLSL Shaders
AI / ML MediaPipe Pose, Transformers.js (@xenova/transformers)
Backend Node.js, Express.js, Socket.io
Auth & Database Firebase Auth, Firestore, Firebase App Check
State Management React Context API, Custom Hooks
Testing Vitest, React Testing Library, Supertest
CI / CD GitHub Actions (Node 20.x, 22.x)
PWA vite-plugin-pwa, Workbox
Deployment Vercel (frontend), configurable backend
Styling Vanilla CSS with modular component styles
Icons Lucide React

πŸ“ Project Structure

spectrax_1/
β”œβ”€β”€ public/                          # Static assets
β”‚   β”œβ”€β”€ assets/demos/                #   Exercise demo videos (squat, pushup, plank, etc.)
β”‚   β”œβ”€β”€ favicon.svg                  #   App icon
β”‚   β”œβ”€β”€ icons.svg                    #   UI icon sprites
β”‚   └── model.glb                    #   3D body model for skeleton rendering
β”‚
β”œβ”€β”€ assets/                          # Project assets
β”‚   └── screenshots/                 #   App screenshots for documentation
β”‚
β”œβ”€β”€ src/                             # Frontend source
β”‚   β”œβ”€β”€ components/                  # React components
β”‚   β”‚   β”œβ”€β”€ WorkoutScreen.tsx        #   Main workout view with camera + pose
β”‚   β”‚   β”œβ”€β”€ CalibrationScreen.tsx    #   Pre-workout body alignment
β”‚   β”‚   β”œβ”€β”€ SummaryScreen.tsx        #   Post-workout analytics
β”‚   β”‚   β”œβ”€β”€ SummaryScreenSkeleton.tsx#   Skeleton loader for summary
β”‚   β”‚   β”œβ”€β”€ ReplayScreen.tsx         #   Session replay UI
β”‚   β”‚   β”œβ”€β”€ Replay3DModel.tsx        #   3D replay with stress shaders
β”‚   β”‚   β”œβ”€β”€ WelcomeScreen.tsx        #   Landing / exercise selection
β”‚   β”‚   β”œβ”€β”€ LoginScreen.tsx          #   Login screen
β”‚   β”‚   β”œβ”€β”€ SignUpScreen.tsx         #   Registration screen
β”‚   β”‚   β”œβ”€β”€ ForgotPasswordScreen.tsx #   Password recovery
β”‚   β”‚   β”œβ”€β”€ UserProfileScreen.tsx    #   User profile view
β”‚   β”‚   β”œβ”€β”€ FitnessCalculator.tsx    #   BMI / calorie calculator
β”‚   β”‚   β”œβ”€β”€ TrophyRoom.tsx           #   Badge & achievement display
β”‚   β”‚   β”œβ”€β”€ AIRecommendations.tsx    #   AI workout suggestions
β”‚   β”‚   β”œβ”€β”€ BadgeNotification.tsx    #   Badge popup notifications
β”‚   β”‚   β”œβ”€β”€ CursorGlow.tsx           #   Cursor glow effect
β”‚   β”‚   β”œβ”€β”€ FpsMonitor.tsx           #   FPS performance monitor
β”‚   β”‚   β”œβ”€β”€ FpsOverlay.tsx           #   FPS overlay display
β”‚   β”‚   β”œβ”€β”€ ScrollToTopButton.tsx    #   Scroll-to-top button
β”‚   β”‚   β”œβ”€β”€ WorkoutPanels.tsx        #   Workout info panels
β”‚   β”‚   β”œβ”€β”€ HistoryPageSkeleton.tsx  #   Skeleton loader for history
β”‚   β”‚   β”œβ”€β”€ EmptyState.tsx           #   Empty state placeholder
β”‚   β”‚   β”œβ”€β”€ NotFound.tsx             #   404 page
β”‚   β”‚   β”œβ”€β”€ ProtectedRoute.tsx       #   Auth route guard
β”‚   β”‚   β”œβ”€β”€ CameraErrorBoundary.tsx  #   Camera error handling
β”‚   β”‚   └── PageErrorBoundary.tsx    #   Page-level error boundary
β”‚   β”‚
β”‚   β”œβ”€β”€ services/                    # Core business logic
β”‚   β”‚   β”œβ”€β”€ exerciseEngine.ts        #   Rep counting & form scoring
β”‚   β”‚   β”œβ”€β”€ poseService.ts           #   MediaPipe pose processing
β”‚   β”‚   β”œβ”€β”€ cameraService.ts         #   Camera initialization & management
β”‚   β”‚   β”œβ”€β”€ sessionRecorder.ts       #   Workout recording & serialization
β”‚   β”‚   β”œβ”€β”€ gestureService.ts        #   Gesture recognition
β”‚   β”‚   β”œβ”€β”€ calibrationStateEngine.ts#   Calibration state machine
β”‚   β”‚   β”œβ”€β”€ calibrationLogic.ts      #   Calibration calculations
β”‚   β”‚   β”œβ”€β”€ calibrationVisualRenderer.ts #  Calibration overlay rendering
β”‚   β”‚   β”œβ”€β”€ occlusionPredictor.ts    #   Landmark occlusion handling
β”‚   β”‚   β”œβ”€β”€ kinematicEngine.ts       #   Motion kinematics
β”‚   β”‚   β”œβ”€β”€ volumetricFogEngine.ts   #   3D volumetric fog shader engine
β”‚   β”‚   β”œβ”€β”€ volumetricFogShaders.ts  #   GLSL shader definitions
β”‚   β”‚   β”œβ”€β”€ workoutSyncService.ts    #   Client-server sync logic
β”‚   β”‚   β”œβ”€β”€ angleUtils.ts            #   Joint angle calculations
β”‚   β”‚   β”œβ”€β”€ gpuAngleUtils.ts         #   GPU-accelerated angle utils
β”‚   β”‚   β”œβ”€β”€ overlayRenderer.ts       #   Canvas overlay rendering
β”‚   β”‚   β”œβ”€β”€ clipEngine.ts            #   Workout clip engine
β”‚   β”‚   β”œβ”€β”€ bodyTypeEngine.ts        #   Body type detection
β”‚   β”‚   β”œβ”€β”€ skeletalSense.ts         #   Skeletal awareness logic
β”‚   β”‚   β”œβ”€β”€ ghostService.ts          #   Ghost overlay service
β”‚   β”‚   β”œβ”€β”€ poseLockService.ts       #   Pose lock detection
β”‚   β”‚   β”œβ”€β”€ syncQueue.ts             #   Data sync queue
β”‚   β”‚   β”œβ”€β”€ performanceThrottleService.ts #  Adaptive performance throttling
β”‚   β”‚   β”œβ”€β”€ activityClassificationService.ts # Exercise auto-detection
β”‚   β”‚   β”œβ”€β”€ wristRotationDetector.ts #   Wrist rotation tracking
β”‚   β”‚   β”œβ”€β”€ Squat_depth_classifier.ts#   Squat depth classification
β”‚   β”‚   └── Pushup_depth_classifier.ts #  Push-up depth classification
β”‚   β”‚
β”‚   β”œβ”€β”€ engine/                      # AI engines
β”‚   β”‚   β”œβ”€β”€ feedbackEngine.ts        #   Post-workout feedback generation
β”‚   β”‚   └── recommendationEngine.ts  #   AI-driven workout recommendations
β”‚   β”‚
β”‚   β”œβ”€β”€ hooks/                       # Custom React hooks
β”‚   β”‚   β”œβ”€β”€ useCameraPose.ts         #   Camera + pose detection lifecycle
β”‚   β”‚   β”œβ”€β”€ useWorkoutSync.ts        #   WebSocket workout sync
β”‚   β”‚   β”œβ”€β”€ useWorkoutWebSocket.ts   #   WebSocket connection management
β”‚   β”‚   β”œβ”€β”€ useBadges.ts             #   Achievement tracking
β”‚   β”‚   β”œβ”€β”€ useLeveling.ts           #   XP & level progression
β”‚   β”‚   β”œβ”€β”€ useNetworkStatus.ts      #   Online/offline detection
β”‚   β”‚   β”œβ”€β”€ useAuth.ts               #   Firebase auth hook
β”‚   β”‚   β”œβ”€β”€ useDisplayConfig.ts      #   Display/resolution config
β”‚   β”‚   β”œβ”€β”€ useFpsCounter.ts         #   FPS counting hook
β”‚   β”‚   β”œβ”€β”€ useOffscreenCanvas.ts    #   Offscreen canvas management
β”‚   β”‚   └── usePrefersReducedMotion.ts #  Reduced motion preference
β”‚   β”‚
β”‚   β”œβ”€β”€ workers/                     # Web Workers (off-main-thread)
β”‚   β”‚   β”œβ”€β”€ poseWorker.ts            #   Pose processing worker
β”‚   β”‚   └── activityWorker.ts        #   Activity classification worker
β”‚   β”‚
β”‚   β”œβ”€β”€ context/                     # React Context providers
β”‚   β”‚   β”œβ”€β”€ AuthContext.tsx           #   Firebase auth state
β”‚   β”‚   β”œβ”€β”€ SettingsContext.tsx       #   User preferences
β”‚   β”‚   └── ThemeContext.tsx          #   Dark/light theme
β”‚   β”‚
β”‚   β”œβ”€β”€ config/                      # Configuration
β”‚   β”‚   β”œβ”€β”€ exercises.ts             #   Exercise definitions & parameters
β”‚   β”‚   β”œβ”€β”€ firebase.ts              #   Firebase initialization
β”‚   β”‚   β”œβ”€β”€ badges.ts                #   Badge definitions
β”‚   β”‚   └── poseLandmarks.ts         #   MediaPipe landmark indices
β”‚   β”‚
β”‚   β”œβ”€β”€ utils/                       # Utility functions
β”‚   β”‚   β”œβ”€β”€ fitnessCalculations.ts   #   BMI, BMR, calorie math
β”‚   β”‚   β”œβ”€β”€ calorieEstimator.ts      #   Per-exercise calorie estimation
β”‚   β”‚   β”œβ”€β”€ streakUtils.ts           #   Workout streak logic
β”‚   β”‚   β”œβ”€β”€ offlineQueue.ts          #   Offline data queue
β”‚   β”‚   β”œβ”€β”€ avatarSkins.ts           #   Avatar skin definitions
β”‚   β”‚   β”œβ”€β”€ badgeIcons.ts            #   Badge icon mappings
β”‚   β”‚   └── debounce.ts              #   Debounce utility
β”‚   β”‚
β”‚   β”œβ”€β”€ assets/                      # Frontend assets (images, SVGs)
β”‚   β”œβ”€β”€ styles/                      # CSS modules
β”‚   β”‚   β”œβ”€β”€ app.css                  #   Global app styles
β”‚   β”‚   β”œβ”€β”€ auth.css                 #   Authentication page styles
β”‚   β”‚   β”œβ”€β”€ WelcomeScreen.css        #   Welcome screen styles
β”‚   β”‚   └── FitnessCalculator.css    #   Calculator styles
β”‚   β”‚
β”‚   β”œβ”€β”€ types/                       # TypeScript type definitions
β”‚   β”‚   └── badge.ts                 #   Badge type interfaces
β”‚   β”‚
β”‚   β”œβ”€β”€ App.tsx                      # Root app with routing
β”‚   β”œβ”€β”€ HistoryPage.tsx              # Workout history page
β”‚   β”œβ”€β”€ SessionCard.tsx              # Session card component
β”‚   β”œβ”€β”€ useWorkoutHistory.ts         # Workout history hook
β”‚   β”œβ”€β”€ main.tsx                     # React entry point
β”‚   β”œβ”€β”€ index.css                    # Global CSS
β”‚   └── style.css                    # Additional global styles
β”‚
β”œβ”€β”€ server/                          # Backend
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ index.js                 #   Server entry point
β”‚   β”‚   β”œβ”€β”€ app.js                   #   Express app setup
β”‚   β”‚   β”œβ”€β”€ app/                     #   App factory (createApp, createServer)
β”‚   β”‚   β”œβ”€β”€ socket/                  #   Socket.io event handlers
β”‚   β”‚   β”œβ”€β”€ modules/                 #   Pose processing, sessions, feedback
β”‚   β”‚   β”œβ”€β”€ middleware/              #   Auth, rate limiting, CORS
β”‚   β”‚   β”œβ”€β”€ shared/                  #   Shared constants & utilities
β”‚   β”‚   └── config/                  #   Server configuration
β”‚   β”‚
β”‚   β”œβ”€β”€ sessions/                    #   Session data storage
β”‚   β”œβ”€β”€ tests/                       #   Backend tests (unit + integration)
β”‚   β”œβ”€β”€ index.js                     #   Root entry (re-exports src/index.js)
β”‚   β”œβ”€β”€ .env.example                 #   Backend env template
β”‚   β”œβ”€β”€ README.md                    #   Backend documentation
β”‚   β”œβ”€β”€ package.json                 #   Backend dependencies
β”‚   └── vitest.config.js             #   Backend test config
β”‚
β”œβ”€β”€ spectrax_anomaly/                # Anomaly detection module
β”‚   β”œβ”€β”€ src/                         #   Z-Score, MAD, Isolation Forest algos
β”‚   └── INTEGRATION.md              #   Integration guide
β”‚
β”œβ”€β”€ scripts/                         # Utility scripts
β”‚   β”œβ”€β”€ setup_labels.sh              #   GitHub label setup script
β”‚   └── verify-theme-security.js     #   Theme security verification
β”‚
β”œβ”€β”€ .github/
β”‚   β”œβ”€β”€ workflows/ci.yml             # CI pipeline (lint, build, test)
β”‚   β”œβ”€β”€ ISSUE_TEMPLATE/              # Issue templates (bug, feature, GSSoC task)
β”‚   └── pull_request_template.md     # PR template
β”‚
β”œβ”€β”€ firestore.rules                  # Firestore security rules
β”œβ”€β”€ firestore.indexes.json           # Firestore index definitions
β”œβ”€β”€ firebase.json                    # Firebase project config
β”œβ”€β”€ vercel.json                      # Vercel deployment config
β”œβ”€β”€ vite.config.ts                   # Vite + PWA + SharedArrayBuffer config
β”œβ”€β”€ tsconfig.json                    # TypeScript configuration
β”œβ”€β”€ tsconfig.node.json               # TypeScript config for Node
β”œβ”€β”€ index.html                       # HTML entry point
β”œβ”€β”€ jest.config.cjs                  # Jest configuration
β”œβ”€β”€ .eslintrc.cjs                    # ESLint configuration
└── package.json                     # Dependencies & scripts

πŸš€ Quick Start

Prerequisites: Node.js v18.x or higher, npm

# 1. Clone the repository
git clone https://github.com/Somil450/spectrax_1.git
cd spectrax_1

# 2. Install frontend dependencies
npm install

# 3. Install backend dependencies
cd server && npm install && cd ..

# 4. Set up environment variables (see below)

# 5. Start the backend (Terminal 1)
cd server && npm run dev

# 6. Start the frontend (Terminal 2)
npm run dev

The frontend runs at http://localhost:5173 and the backend at http://localhost:3001.


πŸ” Environment Variables

Frontend (.env in project root)

Copy .env.example and fill in your Firebase credentials:

# Firebase Configuration (from Firebase Console)
VITE_FIREBASE_API_KEY=your_api_key_here
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

# Firebase App Check β€” reCAPTCHA Enterprise site key (optional, leave empty for local dev)
VITE_APPCHECK_RECAPTCHA_KEY=

# Backend URL (client derives WebSocket URL by swapping http β†’ ws)
VITE_BACKEND_URL=http://localhost:3001

Backend (.env in server/ directory)

PORT=3001
ALLOWED_ORIGIN=http://localhost:5173

⚠️ Never commit .env files to version control. The .env.example file is provided as a template.

Firebase Setup

  1. Create a project at Firebase Console
  2. Enable Authentication (Email/Password provider)
  3. Create a Firestore database
  4. Copy your project config into the .env file
  5. Deploy Firestore security rules:
npm install -g firebase-tools
firebase login
firebase deploy --only firestore:rules

Without deploying these rules, the project runs in Firebase test mode (open access). Always deploy them before going to production.


πŸ’» Usage

Workout Flow

  1. Welcome β€” Choose an exercise or let SpectraX auto-detect it
  2. Calibration β€” Align yourself with the camera for optimal pose tracking
  3. Workout β€” Exercise in real time! Watch reps count up, form scores update, and your 3D skeleton mirror your movement
  4. Summary β€” Review detailed post-workout analytics: rep streaks, duration, calorie burn, accuracy breakdown, and AI-generated improvement tips
  5. Replay β€” Re-watch your session in full 3D with biomechanical stress overlays

πŸƒ Supported Exercises

Exercise Detection Rep Counting Depth Classifier
Bodyweight Squats βœ… βœ… βœ…
Push-Ups βœ… βœ… βœ…
Bicep Curls βœ… βœ… β€”
Shoulder Press βœ… βœ… β€”
Lunges βœ… βœ… β€”
Flutter Kicks βœ… βœ… β€”
Plank (Hold) βœ… ⏱️ Timer β€”

🚧 Planned

  • Jumping Jacks
  • Mountain Climbers
  • Burpees

πŸ“Š Performance

Metric Value
Pose Detection FPS ~30 FPS
Rep Counting Accuracy ~94%
Detection Latency <100ms
Supported Resolution 720p / 1080p
Pose Landmarks 33 Keypoints (3D)
Web Workers 2 (pose + activity classification)

Performance varies by device hardware, lighting conditions, and camera quality. The built-in FPS monitor and adaptive throttle service help maintain smooth performance on lower-end devices.


πŸ“± Browser Compatibility

Browser Support
Chrome (Desktop) βœ… Full Support
Edge βœ… Full Support
Firefox βœ… Full Support
Android Chrome βœ… Full Support
Safari / iOS ⚠️ Experimental

Note: SpectraX requires SharedArrayBuffer support (via Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy headers), which is configured automatically in both the Vite dev server and Vercel deployment.


πŸ§ͺ Testing

# Run frontend tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run lint checks
npm run lint

# Run backend tests
cd server && npm test

The project uses Vitest with jsdom for frontend tests and React Testing Library for component testing. The backend uses Vitest with Supertest for HTTP endpoint testing.

CI runs automatically on push/PR to main via GitHub Actions, testing against Node 20.x and 22.x.


🚒 Deployment

Frontend (Vercel)

The project includes a vercel.json with:

  • SPA rewrites (all routes β†’ index.html)
  • Required COOP/COEP headers for SharedArrayBuffer
  • Service worker cache control

Deploy with:

npx vercel

Backend

The backend is a standalone Express + Socket.io server. Deploy to any Node.js-compatible platform (Railway, Render, Fly.io, etc.) and set the ALLOWED_ORIGIN env var to your frontend URL.


πŸ—ΊοΈ Roadmap

  • AI-based calorie estimation improvements
  • Multi-person pose tracking
  • Voice-guided workout assistant
  • Native mobile application
  • Cloud workout history sync
  • Workout recommendation engine
  • Advanced analytics dashboard with charts
  • Social features (workout sharing, leaderboards)

🀝 Contributing

SpectraX is a GSSoC 2026 project and we welcome contributors of all experience levels!

  1. Read the Contributing Guide and Code of Conduct
  2. Find an issue β€” Check open issues for good first issue, level1, level2, or level3 labels
  3. Follow the workflow:
    # Fork & clone
    git clone https://github.com/YOUR_USERNAME/spectrax_1.git
    cd spectrax_1
    
    # Create a feature branch
    git checkout -b feature/your-feature-name
    
    # Make changes, test locally, then push
    git push origin feature/your-feature-name
  4. Open a PR using the PR template and link the issue number

Commit Convention

Prefix Purpose
feat: New feature
fix: Bug fix
docs: Documentation
refactor: Code restructuring
test: Adding/updating tests
perf: Performance improvement

πŸ”’ Privacy & Security

  • Local Processing β€” Camera data is processed entirely in the browser; no video frames are sent to any server
  • No Raw Video Storage β€” SpectraX never stores raw video footage
  • Minimal Data β€” Only workout analytics and session summaries are persisted
  • No Third-Party Biometric Sharing β€” No personal biometric data is shared externally
  • Firebase App Check β€” Optional reCAPTCHA Enterprise integration to protect authentication endpoints from abuse
  • Socket Auth & Rate Limiting β€” Backend enforces authentication, rate limits, and CORS policies on WebSocket connections

❓ FAQ

See the full FAQ document for detailed answers to common questions about setup, exercises, privacy, and troubleshooting.


πŸ“„ License

This project is licensed under the MIT License.


SpectraX β€” The Future of AI Fitness

Made with ❀️ by Somil Jain and amazing contributors

⭐ Star this repo if you find it useful!

About

Resources

License

Code of conduct

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors