FidelusAleksander / FidelusAleksander/octomatch
Plan: Feature-flagged Supabase and local leaderboard modes
- Dominant language
- JavaScript
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
# Dual-Mode Leaderboard Plan (Feature Flag)
## Problem
Support two leaderboard modes behind a feature flag:
- **Default mode**: Supabase + GitHub OAuth (shared leaderboard).
- **Conference mode**: localStorage + manually entered username for passerby usage.
## Current State (from codebase)
- Frontend-only React + Vite app with game flow in `src/components/GameBoard.jsx`.
- Local persistence currently only stores a single best score in `src/data/gameStats.js`.
- No auth integration, no leaderboard module, no runtime feature-mode switch.
## Proposed Approach
Add a provider abstraction and select implementation by feature flag, defaulting to Supabase mode.
1. **Feature flag + mode selection**
- Add `VITE_LEADERBOARD_MODE` with values: `supabase` (default) or `local`.
- Add mode resolver helper (fallback to `supabase` on invalid value).
- Expose current mode to UI (small badge or debug text in non-prod optional).
2. **Shared leaderboard contract**
- Define common interface for both providers:
- `getSessionUser()`
- `signIn()` / `signOut()` (no-op in local mode except username handling)
- `submitScore(entry)`
- `getLeaderboard(limit)`
- Keep `GameBoard` mostly provider-agnostic by calling this interface.
3. **Supabase provider (default)**
- GitHub OAuth via Supabase Auth (`signInWithOAuth`).
- Backend tables/functions for leaderboard and profile mapping.
- Authoritative score writes + ranked reads (moves ASC, damage ASC, completedAt ASC).
4. **Local provider (conference mode)**
- Username input with validation, persisted as last-used local username.
- Leaderboard stored in localStorage (e.g., `octomatch-leaderboard-v1`).
- Same ranking logic and shape as Supabase mode for parity.
5. **UI/UX integration**
- In Supabase mode: show GitHub sign-in state and leaderboard from backend.
- In Local mode: show username field and local leaderboard.
- Reuse one leaderboard rendering component for both modes.
6. **Testing matrix**
- Unit tests for mode resolver and shared ranking helper.
- Provider tests: Supabase adapter (mock client), local adapter (localStorage).
- Component tests covering both modes and mode switch behavior.
7. **Deployment/configuration**
- Production default `.env`: `VITE_LEADERBOARD_MODE=supabase`.
- Conference deployment override: `VITE_LEADERBOARD_MODE=local`.
- Document setup for Supabase env vars and conference local-mode launch steps.
## Planned Todo Breakdown
1. Add `VITE_LEADERBOARD_MODE` config + resolver (default supabase).
2. Introduce shared leaderboard provider interface.
3. Implement Supabase auth/leaderboard provider.
4. Implement local username/localStorage provider.
5. Refactor GameBoard/UI to use provider abstraction.
6. Add tests for both modes and ranking parity.
7. Update docs/deploy config for prod vs conference mode.
## Notes
- This keeps one codebase and one UI while allowing environment-based mode switching.
- Conference mode intentionally avoids external auth/dependencies for fast setup on kiosks/demo stations.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.