Skip to main content

​
Sync services and execution order

Canonical sync processing is split into coordinated backend services:
  1. Fetch/parse canonical source data
  2. Upsert league records and metadata
  3. Sync team records and logos
  4. Link teams to leagues
  5. Ensure team leaderboard parity where required

​
League linking and leaderboard parity

  • Team rows are linked to league rows through normalized identifiers and mapping logic.
  • Team sync paths also ensure team leaderboard rows exist for consistent ranking surfaces.
  • Public GET /api/config/sports is derived from League.sport. Team sport is never null ("other" when unknown).
  • Leaderboard join (/api/teams/{id}/join) is a separate write from social TeamFollow.
  • HQ stars (app/api/me/starred-teams) are a third write. They do not create TeamFollow or a leaderboard entry. GET /api/teams/{id} (app/api/teams/[id]/route.ts) is the public id-or-slug read.
  • Public GET /api/teams/{id}/roster reads Player rows (isActive: true) and maps position to sport-aware role / duty. Editorial snapshots live in leagues/teams/rosters.json.

​
Team logo propagation

  • Canonical logo paths are fetched from source data and uploaded to storage.
  • Backend updates team logo fields after successful upload.
  • Clients consume resulting logo URLs from API payloads.

​
Idempotency and safety

  • Sync routes are designed to be repeatable.
  • Non-destructive update behavior is preferred over hard deletes.
  • Partial failures should log recoverable errors and preserve existing valid data.