Skip to main content

​
Overview

d-sports-api (package name: d-sports-pwa) is the main application: a Progressive Web App that provides the full fan engagement experience. It is both the backend and the web client.
  • Default port: 3004
  • Run: bun dev

​
Tech stack

CategoryTechnology
FrameworkNext.js 16, React 19
DatabasePostgreSQL, Prisma 6.8
AuthClerk 6.x
StylingTailwind CSS 4, Radix UI, shadcn/ui
Web3Thirdweb, Viem, Wagmi
PaymentsRevenueCat (purchases-js)
StateTanStack Query, TanStack Store
SecretsHashiCorp Vault (optional)
PackageBun

​
Features

  • Locker room — Social feed, posts, comments, likes, following
  • Gamification — Quests, points, achievements, leaderboards, Frontline Pass
  • Digital collectibles — NFT-style collectibles, rarity tiers, pack opening, inventory
  • Shop — Product catalog, cart, RevenueCat purchases
  • Wallet — Web3 wallet, token balances, Thirdweb integration
  • Interactive games — Trivia, wheel spin
  • Team manager dashboard — Collectible creation, bulk upload, packs, analytics, revenue
  • Admin — Impersonation, roles (SuperAdmin, Admin, TeamManager), user management

​
Getting started

  1. Clone the repository and install dependencies (bun install).
  2. Set up environment variables (see repo .env.example or Vault setup in README).
  3. Configure PostgreSQL and run bun prisma db pull then bun prisma generate.
  4. Run bun dev — app is at http://localhost:3004.
For full setup (Vault, seeds, migrations), see the repository README.

​
API

This app is the primary API surface for the D-Sports platform. The API reference in these docs covers endpoints and usage; detailed OpenAPI or API specs live in the repo.

​
Season 0.5 leaderboard infrastructure

  • Points events are now 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 now 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!

Comprehensive non-admin gamification docs now live in dedicated sections with subsections:

Gamification docs hub

Start here for architecture and behavior docs across quests, points, leaderboards, rewards, and achievements.

Backend coverage status

See exactly what is documented vs missing across all non-admin backend feature domains, not only gamification.

​
Backend domain deep dives

Each non-admin backend domain now has dedicated folderized docs with architecture and behavior subsections.

Auth and onboarding

Session/auth boundaries, profile lifecycle, and onboarding behavior.

Social and locker room

Posts, comments, reactions, follow graph, and stream behavior.

Commerce and purchases

Catalog, checkout, purchases, dsports-cash, and entitlement flows.

Collectibles and packs

Pack lifecycle, collectible ownership, inventory, and minting paths.

Wallet and web3

Wallet provisioning, key access controls, and provider integration behavior.

Moderation and reporting

User-facing report intake and moderation model lifecycle.

Platform and infrastructure

Streams, sync routes, backfills, and non-admin operational patterns.

Backend coverage status

Track what is documented, partial, or not yet documented across all non-admin backend domains.

Ecosystem overview

See how d-sports-api fits with the site, native app, and Mic’d Up.