Documentation Index
Fetch the complete documentation index at: https://285e39fd5e337e58f16290.sightscreen.app/llms.txt
Use this file to discover all available pages before exploring further.
How it works
When a user taps Follow, theFollowManager on iOS drives the flow.
Local state first
FollowManager immediately writes the matchId to UserDefaults. This makes the bell icon update instantly — no waiting for the network round-trip.API call
POST /user/follow/match with matchId and deviceId (identifierForVendor). The backend creates a record in match-follows with a TTL of 48 hours after the match ends.If match is live: push-to-start
The backend returns the cached
displayState so iOS can show initial data immediately. Simultaneously, it creates a PENDING record in live-activities and sends a push-to-start notification to the device.LA creation on device
iOS receives the push-to-start and ActivityKit creates the Live Activity on the Lock Screen and Dynamic Island. If the user has LA permissions disabled, the follow still works (bell icon shows a warning badge) but no LA appears.
Token registration
Once the LA is created, iOS observes
pushTokenUpdates on the Activity. TokenManager sends the token to POST /matches/:matchId/activity-token. The backend activates the LA record.Score updates begin
The
LACoordinator now includes this token when fanning out score updates for the match. See live score pipeline.When LA permissions are disabled
If the user has denied Live Activity permissions (or the device doesn’t support them), the follow is still created on the backend. The user is “following” the match — they just won’t get a Lock Screen widget. The bell icon shows a warning state to communicate this. The user can still see match updates by opening the app.Unfollowing
Key points about unfollow:- The backend sends an APNs
endevent to all devices for this user+match. Multi-device cleanup is server-authoritative. FollowManagerremoves the matchId fromUserDefaultsimmediately (optimistic UI).- If the DELETE request fails (offline),
FollowManagerqueues it as a pending unfollow and retries on next app launch.
Syncing follows on login
On login, the iOS app callsGET /user/follows to fetch the list of active follow records from the backend. This reconciles local state with server truth and handles:
- Follows created on another device
- Local state lost due to app reinstall
- Follows that expired while the user was signed out
Key tables
| Table | Key schema | Purpose |
|---|---|---|
match-follows | PK: userId, SK: matchId | Tracks which users follow which matches (TTL: 48h post-match) |
live-activities | PK: matchId, SK: userId#deviceId | Maps active LA tokens to users and devices |
Key endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /user/follow/match | Follow a match |
| DELETE | /user/follow/match | Unfollow a match |
| GET | /user/follows | List followed match IDs (sync on login) |
| POST | /matches/:matchId/activity-token | Register LA update token |
| POST | /matches/:matchId/activity-dismissed | User dismissed LA (triggers unfollow) |
Related pages
- Live Activity lifecycle — full LA creation, update, and end flows
- Live score pipeline — what happens after the LA is active and receiving updates
- Device registration — push tokens and multi-device support