d-sports-api

​

Overview

d-sports-api (package name: d-sports-pwa) is the live application: a Progressive Web App that provides the full fan engagement experience. It is both the production backend and the web client.

• Default port: 3004
• Run: infisical login once, then bun dev
• App version: 0.2.0

​

Tech stack

​

Features

• Locker room — Social feed, posts, comments, reactions, likes, drafts, lineup attachments, follows, per-post get/update/delete
• Gamification — Quests, points, achievements, leaderboards, Frontline Pass, daily quiz sessions
• Fan Rep — Append-only RepLedgerEntry with Fan, Club, and Player sources
• Digital collectibles — Rarity-tiered collectibles, pack opening, inventory, featured showcase
• Shop — Product catalog, cart, RevenueCat and crypto checkout, D-Sports Cash
• Wallet — Custodial Thirdweb wallets, PIN gates, server-side transaction signing
• Interactive games — Team-selected catalog (daily spin, guess-the-player, live games) plus the Game Engine for Pick’em, Trivia, air hockey, and the locker-singularity idle ledger
• Team manager dashboard — Collectible creation, bulk upload, packs, analytics, revenue
• Admin — Impersonation, roles (SuperAdmin, Admin, TeamManager), user management

​

What changed since last docs sync

• OpenAPI is 252 paths, synced from d-sports-api main (e9a8d95). New published surfaces: HQ starred teams, GET /api/teams/{id}, the locker-singularity idle ledger, and wallet attestation at /api/wallets/{address}/attestation (the path value is the wallet database id). PUT /api/packs/{id}/purchase is in the spec as removed (410); confirm with POST /api/checkout/crypto/verify. GET /api/user/all stays out of this spec until d-sports-api#738 merges.
• HQ stars (/api/me/starred-teams) are bookmarks, not follows, with a 50-club cap.
• Binder PIN is a short-lived token: POST /api/binders/{id}/verify-pin returns { granted, token, expiresIn: 300 }. Send x-binder-pin-token on GET /api/binders/{id} or PIN binders return 403 PIN_REQUIRED without shelves.
• Sports catalog, team search, slug lookup, roster, and leaderboard join/leave are in OpenAPI. TeamFollow stays social-only.
• POST /api/locker-room persists lineup and allows attachment-only posts. authorTeamId (alias postAsTeamId) is distinct from the about-tag teamId and returns 403 when unauthorized.
• Marketplace pack listing rejects processing purchases with 409 PACK_NOT_LISTABLE. Native listings/mine aliases me/listings.
• Unknown /api/* paths return JSON 404, not the HTML app 404.
• Secrets moved to Infisical. HashiCorp Vault is no longer the documented local path.
• Prisma is 7.9.1.
• Custodial wallets sign on the server. POST /api/wallets/private-key is deprecated and PIN-gated.
• Fan Rep is a first-class ledger. dsportsDirectRep sums repType = Direct rows from admin grants.

​

Getting started

1. Clone the repository and install dependencies (bun install).
2. Run infisical login once so bun dev and bun db:* can inject secrets.
3. Pull and generate Prisma: bun db:pull then bun db:gen.
4. Run bun dev — app is at http://localhost:3004.

For deployment, Sentry, and seed catalogs, see the repository README and docs/ folder. Do not copy in-repo AGENTS.md into this site.

​

API

This app is the primary API surface for the D-Sports platform. The API reference covers endpoints and usage. The generated spec is synced from the API repo’s openapi.json — do not edit api-reference/openapi.json by hand.

​

Season 0.5 leaderboard infrastructure

• Points events are scoped in PointsHistory by both leaderboard and season.
• Season reset/wipe behavior is unchanged.
• Legacy Season 0 rows with null scoping are intentionally preserved for backward compatibility.

​

Leaderboard scoring behavior

• Team boards compute totals from PointsHistory rows filtered by both active seasonId and the team leaderboardId.
• The global board computes totals from PointsHistory rows filtered by active seasonId only (cross-board season aggregate).
• New point writes (quests, onboarding, daily actions, backfill scripts) include seasonId and leaderboardId where available.
• Some historical/backfill paths can intentionally write leaderboardId: null when a board cannot be determined yet.
• Legacy Season 0 rows with null season/board scope remain in storage and are intentionally excluded from Season 0.5+ scoped calculations.

​

API contract notes

• GET /api/leaderboard?leaderboardId=<id> resolves and scores a specific board.
• GET /api/leaderboard?teamId=<teamId> resolves (or creates) that team board, then scores it.
• GET /api/leaderboard (no params) returns global leaderboard scoring for the active season.
• This release does not introduce season reset/archiving behavior changes, and does not remove LeaderboardEntry.points yet (planned Season 2 cleanup).

​

Gamification deep dives

​

Backend domain deep dives

​

Admin and team management surfaces (public-safe)

​

Compliance and legal: pack opening odds