Requirements

Functional Requirements:

• Log workouts with structured data (exercise type, duration, reps, calories, timestamps)
• View workout history & aggregated stats (daily/weekly summaries)
• Sync and update workout data across multiple devices in near real-time

Non-Functional Requirements:

• Eventual consistency across devices with conflict resolution for concurrent updates
• Low latency (<200ms) for syncing and retrieving workout data
• High scalability to support millions of users and continuous data ingestion

API Design

• Core entities:
  • User (id, height, weight, age, sex)
  • WorkoutSession (id, user_id, start_time, end_time)
  • ExerciseDefinition (id, category, static data for exercise name e.g. Bench Press or Squat)
  • ExerciseSet (workout_id, exercise_id, reps, weight, duration, distance)
  • Goal (exercise_id, goal_reps, goal_weight, goal_duration, goal_distance)
• Endpoints:
  • POST /workouts -> create workout session
  • GET /workouts?user_id={id} -> list workouts
  • GET /workouts/{id} -> get specific workout
  • POST /workouts/{id}/exercises -> add exercise to workout
  • GET /workouts/{id}/exercises -> list exercises in workout
  • POST /goals
  • GET /goals?user_id={id}

High-Level Design

• System Components:
  • API Gateway
  • Workout Service
  • Exercise Service
  • Goal Service
  • Sync Service
  • Postgres (primary DB)
  • Redis (caching layer)
• Workout Flow:
  • User starts workout -> request hits API Gateway
  • Routed to Workout Service
  • Workout Service stores session in Postgres
  • Event published to Sync Service
  • Sync Service pushes updates to other devices (WebSocket)
• Exercise Flow:
  • User requests exercise list
  • API Gateway -> Exercise Service
  • Frequently accessed exercises cached in Redis
  • Full dataset stored in Postgres
• ExerciseSet Flow:
  • User logs exercise data
  • Request -> Workout Service
  • Data stored in Postgres
  • Event emitted -> Sync Service
  • Other devices receive updates
• Goal Flow:
  • User sets goal -> Goal Service
  • Stored in Postgres
  • Retrieved alongside workouts for display

Detailed Component Design

• WorkoutSession Component:
  • Clilent sends POST /workouts to API Gateway
  • API Gateway routes to Workout Service
  • Workout Service:
    • Generates session ID
    • Stores session in Postgres
    • Caches active session in Redis
    • Emits "workout_started" event
  • Sync Service listens and updates other devices
• ExerciseSet Component:
  • Client sends POST /workouts/{id}/exercises
  • Workout Service:
    • Validates exercise type (strength vs cardio)
    • Normalizes schema (null fields appropriately)
    • Normalizes schema (null fields appropriately)
    • Writes to Postgres
    • Updates Redis cache for active session
    • Emits "exercise_logged" event
  • Sync Service pushes update via WebSocket
• ExerciseDefinition Component:
  • Exercise Service handles GET /exercises
  • Frequently accessed exercises cached in Redis
  • Full dataset stored in Postgres
  • Use Elasticsearch for full-text search
• Goal Component:
  • Goal Service stores goals in Postgres
  • On workout retrieval:
    • Workout Service joins goal data
    • Returns enriched response