dubs-server 1.0.0

package/MARCH_MADNESS_SURVIVOR.md

@@ -0,0 +1,254 @@
+# March Madness Survivor Pool - Development Notes
+
+**Last Updated:** February 4, 2026 (Late night session - bracket connectors complete!)
+**Status:** In Development (Core features working)
+
+## Feature Flag
+
+In `dubs-jackpot-spa/app/v2/page.tsx`:
+```javascript
+const ENABLE_MARCH_MADNESS = true; // Set to false to hide tab
+```
+
+---
+
+## Overview
+
+A "Survive or Die" pool where:
+- Users pay **once** to join (SOL entry fee)
+- Pick **ONE team per round** to win
+- If your team **loses** → you're **eliminated**
+- **Last survivors split the pot**
+
+---
+
+## What's Been Built
+
+### Backend (dubs-server)
+
+| File | Purpose |
+|------|---------|
+| `routes/survivorRoutes.js` | All API endpoints for survivor pools |
+| `controllers/survivorController.js` | Business logic (create pool, join, pick, resolve) |
+| `services/survivorSimulator.js` | Dev testing - mock teams, simulate rounds |
+| `services/survivorOracle.js` | Production - fetch ESPN results, resolve picks |
+
+### Frontend (dubs-jackpot-spa)
+
+| File | Purpose |
+|------|---------|
+| `app/v2/features/survivor/components/SurvivorTabContent.tsx` | Main UI - pools list, pool detail, picks |
+| `app/v2/features/survivor/components/bracket/BracketView.tsx` | Full tournament bracket visualization |
+| `app/v2/features/survivor/components/bracket/BracketRegion.tsx` | Single region (16 teams → Elite 8) |
+| `app/v2/features/survivor/components/bracket/BracketMatchup.tsx` | Single game slot (2 teams) |
+| `app/v2/features/survivor/services/survivorService.ts` | API client for survivor endpoints |
+| `app/v2/features/survivor/types/survivor-types.ts` | TypeScript interfaces |
+
+### Database Tables
+
+```sql
+survivor_pools          -- Pool settings (buy-in, current round, status)
+survivor_entries        -- User entries (is_alive, eliminated_at_round)
+survivor_picks          -- User picks per round (team, result)
+survivor_tournament_games  -- All tournament matchups (teams, scores, winner)
+```
+
+---
+
+## How Teams/Bracket Data Works
+
+### Current Setup (Development/Testing)
+
+Teams are **hardcoded mock data** in `survivorSimulator.js`:
+
+```javascript
+const MOCK_TEAMS = [
+  // 68 teams total (64 + 4 First Four)
+  { id: 'e1', name: 'Duke', seed: 1, region: 'EAST', logo: espnLogo(150) },
+  { id: 'w1', name: 'Florida', seed: 1, region: 'WEST', logo: espnLogo(57) },
+  { id: 's1', name: 'Auburn', seed: 1, region: 'SOUTH', logo: espnLogo(2) },
+  { id: 'm1', name: 'Houston', seed: 1, region: 'MIDWEST', logo: espnLogo(248) },
+  // ... etc
+];
+```
+
+**To generate bracket for testing:**
+```bash
+curl -X POST http://localhost:3001/api/survivor/dev/pools/1/generate-bracket
+```
+
+This creates Round of 64 games with standard seeding matchups (1v16, 8v9, 5v12, etc.)
+
+### Production (Real Tournament)
+
+After **Selection Sunday** (NCAA announces bracket):
+
+1. **Option A:** Import from ESPN API
+2. **Option B:** Admin uploads official bracket JSON
+3. **Option C:** Manual database entry
+
+The bracket structure (seeding matchups) is always the same - only team names change.
+
+---
+
+## User Flow
+
+```
+1. JOIN POOL
+   └── User pays SOL entry fee → entry created
+
+2. MAKE PICK (each round)
+   └── Select one team to win → pick saved
+   └── Can change pick until deadline
+
+3. ROUND RESOLVES
+   └── Oracle checks ESPN for final scores
+   └── Winners advance, losers eliminated
+
+4. PAYOUT
+   └── After Championship, survivors split pot
+```
+
+---
+
+## Key API Endpoints
+
+### Public
+- `GET /api/survivor/pools` - List all pools
+- `GET /api/survivor/pools/:id` - Pool details
+- `GET /api/survivor/pools/:id/games` - Tournament games
+- `GET /api/survivor/pools/:id/alive` - Surviving entries
+- `GET /api/survivor/pools/:id/eliminated` - Eliminated entries
+
+### Authenticated (require JWT)
+- `POST /api/survivor/pools/:id/join` - Join pool
+- `GET /api/survivor/pools/:id/my-entry` - User's entry + picks
+- `GET /api/survivor/pools/:id/teams` - Available teams to pick
+- `POST /api/survivor/pools/:id/pick` - Submit pick
+
+### Dev/Simulation (development only)
+- `POST /api/survivor/dev/pools/:id/generate-bracket` - Create mock bracket
+- `POST /api/survivor/dev/pools/:id/simulate-round` - Random results
+- `POST /api/survivor/dev/pools/:id/activate` - Set pool to active
+- `POST /api/survivor/dev/pools/:id/reset` - Reset to round 1
+
+---
+
+## Bracket View Features
+
+- **4 Regions:** South, West (left side) | East, Midwest (right side)
+- **Rounds:** R64 → R32 → Sweet 16 → Elite 8 → Final Four → Championship
+- **Zoom controls:** Scale 40% - 120% (default 75%)
+- **Round labels:** Each column has its own label (Round of 64, Round of 32, Sweet 16, Elite 8) that aligns with the bracket
+- **Connecting lines:**
+  - SVG lines between rounds within each region showing bracket flow
+  - Horizontal yellow lines from Elite 8 → Final Four (using `flex-1` to stretch)
+  - Vertical yellow lines from Final Four → Championship (absolutely positioned)
+- **Right side mirroring:** EAST/MIDWEST regions mirrored with `scaleX(-1)` so bracket flows toward center, but text flipped back to readable
+- **Final Four/Championship layout:**
+  - FF1 (top) connects SOUTH and EAST Elite 8 winners
+  - FF2 (bottom) connects WEST and MIDWEST Elite 8 winners
+  - Championship in center with vertical connectors from both Final Four games
+  - Vertical connector heights: FF1→Champ = 250px, FF2→Champ = 310px
+- **Visual states:**
+  - Green highlight = winner
+  - Grayed out = eliminated
+  - Red pulse = live game
+  - "TBD" = future matchup
+  - Yellow lines = Final Four/Championship connectors
+
+---
+
+## Testing Commands
+
+```bash
+# Create a test pool
+curl -X POST http://localhost:3001/api/survivor/pools \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Test Pool 2025","year":2025,"buyInLamports":"100000000"}'
+
+# Generate bracket for pool ID 1
+curl -X POST http://localhost:3001/api/survivor/dev/pools/1/generate-bracket
+
+# Activate pool (move to round 2)
+curl -X POST http://localhost:3001/api/survivor/dev/pools/1/activate
+
+# Simulate round with 20% upset chance
+curl -X POST http://localhost:3001/api/survivor/dev/pools/1/simulate-round \
+  -H "Content-Type: application/json" \
+  -d '{"upsetChance":0.2}'
+```
+
+---
+
+## What's Left To Do
+
+### High Priority
+- [ ] **Real bracket import** - Admin endpoint to import actual NCAA bracket after Selection Sunday
+- [ ] **Round advancement** - Auto-create next round games when current round completes
+- [ ] **Oracle integration** - Connect to ESPN API for live scores
+- [ ] **Deadline enforcement** - Auto-eliminate users who don't pick before deadline
+- [ ] **Payout logic** - Distribute pot to survivors via Solana
+
+### Medium Priority
+- [ ] **Pick history display** - Show user's picks from previous rounds
+- [ ] **Leaderboard** - Show all alive/eliminated entries
+- [ ] **Notifications** - Email/push for deadlines, results
+- [ ] **Multiple entries** - Allow users to buy multiple entries
+
+### Polish
+- [x] **Bracket connector lines** - Visual lines connecting matchups ✓
+- [x] **Final Four/Championship connectors** - Vertical lines connecting FF to Championship ✓
+- [x] **Round column labels** - Labels aligned with each bracket column ✓
+- [ ] **Mobile responsive** - Better mobile bracket view
+- [ ] **Animations** - Transitions when winners revealed
+
+---
+
+## ESPN Team Logo URLs
+
+Logos come from ESPN CDN:
+```
+https://a.espncdn.com/i/teamlogos/ncaa/500/{espn_team_id}.png
+```
+
+Example ESPN team IDs:
+- Duke: 150
+- Florida: 57
+- Auburn: 2
+- Houston: 248
+
+Full list in `survivorSimulator.js` → `MOCK_TEAMS` array.
+
+---
+
+## Round Names
+
+```javascript
+const ROUND_NAMES = {
+  1: 'First Four',
+  2: 'Round of 64',
+  3: 'Round of 32',
+  4: 'Sweet 16',
+  5: 'Elite 8',
+  6: 'Final Four',
+  7: 'Championship',
+};
+```
+
+---
+
+## Questions for Tomorrow
+
+1. How should we import the real bracket after Selection Sunday?
+2. Should users be able to change their pick before the deadline?
+3. What happens if all remaining users pick the same losing team?
+4. Refund policy if tournament is cancelled?
+
+---
+
+## Related Files
+
+- **Plan document:** `~/.claude/plans/glittery-leaping-cocoa.md`
+- **Frontend:** `~/Developer/iheartsolana/dubs-jackpot-spa/app/v2/features/survivor/`
+- **Backend:** `~/Developer/iheartsolana/solana-programs/dubs-server/`

