Skip to main content

​
Repository topology

d-sports-api is the production API. Native and web clients call it. d-sports-backend is a tracked Rust rewrite that can proxy unmatched /api/* routes back to the TypeScript API. Do not point production clients at the Rust service unless you are running a documented parity soak.

​
Cross-repo data flow

d-sports-api is the runtime API center for native and web clients. leagues is the canonical metadata input for teams, leagues, and editorial rosters. Sync jobs write that data into Postgres, then clients read it through /api/teams, /api/leagues, and /api/teams/{id}/roster. Secrets for API and native local runs go through Infisical (infisical run --env=dev). You do not maintain a hand-copied .env for those repos.

​
Teams and leagues pipeline

  1. leagues repository updates canonical assets/data.
  2. Workflow trigger sends a webhook to the backend sync route.
  3. Backend sync services upsert leagues, team logos, and links.
  4. Clients consume updates through /api/teams and /api/leagues.

​
Quest, Fan Rep, and pass architecture

  • Backend gamification supports per-team quests and pass-aware eligibility.
  • Daily quests also expose a /api/v1/engage/quests/* session API (start, submit, forfeit, arena check-in, daily summary).
  • Fan Rep is a separate ledger (RepLedgerEntry) with Fan, Club, Player, and Direct sources. Read it from /api/v1/engage/rep/*. D-Sports Direct grants use POST /api/admin/users/{userId}/rep.
  • Pass gating includes global pass and event pass semantics.
  • Reward flows include explicit handling for free rewards and unpaid rewards states.
  • Native clients render eligibility and progression from backend response truth.

​
Native ↔ API contracts that changed recently

  • Mobile OAuth can return a one-time MobileSession hex token (fragment preferred). Native exchanges it at POST /api/mobile/exchange for a Clerk sign-in ticket.
  • Custodial wallets sign on the server (POST /api/wallets/{address}/sign-transaction). POST /api/wallets/private-key is deprecated.
  • Treat featured collectibles, locker-room post CRUD (including persisted lineups), Game Center /api/events/* (including player-stats, win-probability, and Live Activity), marketplace /api/v1/marketplace/*, and the public games catalog as first-class client contracts.
  • Use the Game Engine (/api/v1/engage/games/*) for daily mini-games. Native 1.25.9 registers Pick’em, Trivia, prize-wheel, guess-the-player, lineup, card trivia, streak scratcher, six hockey playfields, air hockey, and locker-singularity. The API owns sessions and awards. Locker Singularity uses the idle ledger. Keep calling legacy /api/games/* play routes and Game Center.

​
Public vs internal documentation boundaries

  • Public docs include contributor-focused implementation contracts.
  • Sensitive admin internals, debug/dev routes, and cron/ops internals are excluded.
  • Approved admin/team routes are documented with redaction where needed for contributor onboarding.
  • Rust parity plans, cutover checklists, and unpublished /v1 domain crates stay in the backend repo.