Smartwatch Companion

4league ships a companion app for Wear OS and watchOS. Referees, team managers, and organizers can start matches, log goals, cards, fouls, and substitutions directly from the wrist — and fans can glance at a ranking-position widget to see where their followed teams sit across every competition they play in.

Overview

The smartwatch companion has two main capabilities:

• Live match control — available to users with match-editing rights (organizers, referees, team managers). Start a match, add goals / cards / fouls / substitutions, and end the match — all from the watch.
• Ranking-position widget — available to every user. Glanceable list of every competition your followed teams play in, showing current rank, points, and a daily ▲/▼ arrow vs. the previous day's snapshot.

The watch does not hold its own session. On launch it waits for the phone to push a SESSION_SYNC message containing the authenticated user's sessionId, userId, language, and secretCode. Until that message arrives the companion renders a waiting screen.

Platforms

Both apps use the same message contract (see Phone ↔ Watch Messages) and the same backend endpoint for rankings.

Pairing & Session Sync

Installing the 4league watch app from the Play Store (Wear OS) or App Store (watchOS) is enough — there is no separate login on the watch. The phone app detects a paired watch with the companion installed and pushes a session envelope via the Wearable Data Layer / WatchConnectivity.

Live Match Screens

When the signed-in user has match-editing rights (organizer, referee, or team manager) the watch exposes the full live-match flow:

Watch navigation
├── WaitingScreen — pre-session
├── MatchListScreen — upcoming/in-progress matches
│   └── LiveMatchScreen — running clock, score, team crests
│       ├── GoalEntryScreen — tap a side to add a goal
│       ├── ActionMenuScreen — long-press to open
│       ├── CardEntryScreen — yellow / red card
│       ├── FoulScreen
│       └── SubstitutionScreen
└── RankingsScreen — ranking-position widget (all users)
    └── RankingDetailScreen — Top 5 of the tapped competition

The match list is backed by GET /competition/watchMatches, which returns matches where the caller has editing rights and that either start within the next 10 minutes or are currently in progress — so a referee's watch never shows matches three days out when the user is standing by the pitch right now.

Ranking-Position Widget

The rankings widget is a glanceable tile for every competition that a followed team plays in — visible to every plan (Free, PRO, Enterprise). It's designed so a fan who follows three teams across five competitions can see all five positions in one scroll without opening the phone.

What the user sees

Each tile on the Rankings screen shows:

• The organization name (if the competition belongs to one) as a small header.
• The team name — large, bold.
• The current rank (e.g. "#4") and points in that competition.
• A delta arrow on the right side:
  • ▲ green — team moved up since the previous day's snapshot.
  • ▼ red — team moved down.
  • — grey — rank unchanged since yesterday.
  • · dim — no prior snapshot yet (first-run or newly published competition). Rendered as a no-arrow state on purpose; zero and null are different states.

Stale-data hint

If the last successful fetch is more than 5 minutes old while the Rankings screen is open, a small yellow "Updated >5m ago" line appears above the list. The screen re-evaluates staleness every 30 seconds while visible — the ticker only runs after the first response, so it doesn't burn battery before the user has any data.

Empty state

If the user follows no teams, or every followed team's competition is private/unpublished, the screen shows "No rankings available" plus a manual Refresh button. Private competitions (visibility = 0) are filtered server-side even for competitions the caller owns, so a watch tile can never leak a private-league position to someone who shouldn't see it.

Rankings Screens

RankingsScreen — the tile list

Vertical ScalingLazyColumn of RankingTileCards, one per (team, competition) pair. The screen requests fresh data on navigation and on manual refresh; the list renders whatever the repository last observed and updates reactively when a new RANKINGS_RESPONSE arrives.

RankingDetailScreen — Top 5 of one competition

Tapping a tile opens a detail view that renders the top 5 rows of that competition's standings — the same ranking the user sees on the phone's standings screen. The followed team is highlighted with a green left-edge rule and bold text.

If the followed team is not in the top 5 (say they sit 9th), the screen shows the top 5, a ··· separator, and then one highlighted row for the followed team's current position. A helper match-by-(rank, teamName) fallback handles the case where the followed team id differs between a managed team and its competition-team mirror.

Phone ↔ Watch Messages

All phone-watch traffic is JSON on the /fourleague message path. Messages are one-shot fire-and-forget; the watch never holds a socket. Each message carries a type field that the receiver switches on.

Message catalog

Rankings round-trip

The rankings exchange is intentionally minimal:

Watch                                           Phone
  │ user opens Rankings → requestRankings()
  ├────── { "type": "REQUEST_RANKINGS" }  →
  │                                               │
  │                                  phone calls GET /competition/watch-rankings
  │                                               │
  ├────── ← { "type": "RANKINGS_RESPONSE", "tiles": […] }
  └ RankingRepository.tiles StateFlow emits → UI rerender

