System boundaries
Gamification ind-sports-api is primarily implemented in:
server/quest-actions.tsserver/daily-quest-actions.tslib/leaderboard.tsapp/api/leaderboard/route.tsapp/api/rewards/*prisma/schema.prisma(gamification models)
Core models
QuestandQuestStep: quest definitions and ordered steps.UserQuestStatusandUserStepStatus: per-user quest and step progression.PointsHistory: append-only points ledger.LeaderboardandLeaderboardEntry: board membership and denormalized board points.LeaderboardSeason: season lifecycle metadata.RewardandUserReward: reward catalog and user claim state.
Quest assignment domains
- Global quest tracks and team-scoped quest tracks can coexist.
- Team-scoped progression resolves eligibility based on team context and user relationships.
- Quest assignment/read paths should be treated as backend-authoritative.
Pass-gated eligibility architecture
- Eligibility can be conditioned by global pass and event pass state.
- Pass checks happen server-side and influence quest visibility/completion pathways.
- Client apps should not hardcode pass logic assumptions.
Reward pipeline architecture
- Reward outcomes include free rewards and unpaid rewards semantics.
- Claim/redeem writes are validated against eligibility, status, and prior claims.
- Reward effects propagate into user-visible quest/reward surfaces through API contracts.
Cross-feature flow
Season 0.5 scoping rules
- New points writes include
seasonIdandleaderboardIdwhere determinable. - Team board scoring reads are scoped by both active season and board.
- Global board scoring reads are scoped by active season only.
- Legacy rows with null scope are intentionally preserved and treated as legacy data.
Important implementation notes
- Some flows still use fallback writes with
leaderboardId: nullwhen board context is unavailable. LeaderboardEntry.pointsremains present for compatibility and is planned for later cleanup.- Non-admin reset/archive lifecycle paths are intentionally not covered in this gamification section.