be-components 7.4.8 → 7.5.1

package/lib/module/BetRouter/types/ADMIN_PORTAL.md

@@ -0,0 +1,863 @@
+# BetRouter Admin Portal - Implementation Guide
+
+This document provides comprehensive instructions for building an admin portal to manage the BetRouter system. The portal will help admins visualize and manage the one-to-many relationships between router entities, raw partner data, and partner links.
+
+## 📊 Architecture Overview
+
+BetRouter uses a **one-to-many architecture** with three layers:
+
+```
+┌─────────────────┐
+│  Router Layer   │  ← Canonical/normalized entities (source of truth)
+│  (router_*)     │
+└────────┬────────┘
+         │
+         ↓ (one-to-many)
+┌─────────────────┐
+│   Raw Layer     │  ← Partner-specific data (as-is from partners)
+│   (raw_*)       │
+└────────┬────────┘
+         │
+         ↓ (linked via)
+┌─────────────────┐
+│  Partner Layer  │  ← Junction table linking router ↔ raw
+│  (partner_*)    │
+└─────────────────┘
+```
+
+### Entity Types
+
+The system manages 4 core entities, each with this three-layer structure:
+
+1. **Leagues** - Sports leagues (NBA, NFL, MLB, etc.)
+2. **Contests** - Individual games/matches
+3. **Participants** - Teams, athletes, or event-level entities
+4. **Markets** - Betting markets (moneyline, spread, player props, etc.)
+
+## 🔄 Data Flow & Workflows
+
+### 1. League Setup (Foundation)
+
+**Step 1: Load Raw Leagues from Partners**
+```http
+POST /leagues/load-raw
+Content-Type: application/json
+
+{
+  "partner_id": "partner-123"
+}
+```
+
+Response:
+```json
+{
+  "message": "Raw leagues loaded successfully",
+  "count": 5,
+  "raw_leagues": [
+    {
+      "raw_league_id": "raw-league-1",
+      "partner_id": "partner-123",
+      "external_id": "mlb-2024",
+      "name": "Major League Baseball",
+      "status": "active"
+    }
+  ]
+}
+```
+
+**Step 2: Create Router League (if doesn't exist)**
+```http
+POST /leagues/router
+Content-Type: application/json
+
+{
+  "name": "MLB",
+  "status": "active"
+}
+```
+
+**Step 3: Link Raw League to Router League**
+```http
+POST /leagues/link
+Content-Type: application/json
+
+{
+  "raw_league_ids": ["raw-league-1", "raw-league-2"],
+  "router_league_id": "router-league-abc"
+}
+```
+
+This creates `partner_league` records linking the raw leagues to the router league.
+
+---
+
+### 2. Contest Setup (Games/Matches)
+
+**Step 1: Load Router Contests from BettorEdge**
+```http
+POST /contests/load
+Content-Type: application/json
+
+{
+  "router_league_id": "router-league-abc"
+}
+```
+
+This loads all active contests for the league from BettorEdge (the primary source) and creates `router_contest` records.
+
+**Step 2: Load Raw Contests from Other Partners**
+```http
+POST /contests/load-raw
+Content-Type: application/json
+
+{
+  "partner_id": "partner-123",
+  "router_league_id": "router-league-abc"
+}
+```
+
+This loads contests from a specific partner (Kalshi, BetOpenly) and creates `raw_contest` records ready for linking.
+
+**Step 3: Link Raw Contests to Router Contests**
+```http
+POST /contests/link
+Content-Type: application/json
+
+{
+  "raw_contest_ids": ["raw-contest-1"],
+  "router_contest_id": "router-contest-xyz"
+}
+```
+
+**Step 4: Check Contest Status (Periodically)**
+```http
+POST /contests/check-status
+```
+
+This updates contest statuses (open → closed → settled).
+
+**Important Order:**
+1. Load router contests FIRST (from BettorEdge)
+2. Then load raw contests from each partner
+3. Finally, link raw contests to router contests
+
+---
+
+### 3. Participant Setup (Teams/Athletes)
+
+**Step 1: Load Participants from Router League**
+
+For BettorEdge (creates both router and raw participants):
+```http
+POST /participants/load
+Content-Type: application/json
+
+{
+  "router_league_id": "router-league-abc"
+}
+```
+
+**Step 2: Load Raw Participants by Partner**
+
+For other partners:
+```http
+POST /participants/load-raw
+Content-Type: application/json
+
+{
+  "partner_id": "partner-123",
+  "router_league_id": "router-league-abc"
+}
+```
+
+**Step 3: Link Participants**
+```http
+POST /participants/link
+Content-Type: application/json
+
+{
+  "raw_participant_ids": ["raw-participant-1", "raw-participant-2"],
+  "router_participant_id": "router-participant-abc"
+}
+```
+
+---
+
+### 4. Market Setup (Betting Markets)
+
+**Step 1: Initialize Router Markets**
+
+First, set up the foundational markets:
+```bash
+npm run init:moneyline
+```
+
+This creates the moneyline market with home/away sides.
+
+**Step 2: Load Raw Markets for a Contest**
+```http
+POST /markets/load-raw
+Content-Type: application/json
+
+{
+  "partner_id": "partner-123",
+  "router_contest_id": "router-contest-xyz"
+}
+```
+
+**Step 3: Link Raw Market to Router Market**
+```http
+POST /markets/link
+Content-Type: application/json
+
+{
+  "raw_market_id": "raw-market-1",
+  "router_market_id": "router-market-moneyline",
+  "market_side_id": "market-side-home",
+  "partner_participant_id": "pp-lakers-123",
+  "timeframe_id": "tf-full-game",
+  "variable": 0,
+  "variable_type": "total",
+  "price_key": "yes"
+}
+```
+
+This creates a `partner_market` record with all the required relationships.
+
+---
+
+## 🎨 UI Components to Build
+
+### 1. League Management Page
+
+**View: League List**
+- Display all `router_leagues`
+- For each router league, show:
+  - Name
+  - Status
+  - Count of linked partner leagues (e.g., "2/3 partners linked")
+  - List of which partners are linked (BettorEdge ✓, Kalshi ✗, BetOpenly ✓)
+  - Count of contests in this league
+
+**Actions:**
+- Load raw leagues from partner (dropdown to select partner)
+- Create new router league
+- **Link additional raw leagues to router league** (can link multiple times to add more partners)
+
+**Important: One-to-Many Linking**
+- A `router_league` can have **multiple** `raw_leagues` linked to it (one per partner)
+- The UI should ALWAYS allow the admin to add more `raw_leagues` to a `router_league`
+- Even if a `router_league` already has raw leagues linked, the "Link League" button should remain available
+- The endpoint `GET /leagues/:router_league_id/available-raw/:partner_id` returns both unlinked and already-linked raw leagues
+
+**Key Endpoints:**
+```http
+GET /leagues/router
+GET /leagues/:router_league_id/available-raw/:partner_id
+POST /leagues/load-raw
+POST /leagues/link
+```
+
+---
+
+### 2. Contest Management Page
+
+**View: Contest List**
+- Filter by `router_league_id`
+- By default, display only ACTIVE `router_contests` (status='open') for selected league
+- For each contest show:
+  - Contest label (e.g., "Yankees vs Red Sox")
+  - Scheduled datetime
+  - Status (should all be 'open' by default)
+  - Count of linked partner contests (e.g., "2/3 partners linked")
+  - List of which partners are linked (BettorEdge ✓, Kalshi ✓, BetOpenly ✗)
+  - Count of linked markets
+
+**Query Parameters:**
+- `status` (optional): Filter by contest status
+  - Default: `'open'` - Returns all active/open contests
+  - `'closed'` - Returns closed contests with pagination (max 100 per page)
+- `offset` (optional): Pagination offset for closed contests
+  - Only used when `status='closed'`
+  - Default: `0`
+  - Example: `offset=100` for page 2, `offset=200` for page 3
+
+**Response includes:**
+- `router_contests[]` - Array of contests (all active OR up to 100 closed)
+- `total_count` - Total number of contests matching the filter
+- `has_more` - Boolean indicating if more results are available (for pagination)
+
+**Actions:**
+- Load raw contests by partner + league
+- Create router contest manually
+- **Link additional raw contests to router contest** (can link multiple times to add more partners)
+- **Auto-link contests** - Automatically match and link all contests for a partner (recommended)
+- View/load markets for contest
+- Check contest status
+
+**Important: One-to-Many Linking**
+- A `router_contest` can have **multiple** `raw_contests` linked to it (one per partner)
+- The UI should ALWAYS allow the admin to add more `raw_contests` to a `router_contest`
+- Even if a `router_contest` already has raw contests linked, the "Link Contest" button should remain available
+- Example: Router contest "Lakers vs Celtics" can have:
+  - BettorEdge raw contest (external_id: "be-12345")
+  - Kalshi raw contest (external_id: "KXNBA-LAL-BOS")
+  - BetOpenly raw contest (external_id: "bo-67890")
+- The UI should show which partners are already linked and allow adding more
+
+**Key Endpoints:**
+```http
+GET /contests/router?status=open
+GET /contests/open/:router_league_id
+GET /contests/:router_contest_id/available-raw/:partner_id
+POST /contests/load-raw
+POST /contests/link
+POST /autolinking/contests  ← Auto-link (recommended)
+```
+
+**Auto-Linking Contests:**
+Instead of manually linking contests one-by-one, use auto-linking to automatically match contests for a partner.
+
+**IMPORTANT:** Auto-linking only processes ACTIVE router_contests (status='open'). Closed or settled contests are excluded from autolinking.
+
+```http
+POST /autolinking/contests
+Content-Type: application/json
+
+{
+  "router_league_id": "league-nba-123",
+  "partner_id": "kalshi-partner-id"
+}
+```
+
+Response:
+```json
+{
+  "message": "Auto-linking complete: 23/25 matched (23 created, 0 updated)",
+  "entity_type": "contest",
+  "partner_name": "Kalshi",
+  "total_router_entities": 25,
+  "matched_count": 23,
+  "created_count": 23,
+  "updated_count": 0,
+  "failed_count": 2,
+  "results": [
+    {
+      "success": true,
+      "router_entity_id": "contest-123",
+      "partner_id": "kalshi-partner-id",
+      "partner_name": "Kalshi",
+      "raw_entity_id": "raw-kalshi-1",
+      "partner_entity_id": "pc-new-1",
+      "confidence": 0.95,
+      "match_method": "date_and_participants"
+    }
+  ]
+}
+```
+
+Auto-linking matches contests based on:
+- Scheduled datetime similarity
+- Participant matching
+- Title similarity
+
+Benefits:
+- Much faster than manual linking
+- Consistent matching logic
+- Provides confidence scores
+- Shows which contests failed to match for manual review
+
+**Recommended UI Flow:**
+```
+Contest Card: "Lakers vs Celtics"
+├─ Scheduled: 2024-01-15 7:00 PM
+├─ Status: Open
+├─ Linked Partners:
+│  ├─ ✓ BettorEdge (external_id: be-12345)
+│  ├─ ✓ Kalshi (external_id: KXNBA-LAL-BOS)
+│  └─ ✗ BetOpenly (not linked)
+└─ Actions:
+   ├─ [+ Link Another Partner]  ← Always available
+   └─ [View Markets]
+```
+
+---
+
+### 3. Participant Management Page
+
+**View: Participant List (League-Specific)**
+- **Important:** Participants are accessed within a league context
+- Navigate to participants via: League → Participants
+- Filter by `participant_type` (team/athlete/event)
+- Display `router_participants` for the selected league only
+- For each participant show:
+  - Name
+  - Type
+  - League
+  - BettorEdge ID
+  - Tags (name variations)
+  - Count of linked partner participants (e.g., "2/3 partners linked")
+  - List of which partners are linked (BettorEdge ✓, Kalshi ✓, BetOpenly ✗)
+
+**API Call:** `GET /participants/router?router_league_id=league-nba-123`
+
+**Actions:**
+- Load participants from BettorEdge (creates both router + raw for the league)
+- Load raw participants by partner for the league
+- **Link additional raw participants to router participant** (can link multiple times to add more partners)
+- Edit participant tags for better matching
+
+**Important: League-Specific Participants**
+- Router participants are **league-specific** - each belongs to exactly one league
+- "Dallas Cowboys" exists as a router participant in NFL
+- "LA Lakers" exists as a separate router participant in NBA
+- A `router_participant` can have **multiple** `raw_participants` linked to it (one per partner within that league)
+- The UI should ALWAYS allow the admin to add more `raw_participants` to a `router_participant`
+- Even if a `router_participant` already has raw participants linked, the "Link Participant" button should remain available
+- The endpoint `GET /participants/:router_participant_id/available-raw/:partner_id/:router_league_id` returns both unlinked and already-linked raw participants
+
+**Key Endpoints:**
+```http
+GET /participants/router?router_league_id=league-nba-123
+GET /participants/:router_participant_id/available-raw/:partner_id/:router_league_id
+POST /participants/load
+POST /participants/load-raw
+POST /participants/link
+```
+
+---
+
+### 4. Market Management Page
+
+**View: Market List by Contest**
+- Select a `router_contest_id`
+- Display all `router_markets` available
+- For each router market show:
+  - Market label (Moneyline, Spread, etc.)
+  - Category
+  - Variable required?
+  - Count of linked partner markets
+
+**Actions:**
+- Load raw markets for contest by partner
+- Link raw market to router market (with side, variable, etc.)
+- View market sides and variables
+
+**Key Endpoints:**
+```http
+GET /markets/router
+GET /markets/sides
+GET /markets/variables
+POST /markets/load-raw
+POST /markets/link
+```
+
+---
+
+## 🔍 Data Relationships Visual Guide
+
+### One-to-Many Example: Yankees vs Red Sox Contest
+
+```
+Router Contest
+┌─────────────────────────────────┐
+│ router_contest_id: "rc-001"     │
+│ contest_label: "Yankees vs Sox" │
+│ contest_id: "be-event-123"      │ ← BettorEdge source ID
+└─────────────────────────────────┘
+           ↓ one-to-many
+┌─────────────────────────────────┐
+│ Raw Contest (BettorEdge)        │
+│ raw_contest_id: "raw-001"       │
+│ partner_id: "bettoredge"        │
+│ external_id: "be-event-123"     │
+│ pretty_title: "NYY @ BOS"       │
+└─────────────────────────────────┘
+           ↓
+┌─────────────────────────────────┐
+│ Raw Contest (Kalshi)            │
+│ raw_contest_id: "raw-002"       │
+│ partner_id: "kalshi"            │
+│ external_id: "KXMLB-NYY-BOS"    │
+│ pretty_title: "Yankees @ Red Sox"│
+└─────────────────────────────────┘
+           ↓
+┌─────────────────────────────────┐
+│ Raw Contest (BetOpenly)         │
+│ raw_contest_id: "raw-003"       │
+│ partner_id: "betopenly"         │
+│ external_id: "bo-game-456"      │
+│ pretty_title: "NYY at BOS"      │
+└─────────────────────────────────┘
+           ↓ linked via
+┌─────────────────────────────────┐
+│ Partner Contest Records         │
+│ - partner_contest_id: "pc-001"  │
+│   raw_contest_id: "raw-001"     │
+│   router_contest_id: "rc-001"   │
+│                                 │
+│ - partner_contest_id: "pc-002"  │
+│   raw_contest_id: "raw-002"     │
+│   router_contest_id: "rc-001"   │
+│                                 │
+│ - partner_contest_id: "pc-003"  │
+│   raw_contest_id: "raw-003"     │
+│   router_contest_id: "rc-001"   │
+└─────────────────────────────────┘
+```
+
+### Market Linking Example: Moneyline Market
+
+```
+Router Market (Template)
+┌─────────────────────────────────┐
+│ router_market_id: "rm-001"      │
+│ market_key: "moneyline"         │
+│ market_label: "Moneyline"       │
+│ category: "game_result"         │
+└─────────────────────────────────┘
+           ↓ has sides
+┌────────────────┬────────────────┐
+│ Side: Home     │ Side: Away     │
+│ side_key: home │ side_key: away │
+└────────────────┴────────────────┘
+           ↓ for specific game
+┌─────────────────────────────────┐
+│ Raw Market (BettorEdge)         │
+│ raw_market_id: "rawm-001"       │
+│ partner_contest_id: "pc-001"    │
+│ external_id: "2"                │ ← BettorEdge market ID
+│ pretty_title: "Winner"          │
+└─────────────────────────────────┘
+           ↓ linked via
+┌─────────────────────────────────┐
+│ Partner Market (Home Side)      │
+│ partner_market_id: "pm-001"     │
+│ raw_market_id: "rawm-001"       │
+│ router_market_id: "rm-001"      │
+│ market_side_id: "side-home"     │
+│ router_market_variable_id: "v-0"│
+│ price_key: null                 │
+└─────────────────────────────────┘
+┌─────────────────────────────────┐
+│ Partner Market (Away Side)      │
+│ partner_market_id: "pm-002"     │
+│ raw_market_id: "rawm-001"       │
+│ router_market_id: "rm-001"      │
+│ market_side_id: "side-away"     │
+│ router_market_variable_id: "v-0"│
+│ price_key: null                 │
+└─────────────────────────────────┘
+```
+
+---
+
+## 📋 Complete Endpoint Reference
+
+### League Endpoints
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/leagues/router` | - | Get all router leagues |
+| GET | `/leagues/raw` | - | Get all raw leagues |
+| GET | `/leagues/partner` | - | Get all partner leagues |
+| GET | `/leagues/:router_league_id/available-raw/:partner_id` | - | Get available raw leagues to link. Returns `{ raw_leagues: [], already_linked: [] }` |
+| POST | `/leagues/load-raw` | `{ partner_id }` | Load raw leagues from partner |
+| POST | `/leagues/link` | `{ raw_league_ids[], router_league_id }` | Link raw leagues to router league |
+
+### Contest Endpoints
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| POST | `/contests/load` | `{ router_league_id }` | **Load router contests from BettorEdge** (primary source) for a league |
+| POST | `/contests/load-raw` | `{ partner_id, router_league_id }` | **Load raw contests from partner** (Kalshi, BetOpenly) for a league |
+| GET | `/contests/router?status=open` | - | Get router contests by status |
+| GET | `/contests/partner` | - | Get all partner contests |
+| GET | `/contests/open/:router_league_id?status=open&offset=0` | - | Get contests for league. Default: status='open' (all active). For status='closed': paginated, max 100 per page |
+| GET | `/contests/:router_contest_id` | - | Get specific contest |
+| GET | `/contests/:router_contest_id/available-raw/:partner_id` | - | Get available raw contests to link. Returns `{ raw_contests: [], already_linked: [] }` |
+| POST | `/contests/link` | `{ raw_contest_ids[], router_contest_id }` | Link raw contests to router contest (manual) |
+| POST | `/contests/check-status` | - | Check and update contest statuses |
+| POST | `/autolinking/contests` | `{ router_league_id, partner_id }` | **Auto-link all contests for a partner** (recommended) |
+
+### Participant Endpoints
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/participants/router?router_league_id=xxx` | - | Get router participants for a specific league (query param required) |
+| GET | `/participants/raw` | - | Get all raw participants |
+| GET | `/participants/partner` | - | Get all partner participants |
+| GET | `/participants/:router_participant_id/available-raw/:partner_id/:router_league_id` | - | Get available raw participants to link for a specific league context. Returns `{ raw_participants: [], already_linked: [] }` |
+| POST | `/participants/load` | `{ router_league_id }` | **Load router participants from BettorEdge** for a league |
+| POST | `/participants/load-raw` | `{ partner_id, router_league_id }` | **Load raw participants from partner** for a league |
+| POST | `/participants/link` | `{ raw_participant_ids[], router_participant_id }` | Link raw participants to router participant |
+
+**Important:** Router participants are now **league-specific**. Each participant belongs to exactly one league. When querying `/participants/router`, always include the `router_league_id` query parameter to filter participants for the league you're working with.
+
+### Market Endpoints
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/markets/router` | - | Get all router markets |
+| GET | `/markets/variables` | - | Get all market variables |
+| GET | `/markets/sides` | - | Get all market sides |
+| GET | `/markets/partner` | - | Get all partner markets |
+| GET | `/markets/raw/:router_contest_id` | - | Get raw markets for contest |
+| POST | `/markets/load-raw` | `{ partner_id, router_contest_id }` | Load raw markets by partner |
+| POST | `/markets/link` | `{ raw_market_id, router_market_id, market_side_id, variable?, variable_type?, price_key? }` | Link raw market to router market |
+
+### Partner Endpoints
+
+| Method | Endpoint | Body | Description |
+|--------|----------|------|-------------|
+| GET | `/partners` | - | Get all active partners with their options (including price_key_required, price_key_options) |
+| POST | `/partners/load` | - | Create default partners if they don't exist |
+
+**Partner Options Structure:**
+```typescript
+{
+  partner_id: "kalshi-123",
+  name: "Kalshi",
+  status: "active",
+  options: {
+    price_key_required: true,      // If true, admin must provide price_key when linking
+    price_key_options: ["yes", "no"] // Valid options for price_key
+  }
+}
+```
+
+---
+
+## 💡 UI/UX Recommendations
+
+### 1. Dashboard Home
+- Show summary statistics:
+  - Total router leagues
+  - Total active contests
+  - Total router participants
+  - Total router markets
+  - Pending links (raw entities not yet linked)
+
+### 2. Linking Interface
+
+**Option A: Side-by-Side Selection**
+```
+┌─────────────────────┬─────────────────────┐
+│  Raw Entities       │  Router Entity      │
+│  (Checkboxes)       │  (Single Select)    │
+├─────────────────────┼─────────────────────┤
+│ ☑ BettorEdge: NYY   │ ○ Yankees           │
+│ ☑ Kalshi: YANKEES   │ ○ Red Sox           │
+│ ☐ BetOpenly: NYY    │ ○ Dodgers           │
+└─────────────────────┴─────────────────────┘
+         [Link Selected] Button
+```
+
+**Option B: Drag and Drop**
+```
+┌─────────────────────┐    ┌─────────────────────┐
+│  Raw Entities       │    │  Router Entity      │
+│                     │    │                     │
+│  [BettorEdge: NYY]  │───▶│  [Yankees]          │
+│  [Kalshi: YANKEES]  │    │                     │
+│  [BetOpenly: NYY]   │    │  Drop raw entities  │
+│                     │    │  here to link       │
+└─────────────────────┘    └─────────────────────┘
+```
+
+### 3. Filtering & Search
+- Filter contests by:
+  - League
+  - Status (open/closed/settled)
+  - Date range
+  - Has markets / No markets yet
+
+- Search participants by:
+  - Name
+  - Type (team/athlete)
+  - Has links / No links yet
+
+### 4. Bulk Operations
+- Allow selecting multiple raw entities and linking them at once
+- Batch load raw data from all partners for a league
+- Bulk status checks
+
+### 5. Visual Indicators
+- 🟢 Green: Fully linked (router + multiple raw + partner links)
+- 🟡 Yellow: Partially linked (router + some raw, missing others)
+- 🔴 Red: Unlinked (raw exists but no router/partner link)
+- ⚪ Gray: Inactive/closed
+
+---
+
+## 🔒 Authentication
+
+All endpoints require authentication. Include the auth token in headers:
+
+```javascript
+const headers = {
+  'Authorization': `Bearer ${token}`,
+  'Content-Type': 'application/json'
+};
+```
+
+---
+
+## 🚀 Suggested Build Order
+
+1. **Phase 1: Read-Only Views**
+   - League list
+   - Contest list
+   - Participant list
+   - Market list
+   - Partner list
+
+2. **Phase 2: Data Loading**
+   - Load raw leagues button
+   - Load raw contests button
+   - Load raw participants button
+   - Load raw markets button
+
+3. **Phase 3: Linking**
+   - Link leagues interface
+   - Link contests interface
+   - Link participants interface
+   - Link markets interface
+
+4. **Phase 4: Advanced Features**
+   - Bulk operations
+   - Search & filters
+   - Status checks
+   - Analytics dashboard
+
+---
+
+## 📦 TypeScript Types
+
+All types are available in `src/types/`. Import them in your client:
+
+```typescript
+import {
+  RouterLeagueProps,
+  RawLeagueProps,
+  PartnerLeagueProps,
+  RouterContestProps,
+  RawContestProps,
+  PartnerContestProps,
+  RouterParticipantProps,
+  RawParticipantProps,
+  PartnerParticipantProps,
+  RouterMarketProps,
+  RawMarketProps,
+  PartnerMarketProps,
+  MarketContestProps,
+  RouterMarketSideProps,
+  RouterMarketVariableProps
+} from './types/betrouter';
+```
+
+---
+
+## 🎯 Example: Complete Contest Setup Workflow
+
+```javascript
+// 1. Load raw contests from BettorEdge for NBA league
+const loadResponse = await fetch('/contests/load-raw', {
+  method: 'POST',
+  headers,
+  body: JSON.stringify({
+    partner_id: 'bettoredge-partner-id',
+    router_league_id: 'nba-router-league-id'
+  })
+});
+
+const { raw_contests } = await loadResponse.json();
+// Returns: [ { raw_contest_id, external_id, pretty_title, ... }, ... ]
+
+// 2. Admin reviews the raw contests and selects one to link
+// Let's say they select "Lakers vs Celtics"
+
+// 3. Check if router contest exists
+const routerContestsResponse = await fetch(
+  `/contests/open/nba-router-league-id`
+);
+const { router_contests } = await routerContestsResponse.json();
+
+// Find matching router contest by contest_id (BettorEdge source)
+const matchingRouterContest = router_contests.find(
+  rc => rc.contest_id === raw_contests[0].external_id
+);
+
+// 4. Link the raw contest to the router contest
+if (matchingRouterContest) {
+  await fetch('/contests/link', {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({
+      raw_contest_ids: [raw_contests[0].raw_contest_id],
+      router_contest_id: matchingRouterContest.router_contest_id
+    })
+  });
+}
+
+// 5. Now load markets for this contest
+const marketsResponse = await fetch('/markets/load-raw', {
+  method: 'POST',
+  headers,
+  body: JSON.stringify({
+    partner_id: 'bettoredge-partner-id',
+    router_contest_id: matchingRouterContest.router_contest_id
+  })
+});
+
+const { raw_markets } = await marketsResponse.json();
+// Returns: [ { raw_market_id, external_id, pretty_title, ... }, ... ]
+
+// 6. Link each raw market to appropriate router market
+// For example, link the moneyline market (external_id: "2")
+const moneylineRaw = raw_markets.find(rm => rm.external_id === "2");
+
+// Get router markets and sides
+const [routerMarkets, marketSides] = await Promise.all([
+  fetch('/markets/router').then(r => r.json()),
+  fetch('/markets/sides').then(r => r.json())
+]);
+
+const moneylineRouter = routerMarkets.find(rm => rm.market_key === "moneyline");
+const homeSide = marketSides.find(
+  s => s.router_market_id === moneylineRouter.router_market_id &&
+       s.side_key === "home"
+);
+
+// Link raw market to router market for home side
+await fetch('/markets/link', {
+  method: 'POST',
+  headers,
+  body: JSON.stringify({
+    raw_market_id: moneylineRaw.raw_market_id,
+    router_market_id: moneylineRouter.router_market_id,
+    market_side_id: homeSide.market_side_id,
+    variable: 0,
+    variable_type: 'total'
+  })
+});
+
+// Repeat for away side...
+```
+
+---
+
+## 📝 Notes
+
+- **IDs are UUIDs**: All entity IDs are randomly generated strings. Display human-readable labels in the UI.
+- **Denormalized fields**: `partner_id` and `external_id` are denormalized in junction tables for convenience.
+- **Batch operations**: Always use batch GET operations and work in memory before saving for performance.
+- **Status management**: Contests move through states: open → closed → settled. Markets can be active or closed.
+- **Variable types**: Markets can have variables (spreads/totals) with type 'spread' or 'total'.
+- **Price keys**: Kalshi markets use price_key ('yes'/'no') to indicate which side of the binary market to use. The `router_partners` table has `options.price_key_required` and `options.price_key_options` to indicate which partners require this field.
+- **Participant types**: Can be 'team', 'athlete', or 'event' (for event-level totals).
+- **Market categories**: 'game_result', 'team_stat', 'player_stat', 'game_stat'.
+
+---
+
+This guide provides everything needed to build a comprehensive admin portal for managing the BetRouter system!