Backend API

GET / POST /competition/watch-rankings

Aggregated watch-tile endpoint. Returns one RankingTile per (followed team, competition) pair. Both GET and POST are accepted — the watch companion uses the GET form for idempotent requests; dev tooling and tests prefer the POST body form to avoid URL-length limits on users who follow many teams.

Request

The endpoint accepts managed team ids (the top-level team the user follows) or competition-team ids (the per-competition mirror). Both resolve to the same tile.

Response

{
  "tiles": [
    {
      "rankingId": "65f0c3…",          // = competitionId. Stable per (team, competition) tile.
      "orgId":     "65ef91…" | null,   // parent organization id.
      "orgName":   "Sunday League" | null,
      "orgLogo":   "https://…" | null,
      "teamId":    "65f0b7…",          // caller's followed team id, echoed back.
      "teamName":  "FC Example" | null,
      "teamCrest": "https://…" | null, // team.logo
      "rank":      4,                    // 1-based (1 = leader).
      "points":    27,
      "delta":     2 | null,             // priorRank - currentRank. +ve = moved up. null = no prior snapshot.
      "top5": [                          // top 5 rows of the same standings (oldest-rank-first).
{ "rank": 1, "teamId": "…", "teamName": "…", "points": 34 },
{ "rank": 2, "teamId": "…", "teamName": "…", "points": 30 },
{ "rank": 3, "teamId": "…", "teamName": "…", "points": 28 },
{ "rank": 4, "teamId": "…", "teamName": "…", "points": 27 },
{ "rank": 5, "teamId": "…", "teamName": "…", "points": 25 }
      ]
    }
  ]
}

RankingTile field reference

Visibility & publish gating

A tile is only emitted when both conditions hold on the competition:

• visibility !== 0 — the internal migration collapses private, demo, hidden, and inactive competitions into visibility = 0; this filter gates the whole public surface.
• onboardingDone === true — the competition is published (onboarding has finished). Half-configured drafts are skipped because their standings would be empty or misleading.

Daily Snapshot Cron

The delta field on each tile is computed against a daily snapshot of every published competition's standings. A dedicated cron helpers/competitionSnapshotJob.js runs once per 24h and writes one document per competition per day to the rankSnapshots collection.

Why daily and not match-driven

A match-driven snapshot would re-fire every time a match finishes, and on a busy Saturday the widget's arrow would flip sign multiple times as each result landed. One canonical pass per 24 hours gives every tile a stable "since yesterday" delta that compares against one reference point rather than an arbitrary mid-day checkpoint. Users far from UTC may perceive their "yesterday" shifted by one local day — acceptable, and matches the existing RankingSnapshots behavior.

Snapshot document shape

// collection: rankSnapshots
{
  _id:            ObjectId,
  competitionId:  "65f0c3...",           // stringified competition id
  date:           "YYYY-MM-DD",          // UTC midnight canonical date key (no time component)
  entries:        {                      // whole-table map keyed on competition-team _id
    "65f0b7...": { rank: 1, points: 34 },
    "65f0b8...": { rank: 2, points: 30 },
    ...
  },
  teamCount:      20,                    // convenience for admin queries
  snapshotRunId:  "competition-cron:2026-04-21T03:15:00.000Z"   // groups a single cron invocation
}

A whole-table map per competition (rather than one row per team) keeps the cron's write rate low — a 12-team league is one upsert, not twelve — and matches the shape the read path needs anyway, because the endpoint's top5 block reads the same snapshot.

Where the delta comes from

For each followed (team, competition) tile the endpoint runs RankSnapshots.findMostRecentPrior(competitionId, todayKey) — i.e. the most recent snapshot strictly before today's UTC date. If that snapshot contains an entry for the team, delta = priorEntry.rank − currentRank. If it doesn't — first-run, team joined today, or the competition was published in the last 24 hours — delta is null, and the watch renders a no-arrow state.

Retention

Snapshots are retained indefinitely for MVP. A 20-team competition is roughly 1 KB on disk, so a year of daily rows across a typical tenant is measured in megabytes. A retention job (TTL index on date, or cold archival) can be added later if collection growth becomes a concern.

Related: the rankingPositionChange push

Complementing the glanceable widget is an on-demand push notification (rankingPositionChange) that fires when a followed team's position moves relative to the organization-level ranking system. Tapping the notification deep-links into the phone app's RankingTable screen for the relevant organization.

Because the notification's positionChange uses the same positive-means-moved-up convention as the watch tile's delta, the ▲/▼ the user saw in the push matches the ▲/▼ they see when they raise their wrist a moment later.