AWS Builder Center

Builder Center

Fitelligence: The Engineering Ecosystem behind AI Biomechanics & Gym Operations

Fitelligence: The Engineering Ecosystem behind AI Biomechanics & Gym Operations

A deep dive into the architecture powering a full-stack, AI-driven fitness and gym management platform.

Binod Prasad Joshi

AWS Community Builder - Dev Tools | 2× AWS Certified | Devops/Cloud Consultant
This technical blog post breaks down the complete engineering architecture of FitIntelligence, a premium, full-stack fitness and gym management application. By merging real-time computer vision, large language model (LLM) reasoning, geofenced location intelligence, and automated CI/CD deployment pipelines, FitIntelligence bridges the gap between hardware tracking and digital coaching.

1. System Architecture Topology

The diagram below illustrates the end-to-end data flow, API gateways, background processing jobs, and AI/ML model integrations within the FitIntelligence platform.


2. In-Depth Service Analysis

A. Mobile Client (React Native, TypeScript, Zustand)

The FitIntelligence mobile app is engineered for smooth interactive experiences, combining a custom glassmorphic dark-theme UI with low-latency client logic:
  • Zustand State Manager: Avoids the heavy re-rendering of Redux by managing separate stores ( useStore  and  useAdminStore ) for local auth, theme tokens, gym checklists, and current calendar entries.
  • FormData Video Streaming: Video files picked from the library are sent to the  /trainer/ai/analyze-video  endpoint as a multi-part form payload.
  • Path Prefix Stability: The client retains the native file scheme ( file://  or  content:// ) depending on the OS platform to allow React Native's underlying network client (OkHttp / RCTNetworking) to stream files without raising silent  Network Error  read crashes.

B. FastAPI Gateway (FastAPI, Uvicorn, SQLAlchemy)

The backend service acts as the operational orchestrator. Built using FastAPI for asynchronous routing:
  • Uvicorn Gateway: Runs the API gateway on port  8000 . By configuring large request body limits and optimizing Uvicorn keep-alive timeouts, the backend handles concurrent high-bandwidth video uploads smoothly.
  • Security & Auth: Leverages JWT tokens and OAuth2 interfaces to handle user registrations, admin privileges, and secure token refresh cycles.
  • SQLAlchemy & Alembic ORM: Handles connection pooling to PostgreSQL. Database updates are managed through programmatic migration scripts ( alembic upgrade head ) executed automatically during production updates.

C. Computer Vision Engine (NVIDIA YOLO11-Pose)

When a video is received, the backend saves the payload to a secure temporary path and processes it using the YOLO11-Pose keypoint extraction library:
  1. Joint Coordinates Extraction: Frame-by-frame, the model isolates human silhouettes and computes the coordinates of 17 key joints (shoulders, elbows, hips, knees, ankles, etc.) relative to the frame dimensions.
  1. Angle Calculation: Using vector mathematics, joint flexions are tracked dynamically. The angle θ\theta θ at a joint (e.g. elbow) formed by points AA A (shoulder), BB B (elbow), and CC C (wrist) is calculated using the dot product:

  1. Range of Motion (ROM) Computation: The minimum and maximum extension angles across the entire clip are calculated to determine if the user has reached full extension (e.g., deadhang in pull-ups) and full flexion.

D. Biomechanical Reasoning (AWS Bedrock & Meta Llama 3 70B)

Raw numerical angles do not help an everyday athlete. To make this data actionable, the calculated angles and exercise metrics are sent to AWS Bedrock using Meta Llama 3 70B as the core reasoning model.
  • Biomechanics Prompting: The LLM is instructed to evaluate the joint angles like a kinesiologist. It verifies target muscle activation, spine angle consistency, and depth limits.
  • Structured Outputs: The prompt enforces a strict JSON schema return so that the frontend can read the response reliably without parsing issues:
json
JSON
{
  "score": 85,
  "coach_verdict": "Concentric phase shows excellent stability. Hip crease reached parallel, but watch for premature lumbar tuck.",
  "injury_risk": "Spine flexion under load at bottom depth increases shear force on L5-S1 lumbar joints.",
  "positives": ["Knee path tracked parallel to feet", "Chest stayed proud during ascent"],
  "issues": ["Mild posterior pelvic tilt at peak depth"],
  "fix_it_now": ["Cut depth 2 inches higher and brace your core continuously"],
  "what_to_do_next": ["Incorporate plank-to-squat transitions", "Perform goblet squats with paused depth checks"]
}


3. Gym & Location Services (Geofencing & Biometrics)

Ensures accountability for gym check-ins through dual-factor verification:
  1. Haversine Geofencing: When a user checks in, the backend computes the distance between their current GPS coordinates and the gym's registered coordinates using the Haversine formula:

If the computed distance dd d is less than the geofence radius (e.g., 100 meters), the user passes the first boundary step.
  1. AWS Rekognition Face Comparison: The user takes a live check-in selfie, which is uploaded to an Amazon S3 bucket. The backend calls  compare_faces  on AWS Rekognition to match the selfie against their registered profile picture. If the match confidence exceeds 90%, the check-in is approved.

4. Cache & Task Queue (Redis 7 & Celery)

Handles background computations and notifications without delaying HTTP responses:
  • Celery Workers: Run background jobs such as processing image assets, calculating stats, and dispatching push alerts.
  • Celery Beat: A scheduler that triggers daily membership health checks. It flags accounts whose memberships expire in 3 days or less, and queues push warning tasks.

5. AWS Infrastructure Setup

FitIntelligence runs on a production environment hosted on AWS (us-east-1):
  • EC2 Host Instance: Orchestrates backend services inside a multi-container Docker environment.
  • Amazon ECR (Elastic Container Registry): Serves as the repository for backend Docker images.
  • Amazon S3: Serves as the media storage vault for user selfies and profile images.
  • AWS Rekognition: Handles anti-proxy validation checks.
  • AWS Bedrock: Processes text prompts and biomechanical angle critiques using the Llama 3 model family.
  • IAM Instance Profile: Provides the EC2 host with secure access to S3, Rekognition, and Bedrock without hardcoding access keys in the code.

6. The CI/CD Pipelines

FitIntelligence uses GitHub Actions workflows to automate building, testing, security checks, and production deployments.

A. The CI Pipeline ( ci.yml )

Runs on every push to the  main  and  develop  branches:
  1. Linting and Quality Check: Validates imports and formats using  ruff ,  black , and  isort .
  1. Database Integration Testing: Spins up dynamic PostgreSQL 16 and Redis 7 Docker containers within the GitHub Runner.
  1. Pytest Suite: Runs integration tests to verify auth endpoints, location calculations, and database models.
  1. ECR Image Compilation: Authenticates with AWS, builds the production-ready backend Docker container, tags it with the unique git commit SHA, and pushes it to Amazon ECR.

B. The CD Pipeline ( cd.yml )

Triggers automatically once the CI pipeline completes successfully on the  main  branch:
  1. SSH Key Injection: Securely logs in to the production EC2 instance.
  1. Code Synchronization: Synchronizes workspace updates (excluding frontend files) directly to  /home/ubuntu/app/  using  rsync .
  1. Docker Compose Hot-Reload: Pulls the new container image from Amazon ECR and restarts the services ( docker compose up -d ).
  1. Database Auto-Migration: Runs Alembic database migrations ( docker compose exec -T api alembic upgrade head ) to update tables without losing data.
  1. Health Checks: Executes a retry loop using curl to verify the API returns a  200 OK  status.

7. Summary of Recent Optimizations

To ensure the app feels elite, stable, and polished, we recently rolled out several optimizations:
  • Emoji-Free Design System: Replaced casual, unpolished emojis in result cards with professional FontAwesome vector icons (e.g.  check-circle  for strong points,  exclamation-circle  for corrections) to align with a scientific sports aesthetic.
  • No-Crash API Handler: Wrapped the backend video processing logic in a fallback try/except framework to ensure it always returns a structured JSON payload even in case of exceptions.
  • Path Prefix Fix: Kept the  file://  structure intact on iOS during uploads to resolve native networking issues, restoring the video upload flow.

Closing Thoughts

FitIntelligence is a good example of what it takes to turn a phone camera into a credible fitness coach: a pose-estimation model doing the geometry, an LLM translating angles into coaching language, and a boring-but-solid layer of geofencing, background jobs, and CI/CD holding it all together in production. None of the individual pieces are exotic — the value is in how cleanly they're wired together and how much failure-mode handling sits underneath the polish.
# amazon-bedrock# amazon-rekognition# computer-vision# containers# ai-engineering
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article