Requirements

Functional Requirements:

Log workouts: Users can record activities (type, duration, distance, heart rate, GPS route).

View history & stats: Users can view past workouts and aggregated metrics (daily, weekly, monthly).

Sync across devices: Seamless state synchronization across mobile, web, and wearables.

• Set goals & monitor progress: Users can set targets (e.g., "run 10 miles a week") and track completion.

Non-Functional Requirements:

High Availability & Reliability: The system must remain available even if individual components fail.

Low Latency (Writes): Logging real-time telemetry from wearables or phones must be fast and unobtrusive.

Eventual Consistency (Reads): It is acceptable if aggregated stats take a few seconds to update after a workout finishes.

Offline Support: The mobile client must allow logging workouts without an internet connection and sync when back online.

• Scalability: Must support millions of concurrent users, especially during peak workout hours (e.g., early mornings, evenings).

API Design

We will use RESTful APIs. For high-frequency telemetry data from devices, a WebSocket or gRPC stream could be considered, but REST with batched payloads is simpler and highly effective for standard mobile clients.

• POST /v1/workouts
  • Payload: { "user_id": "123", "type": "RUN", "start_time": "...", "end_time": "...", "metrics": [...] }
  • Purpose: Submits a completed workout or syncs a batched offline workout.
• GET /v1/workouts?user_id=123&limit=20&offset=0
  • Purpose: Retrieves workout history for the feed.
• GET /v1/stats?user_id=123&period=weekly
  • Purpose: Fetches aggregated statistics (total distance, calories, etc.).
• POST /v1/goals
  • Payload: { "user_id": "123", "metric": "DISTANCE", "target": 10.0, "period": "WEEKLY" }
  • Purpose: Creates a new user goal.

High-Level Design

The system relies on a microservices architecture to decouple the heavy write operations (workout telemetry) from the read-heavy operations (user profiles and aggregated stats).

• API Gateway: Acts as the single entry point, handling authentication, rate limiting, and request routing.
• Workout Service: Handles the ingestion of workout data.
• Stats & Analytics Service: Consumes workout events and pre-calculates user statistics and goal progress.
• User & Goals Service: Manages user profiles, authentication, and goal definitions.
• Message Broker (Kafka): Ensures reliable, asynchronous processing of workout events to update stats, notify friends, and trigger push notifications.

Detailed Component Design

1. Workout Ingestion & Storage (Write Path)

• Challenge: Wearables and phones generate massive amounts of telemetry data (GPS coordinates every second, heart rate). Writing this directly to a relational database would cause locks and severe performance bottlenecks.
• Solution: * The mobile client batches telemetry data locally (SQLite/Realm) and sends it to the Workout Service periodically or at the end of the session. This naturally handles the offline support requirement.
  • The Workout Service stores the raw, high-volume time-series data in a NoSQL Time-Series Database like Cassandra or Amazon Timestream, which are optimized for extremely fast, heavy write workloads and horizontal scaling.
  • Once saved, the Workout Service publishes a WorkoutCompleted event to Kafka.

2. Stats Aggregation & Goals (Async Processing)

• Challenge: Calculating a user's total weekly distance on-the-fly every time they open the app is too slow and database-intensive.
• Solution:
  • We use a Fan-Out architecture via Kafka. The Stats Service subscribes to the WorkoutCompleted topic.
  • When an event arrives, the service asynchronously updates the user's running totals (daily/weekly/monthly) in a relational database (PostgreSQL) using incremental counters.
  • It also checks these new totals against the user's defined targets in the User & Goals Service. If a goal is met, it publishes a GoalAchieved event to Kafka, which the Notification Service picks up to send a push notification to the user.
  • Read Path Optimization: Aggregated stats are cached in Redis. When the client calls GET /v1/stats, the API fetches it from Redis in sub-millisecond time, falling back to PostgreSQL only on a cache miss.