Flashback Challenges Change Checklist

Use this before editing the live challenge feature.

Before changing code

• Load the Flashback Challenges Gamesense wiki pages through flashback-mcp, starting with this section’s index and architecture page.
• Identify which subsystem you are touching:
  • frontend UI
  • frontend hooks/API client
  • challenge registration
  • FACEIT OAuth
  • FACEIT match sync cron
  • scoreboard/scoring
  • challenge analytics
  • demo pipeline/RPC/queues
  • Supabase schema/RLS
• Use rg to find all references before editing.
• If touching multiple services, use Flashback MCP for live context when available.

API/client rules

• Client/shared code should use apiClient, apiGet, apiPost, apiPut, apiDelete.
• Do not add raw fetch from client code unless there is a strong reason.
• Keep OpenAPI schema/types in mind when changing route shapes.
• Existing deprecated challenge client files:
  • src/hooks/useChallenges.ts
  • src/lib/api/challenges.client.ts
• Prefer src/hooks/useApi.ts for new work.

Database rules

• Do not mutate production data manually unless explicitly asked.
• For investigation, use read-only SELECT queries.
• If adding columns used by routes, support rollout safety where possible:
  • routes may include fallback handling for missing columns (42703)
  • migrations should be backwards compatible when feasible
• Check generated Supabase types if schema changes require it.

Challenge registration rules

Registration depends on:

• Clerk auth/current user
• FACEIT identity in publicMetadata.faceit
• challenge visibility/org access
• date windows
• optional password hash
• users row existence
• user_challenges enrollment

Do not bypass these checks without an explicit product/security decision.

FACEIT sync rules

The production sync path is src/app/api/v1/cron/faceit-match-sync/route.ts.

Be careful with:

• API rate limits
• max participant limits
• history pagination/window filtering
• placement match detection
• Elo start/end baseline updates
• duplicate demo/pipeline creation
• challenge_faceit_matches upsert conflict key
• demo URL availability

Do not assume all FACEIT matches have demo URLs.

Scoreboard/scoring rules

• Challenge scoreboard stats should come from analyzed demos only.
• Do not use legacy user_games as a scoreboard fallback; source switching can make displayed match counts decrease.
• Paginate/chunk all high-volume scoreboard reads, including challenge_faceit_matches; Supabase/PostgREST returns only 1000 rows by default.
• scoring_config supports weighted metrics.
• Players may be unqualified if below minAnalyzedMatches.
• Placement matches can affect Elo gain display and eligibility.

Before changing scoring, inspect:

• src/app/api/v1/challenges/[challengeId]/scoreboard/route.ts
• src/types/api/scoreboard.dto.ts
• challenges.scoring_config for live challenge rows

Analytics rules

Analytics are per current user and registration-gated.

Key file:

• src/lib/challenges/challenge-analytics.server.ts

The user-facing demo processing states are:

• not_queued
• queued
• processing
• failed
• analyzed
• no_player_stats

Do not collapse these states unless UI/product explicitly wants less detail.

Demo pipeline rules

Read ../demo-pipeline/contracts/queues.md before changing pipeline integration.

Current queue flow:

create_pipeline_job
  -> demo_download queue
  -> faceit-downloader
  -> advance_demo_pipeline_stage
  -> demo_analyze queue
  -> analyst
  -> analyzed_demos + demo_* tables

Retry logic is mostly tracked on demo_pipeline, not by blindly redelivering download messages.

Testing suggestions

Depending on change:

• Run focused unit tests for changed lib files.
• For challenge analytics/scoring, run tests under src/__tests__/lib/challenges/.
• For route changes, inspect OpenAPI/schema impact.
• Do not run npm run build unless explicitly asked or before commit/push per repo instructions.

Useful targeted commands:

npm test -- src/__tests__/lib/challenges/challenge-analytics.server.test.ts
npm test -- src/__tests__/lib/challenges/challenge-match-outcome-backfill.test.ts
npm test -- src/__tests__/lib/challenges/challenge-access.server.test.ts

Common safe investigation command

rg -n "challenge_faceit_matches|faceit-match-sync|scoring_config|demo_player_match_stats|create_pipeline_job|useChallengeAnalytics" src supabase ../demo-pipeline