System context - Sightscreen

System context diagram

This shows every system and external service in play, and the connections between them.

Ingest

The backend polls SportMonks on a schedule for fixture lists, live scores, and ball-by-ball data. Raw responses are cached in DynamoDB.

Process

Services transform raw SportMonks data into a normalized display state. State hashes detect actual changes to avoid redundant pushes.

Deliver

When match state changes, the backend sends push notifications and Live Activity updates through Apple APNs to subscribed devices.

Serve

The iOS app also makes direct REST API calls to the backend for on-demand data — fixture lists, match details, standings, etc.

Connection	Protocol	Auth	Notes
iOS to Backend	HTTPS REST	Cognito JWT in `Authorization` header	All endpoints require auth except health check
Admin to Backend	HTTPS REST	Cognito JWT	Admin-scoped token with elevated permissions
Backend to SportMonks	HTTPS REST	API key in query params	Rate-limited, polled on intervals
Backend to DynamoDB	AWS SDK	IAM role	All persistent storage goes here
Backend to Cognito	AWS SDK	IAM role	Token verification, user pool management
Backend to APNs	HTTP/2	JWT-based APNs auth token	Separate channels for alerts vs Live Activities

If push notifications stop working, check the APNs auth token expiry first. These tokens are short-lived and need periodic refresh.

⌘I