FidelusAleksander / FidelusAleksander/octomatch

Plan: Feature-flagged Supabase and local leaderboard modes

Open
#5 0 comments 1 reaction 2 assignees Claimed by @FidelusAleksander View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.