Requirements

Functional Requirements:

1. User Management

• Users must be able to sign up, log in, and manage their account.
• Users can follow any number of teams or athletes.
• Users can unfollow teams or athletes at any time.

2. Real-Time Updates

• Users must receive real-time game events (scores, fouls, plays, stats).
• System must push updates only for the teams/athletes a user follows.
• On reconnect, the system must allow the user to fetch the latest game state to recover missed events.

3. Historical Data

• System must store all historical game data, events, and play-by-play logs.
• Users must be able to fetch any past game data.
• Users must be able to view aggregated stats for teams/players.

5. Ingestion

• System must ingest real-time feeds from trusted sports data providers.
• System must normalize events into a unified event format before internal distribution.
• Events must be forwarded for both real-time fan-out and persistent storage.

Non-Functional Requirements:

1. High Availability

• Load balancer must route clients only to healthy servers.
• Users should automatically reconnect to a new server if failures occur.

2. Low Latency

• End-to-end delay from provider event → user WebSocket message should be minimal (target under ~200ms).
• Event processing must be streaming-oriented, not batch-based.

3. Scalability

• Real-time push layer must scale horizontally using stateless WebSocket servers.
• NoSQL store must support large amounts of user preference data.
• SQL DB must support heavy read loads on historical queries via replicas or partitioning.

4. Consistency

• Historical and game data must be correct and durable.
• On reconnect, user must receive the latest canonical state.
• Real-time updates must reflect exact order from data provider.

API Design

1.1 Auth

POST /auth/signup

• Body: email, password
• Result: user_id, token

POST /auth/login

• Body: email, password
• Result: token

1.2 User Profile

GET /user/me

• Auth required
• Result:
• • user_id
  • followed_teams: []
  • followed_players: []

1.3 Follow / Unfollow

POST /user/follow/team

• Body: team_id

POST /user/unfollow/team

• Body: team_id

POST /user/follow/player

• Body: player_id

POST /user/unfollow/player

• Body: player_id

These update the user’s preference document in our NoSQL DB.

1.4 Historical Data

GET /games/{game_id}

• Returns final score, play-by-play, stats

GET /games/team/{team_id}/recent

• Returns recent games for a team

1.5 Real-time Updates

GET /ws/live

• WebSocket endpoint
• Auth with token
• After connection:
• • client sends: { subscribe: ["team:123", "player:456"] }
  • server streams: score updates, events, stats deltas

High-Level Design

 Data Provider Ingestion Service

• Subscribes to official sports data feeds.
• Receives real-time events (scores, fouls, substitutions, etc.).
• Writes raw events + normalized events.
• Forwards events to:
• • Event Router / Message Bus
  • Historical DB

Real-Time Push Layer (WebSocket Servers)

• Horizontally scalable stateless servers.
• Only state they hold: active WebSocket connections.
• Subscribes to message bus.
• For each incoming event:
• • determine which users are subscribed
  • push event to connected users

This service is the entry point of all sports data.

Detailed Component Design

3.1 Real-Time Event Flow

Step 1 — Data providers push live events

We assume:

• events are timely
• accurate
• delivered through some push API

Step 2 — Ingestion Service normalizes

• Normalizes sports event formats
• Adds metadata
• Publishing every event into a central message bus topic

Reasoning:

• decouples push from ingest
• acts as buffering in case of temporary slowdowns
• ensures no backpressure on ingestion

Step 3 — Event Router fans out

• Real-time fan-out to WebSocket servers
• Separate background workers store the same events to SQL DB

Latency target:

• < 200 ms end-to-end
• streaming via message bus ensures low overhead and horizontal scaling

3.2 Delivering Events to Users

Push Layer (WebSocket servers)

Responsibilities:

1. Authenticate user
2. Maintain WebSocket session
3. Store user’s subscribed interests in local memory
4. Receive events from message bus
5. Determine which sessions care about the event
6. Push message over WebSocket

These servers are stateless, aside from:

• memory of which users are connected
• their subscription list

Because they are stateless:

• scaling horizontally is simple
• failure of one server only affects its open WebSocket connections

3.3 Handling Disconnects / Missed Events

WebSocket alone does not guarantee delivery if the user disconnects.

So we handle this by:

When user reconnects

• Client calls: GET /games/{game_id} or /state-sync
• Server returns latest game state
• Small gap in messages is corrected

This guarantees eventual consistency for users even if they temporarily lose the connection.

3.4 User Data Management

User metadata + follow lists are stored in NoSQL:

• scalable
• low write/read latency
• document-oriented structure

This DB is used by:

• User Service (REST)
• Push Layer (to know who to notify)

3.5 Storage of Historical Data

All long-term storage is done in PostgreSQL:

• Every event is appended to game_events table
• Periodic aggregations update:
• • final score
  • player stats
  • team stats

This provides:

• ACID correctness
• referential integrity
• ability to query:
• • “What are last 5 games for team X?”
  • “Show full timeline for game Y”

This meets consistency and persistence requirements.