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

This highly available microservices architecture decouples heavy write operations from read operations while introducing stream processing and fault-tolerance mechanisms to ensure data integrity and system resilience.

• Smart Client (Mobile/Wearable): Now includes local noise reduction (Kalman filter) and a persistent local queue for robust offline capabilities.
• API Gateway: The single entry point, equipped with Circuit Breakers to prevent cascading failures.
• Workout Service: Ingests raw telemetry data and pushes it directly to a raw data stream.
• Stream Processor (Apache Flink): Buffers, reorders, and cleanses out-of-order GPS data before persisting it.
• Stats & Analytics Service: Asynchronously calculates user statistics and implements Graceful Degradation via caching.
• User & Goals Service: Manages user profiles and targets.
• Message Broker (Kafka): Ensures reliable, decoupled asynchronous communication across all services.

Detailed Component Design

1. Robust Workout Ingestion & Offline Sync (Write Path)

• Challenge: Sporadic network connections lead to data loss or duplicate entries. Raw GPS data is often noisy or wildly inaccurate.
  • Solution:Client-Side Smoothing: Before saving locally, the client applies a Kalman filter to smooth out GPS anomalies and discard extreme outliers.
  • Queue-Based Offline Sync: Telemetry is stored in a local persistent database (e.g., SQLite). A Background Sync Manager monitors OS network state and pushes batched data when online.
  • Idempotency: The client generates a unique UUID (Idempotency Key) for each workout session. The server checks this key against Redis; if a duplicate retry occurs (e.g., the network dropped before the client received the 200 OK), the server safely ignores it without corrupting the user's data.

2. Handling Out-of-Order Data (Stream Processing)

• Challenge: Network latency can cause data packets to arrive out of chronological order, messing up distance calculations and route mapping.
  • Solution:The Workout Service no longer writes directly to the database. Instead, it pushes the raw, timestamped payload into a Kafka Raw Telemetry Stream.
  • Apache Flink (or Kafka Streams) consumes this stream. It applies a sliding time window (e.g., 30 seconds) to buffer the incoming packets, re-orders them chronologically based on their strict client-side timestamps, and performs final server-side smoothing.
  • Once processed, Flink writes the clean data to the Time-Series DB (Cassandra) and publishes the WorkoutCompleted event to the processed Kafka topic.

3. Stats Aggregation & Goals (Async Processing)

• Challenge: Calculating metrics on the fly is database-intensive.
  • Solution:Using a Fan-Out architecture, the Stats Service and Notification Service subscribe to the WorkoutCompleted Kafka topic.
  • The Stats Service asynchronously increments the user's running totals in PostgreSQL.
  • If a goal threshold is crossed, it emits a GoalAchieved event, prompting the Notification Service to dispatch a push notification.

4. Fault Tolerance & Service Isolation (High Availability)

• Challenge: A failure in a downstream service (like user profiles) could cause the API gateway to hang, bringing down the entire system.
• Solution:
  • Circuit Breakers: Implemented at the API Gateway and between internal services. If the User Service latency spikes or it crashes, the circuit breaker "trips," failing fast and immediately returning a 503 Service Unavailable instead of holding connection threads open.
  • Graceful Degradation: If the primary PostgreSQL database or the Stats Service experiences an outage, the API Gateway catches the failure. Instead of showing an error screen, it degrades gracefully by fetching the last known stale dashboard data directly from the Redis Cache, ensuring the user still sees a functional UI.