package/PANDA.md

@@ -0,0 +1,166 @@
+# PandaScore Data Structure
+
+## Overview
+
+PandaScore uses an opinionated, hierarchical data structure to map esports competitions across all video games. Understanding this hierarchy is critical for building betting features on top of it.
+
+## Hierarchy
+
+```
+Videogame (Valorant, CS2, LoL, Dota 2)
+  └── League (recurring competition — e.g. VCT Champions, ESL Pro League)
+        └── Series (single occurrence — e.g. VCT Champions 2026)
+              └── Tournament (stage — e.g. Group Stage, Playoffs)
+                    └── Match (confrontation — e.g. Team A vs Team B)
+                          └── Game (individual map/round)
+```
+
+## Levels Explained
+
+### Videogame
+The game itself. Each has a unique ID and slug.
+
+| ID | Name | Slug |
+|----|------|------|
+| 1 | League of Legends | league-of-legends |
+| 3 | Counter-Strike | cs-go |
+| 4 | Dota 2 | dota-2 |
+| 14 | Overwatch | ow |
+| 20 | PUBG | pubg |
+| 22 | Rocket League | rl |
+| 23 | Call of Duty | cod-mw |
+| 24 | Rainbow 6 Siege | r6-siege |
+| 25 | EA Sports FC | fifa |
+| 26 | Valorant | valorant |
+| 27 | King of Glory | kog |
+| 28 | LoL Wild Rift | lol-wild-rift |
+| 29 | StarCraft 2 | starcraft-2 |
+| 30 | StarCraft Brood War | starcraft-brood-war |
+| 34 | Mobile Legends | mlbb |
+
+### League
+The top-level competition. Think of it as the brand/name of a recurring event.
+- **Sports analogy**: FIFA World Cup, UEFA Champions League, NFL
+- **Esports examples**: VCT Champions, ESL Pro League, LCK, The International
+
+Key fields: `id`, `name`, `slug`, `image_url`, `videogame`, `series[]`
+
+### Series
+A single timely occurrence of a league. One league has many series over the years.
+- **Sports analogy**: FIFA World Cup 2022, NFL Season 2024
+- **Esports examples**: VCT Champions 2026, ESL Pro League Season 21
+
+Key fields: `id`, `full_name`, `year`, `season`, `begin_at`, `end_at`, `winner_id`, `league_id`
+
+### Tournament
+A stage or phase within a series. This is where standings and brackets live.
+- **Sports analogy**: FIFA World Cup 2022 — Group C, NFL 2024 — Playoffs
+- **Esports examples**: VCT Champions 2026 — Group Stage, The International 2026 — Playoffs
+
+Key fields: `id`, `name`, `type` (bracket type), `matches[]`, `teams[]`, `standings`
+
+### Match
+A confrontation between two opponents. **This is the betting level** — where you have two sides and an outcome.
+- **Sports analogy**: Denmark vs Australia
+- **Esports examples**: OG vs PSG.LGD (best of 5)
+
+Key fields: `id`, `name`, `status` (not_started/running/finished), `opponents[]`, `results[]`, `winner`, `begin_at`, `number_of_games`, `tournament_id`
+
+Match statuses:
+- `not_started` — scheduled, not yet live
+- `running` — currently being played
+- `finished` — completed with results
+- `canceled` — won't happen
+
+### Game
+An individual map or round within a match. Data structure varies per videogame.
+- **Sports analogy**: A single match has one game (Denmark vs Australia = 1 game)
+- **Esports examples**: A CS2 best-of-3 match has up to 3 games (maps)
+
+Game-level data is videogame-specific and only available for games supporting Historical Data.
+
+## Key Differences from Traditional Sports
+
+| Concept | Traditional Sports | Esports (PandaScore) |
+|---------|-------------------|----------------------|
+| Season structure | Fixed schedule (82 games, 17 weeks, etc.) | Tournament-based, variable |
+| "League" means | A fixed set of teams playing a season | Any recurring competition |
+| Regular season | Yes (months of scheduled games) | Rare — mostly events/tournaments |
+| Betting level | Individual game in the schedule | Match (within a tournament) |
+| Nesting depth | League → Season → Game | League → Series → Tournament → Match → Game |
+
+## For Dubs Betting
+
+The path to a bettable event:
+1. Pick relevant **Leagues** (curate a whitelist of league IDs worth betting on)
+2. Find active **Series** within those leagues (current year/season)
+3. Get **Tournaments** within those series (group stage, playoffs, etc.)
+4. List **Matches** within those tournaments — these are what users bet on
+5. Match `status: "not_started"` = upcoming and bettable
+
+## API Endpoints (Our Server)
+
+Current endpoints at `/api/esports`:
+
+```
+GET /api/esports/leagues                              — List all leagues
+GET /api/esports/leagues/:leagueId                    — Get single league
+GET /api/esports/videogames/:videogameId/leagues      — Leagues by game
+GET /api/esports/leagues/:id/series                   — Series within a league
+GET /api/esports/leagues/:id/tournaments              — Tournaments within a league
+GET /api/esports/leagues/:id/matches/upcoming         — Upcoming (bettable) matches
+GET /api/esports/leagues/:id/matches/running          — Currently live matches
+GET /api/esports/leagues/:id/matches                  — All matches (rich filtering)
+```
+
+### Key Response Fields by Endpoint
+
+**Series** — `full_name`, `year`, `season`, `begin_at`, `end_at`, `winner_id`, `tournaments[]`
+
+**Tournaments** — `name`, `tier` (s/a/b/c/d/unranked), `type` (online/offline), `prizepool`, `region`, `teams[]`, `matches[]`, `expected_roster[]`, `begin_at`, `end_at`
+
+**Matches** — `name`, `status`, `opponents[]`, `results[]`, `winner`, `begin_at`, `number_of_games`, `match_type` (best_of), `tournament`, `streams_list[]`, `games[]`, `live.url` (WebSocket), `serie`, `rescheduled`, `forfeit`, `draw`, `videogame_title`
+
+### Match Filtering (General `/matches` Endpoint)
+
+The general matches endpoint supports powerful filtering:
+- `filter[status]=running` — Live matches only
+- `filter[status]=not_started` — Upcoming only
+- `filter[status]=finished` — Completed only
+- `filter[future]=true` — Future matches (by begin_at)
+- `filter[past]=true` — Past matches
+- `filter[opponent_id]=123` — Matches involving a specific team/player
+- `filter[tournament_id]=456` — Matches in a specific tournament
+- `filter[serie_id]=789` — Matches in a specific series
+- `filter[opponents_filled]=true` — Only matches with known opponents (not TBD)
+- `filter[match_type]=best_of` — Filter by match format
+- `range[begin_at]=2026-01-01,2026-12-31` — Date range filter
+- `sort=-scheduled_at` — Sort by scheduled date (descending)
+
+## API Authentication
+
+PandaScore uses Bearer token auth:
+```
+Authorization: Bearer <PANDASCORE_API_KEY>
+```
+
+Environment variable: `PANDASCORE_API_KEY`
+
+## Pagination
+
+All list endpoints support:
+- `page` — page number (default: 1)
+- `per_page` — results per page (default: 50, max: 100)
+- `sort` — field to sort by (prefix with `-` for descending, e.g. `-modified_at`)
+
+## Filtering & Search
+
+- `filter[field]=value` — exact match filter
+- `search[field]=value` — fuzzy text search
+- `range[field]=min,max` — range filter
+
+## References
+
+- [PandaScore API Docs](https://developers.pandascore.co/docs/introduction)
+- [Data Structure Fundamentals](https://developers.pandascore.co/docs/fundamentals)
+- [Filtering & Sorting](https://developers.pandascore.co/docs/filtering-and-sorting)

package/Procfile

@@ -0,0 +1,4 @@
+web: node server.js
+oracle: node cron/oracleMonitor.js
+jackpot-keeper: node scripts/jackpot/keeper.js
+pickem-oracle: node cron/pickemOracleMonitor.js