be-components 7.4.7 → 7.5.1

package/lib/commonjs/BetRouter/types/ADMIN_PORTAL_SIMPLIFIED.md

@@ -0,0 +1,1881 @@
+# BetRouter Admin Portal - Simplified Workflow Guide
+
+This guide focuses on the **practical, entity-centric workflow** for managing BetRouter entities.
+
+## 🎯 Core Workflow
+
+### 1. **League Management** (Foundation Layer)
+
+League linking establishes the foundation for all other entities. Before you can link contests, participants, or markets, you must first ensure leagues are properly connected to partners.
+
+#### a) **League List** (Start Here)
+
+**Endpoint:** `GET /leagues/router`
+
+Display all router leagues as the entry point:
+
+```json
+[
+  {
+    "router_league_id": "league-nba-123",
+    "name": "NBA",
+    "status": "active"
+  },
+  {
+    "router_league_id": "league-mlb-456",
+    "name": "MLB",
+    "status": "active"
+  }
+]
+```
+
+**UI:** Simple list showing leagues with link status.
+
+#### b) **League Detail & Linking** (Click on a League)
+
+When admin clicks on a specific league, show the league detail page.
+
+**Get League Info with Partner Status**
+
+**Endpoint:** `GET /leagues/router` (filter by ID in client)
+
+Shows the league and which partners are linked:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NBA League                                                  │
+│  Status: Active                                              │
+│                                                              │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │ Partner Links                                         │ │
+│  ├───────────────────────────────────────────────────────┤ │
+│  │                                                       │ │
+│  │ BettorEdge        ✅ Linked (1 league)               │ │
+│  │   external_id: nba-league-2024                       │ │
+│  │                                                       │ │
+│  │ Kalshi            ❌ Not Linked                      │ │
+│  │   [Load Available Leagues] button                    │ │
+│  │                                                       │ │
+│  │ BetOpenly         ✅ Linked (1 league)               │ │
+│  │   external_id: nba-2024-season                       │ │
+│  │                                                       │ │
+│  └───────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Manage League Links] [View Contests] [View Participants] │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### c) **Load Available Raw Leagues for a Partner**
+
+**NEW ENDPOINT:** `GET /leagues/:router_league_id/available-raw/:partner_id`
+
+This shows available raw leagues from a specific partner that can be linked to this router league:
+
+```json
+{
+  "router_league": {
+    "router_league_id": "league-nba-123",
+    "name": "NBA",
+    "status": "active"
+  },
+  "raw_leagues": [
+    {
+      "raw_league_id": "raw-kalshi-nba-1",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA",
+      "name": "NBA Basketball",
+      "status": "active"
+    },
+    {
+      "raw_league_id": "raw-kalshi-nba-2",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-RS",
+      "name": "NBA Regular Season",
+      "status": "active"
+    }
+  ],
+  "already_linked": [
+    {
+      "raw_league_id": "raw-kalshi-nba-3",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-PO",
+      "name": "NBA Playoffs",
+      "status": "active"
+    },
+    {
+      "raw_league_id": "raw-kalshi-nba-4",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-ALL",
+      "name": "NBA All-Star",
+      "status": "active"
+    }
+  ]
+}
+```
+
+**Key Features:**
+- Only shows raw leagues from the selected partner
+- `raw_leagues` array contains leagues available to link (not yet linked)
+- `already_linked` array contains leagues that are already linked
+- **UI should display BOTH sections** so admin can see what's already connected
+
+#### d) **Link Raw Leagues**
+
+**Endpoint:** `POST /leagues/link`
+
+```json
+{
+  "raw_league_ids": ["raw-kalshi-nba-1", "raw-kalshi-nba-2"],
+  "router_league_id": "league-nba-123"
+}
+```
+
+Response:
+
+```json
+{
+  "message": "Successfully linked 2 partner league(s)",
+  "partnerLeagues": [
+    {
+      "partner_league_id": "pl-new-1",
+      "raw_league_id": "raw-kalshi-nba-1",
+      "router_league_id": "league-nba-123",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA"
+    },
+    {
+      "partner_league_id": "pl-new-2",
+      "raw_league_id": "raw-kalshi-nba-2",
+      "router_league_id": "league-nba-123",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-RS"
+    }
+  ]
+}
+```
+
+**Why Multiple Leagues?**
+Some partners (like Kalshi) have multiple series/leagues that map to a single router league. For example:
+- Router League: "NBA"
+- Kalshi Raw Leagues: "KXNBA" (general), "KXNBA-RS" (regular season), "KXNBA-PO" (playoffs)
+
+All three Kalshi leagues should link to the same NBA router league.
+
+#### e) **When "Load Available Leagues" is clicked:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Kalshi Leagues for "NBA"                          [Close X]│
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Already Linked (2)                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │                                                        │ │
+│  │ ✅ KXNBA-PO                                           │ │
+│  │    NBA Playoffs                                       │ │
+│  │    Status: Active                                     │ │
+│  │    [Unlink]                                           │ │
+│  │                                                        │ │
+│  │ ✅ KXNBA-ALL                                          │ │
+│  │    NBA All-Star                                       │ │
+│  │    Status: Active                                     │ │
+│  │    [Unlink]                                           │ │
+│  │                                                        │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Available to Link (2)                                  │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │                                                        │ │
+│  │ ☑ KXNBA                                               │ │
+│  │   NBA Basketball                                      │ │
+│  │   Status: Active                                      │ │
+│  │                                                        │ │
+│  │ ☑ KXNBA-RS                                            │ │
+│  │   NBA Regular Season                                  │ │
+│  │   Status: Active                                      │ │
+│  │                                                        │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Link Selected]  [Cancel]                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### 2. **Load Contests for a League** (Admin Operation)
+
+Before viewing contests, the admin needs to load them from partner APIs into the system.
+
+#### a) **Load Router Contests from BettorEdge** (Primary Source)
+
+**Endpoint:** `POST /contests/load`
+
+BettorEdge is the primary source for router contests. Load contests for a specific league:
+
+**Request:**
+```json
+{
+  "router_league_id": "league-nba-123"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Contests loaded successfully",
+  "count": 25,
+  "contests": [
+    {
+      "router_contest_id": "contest-123",
+      "router_league_id": "league-nba-123",
+      "contest_label": "NBA: Lakers vs Celtics",
+      "contest_id": "be-event-789",
+      "scheduled_datetime": "2025-10-30T19:00:00Z",
+      "status": "open"
+    }
+  ]
+}
+```
+
+**When to use:**
+- When first setting up a league
+- To load new/upcoming contests
+- Periodically to refresh the contest list
+
+**UI Flow:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NBA League                                                  │
+│  Status: Active                                              │
+│                                                              │
+│  [Load Router Contests from BettorEdge] ← Button            │
+│                                                              │
+│  This will fetch all active NBA contests from BettorEdge    │
+│  and create router_contest records.                         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### b) **Load Raw Contests from Other Partners**
+
+**Endpoint:** `POST /contests/load-raw`
+
+After loading router contests, load raw contests from each partner (Kalshi, BetOpenly):
+
+**Request:**
+```json
+{
+  "partner_id": "kalshi-partner-id",
+  "router_league_id": "league-nba-123"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Raw contests loaded successfully",
+  "count": 30,
+  "raw_contests": [
+    {
+      "raw_contest_id": "raw-kalshi-1",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-30OCT-LAL-BOS",
+      "pretty_title": "Lakers vs Celtics",
+      "scheduled_datetime": "2025-10-30T19:00:00Z",
+      "status": "active"
+    }
+  ]
+}
+```
+
+**When to use:**
+- After loading router contests
+- Before linking contests to partners
+- To refresh available contests from a partner
+
+**UI Flow:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NBA League - Partner Contest Loading                       │
+│                                                              │
+│  Load raw contests from:                                    │
+│                                                              │
+│  ☐ Kalshi          [Load Contests]                          │
+│  ☐ BetOpenly       [Load Contests]                          │
+│                                                              │
+│  These will fetch contests from each partner's API and      │
+│  store them as raw_contest records ready for linking.       │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Important:**
+- Load router contests FIRST (from BettorEdge)
+- Then load raw contests from other partners
+- Finally, link raw contests to router contests using the linking workflow
+
+---
+
+### 3. **Contest List** (Within Selected League)
+
+**Endpoint:** `GET /contests/open/:router_league_id?status=open&offset=0`
+
+Once contests are loaded for a league, show contests based on status filter:
+
+**Default Behavior (Active Contests):**
+```http
+GET /contests/open/:router_league_id
+GET /contests/open/:router_league_id?status=open
+```
+
+Response:
+```json
+{
+  "router_contests": [
+    {
+      "router_contest_id": "contest-123",
+      "contest_label": "NBA: Lakers vs Celtics",
+      "scheduled_datetime": "2025-10-30T19:00:00Z",
+      "status": "open"
+    }
+  ],
+  "total_count": 25,
+  "has_more": false
+}
+```
+
+**Closed Contests (Paginated):**
+```http
+GET /contests/open/:router_league_id?status=closed&offset=0
+GET /contests/open/:router_league_id?status=closed&offset=100  // Page 2
+```
+
+Response (max 100 results):
+```json
+{
+  "router_contests": [
+    {
+      "router_contest_id": "contest-456",
+      "contest_label": "NBA: Warriors vs Nets",
+      "scheduled_datetime": "2025-10-25T19:00:00Z",
+      "status": "closed"
+    }
+    // ... up to 100 contests
+  ],
+  "total_count": 250,
+  "has_more": true  // More results available
+}
+```
+
+**Query Parameters:**
+- `status` (optional): `'open'` (default) or `'closed'`
+- `offset` (optional): Pagination offset for closed contests (default: 0)
+
+**UI:** Table showing:
+- Contest label (clickable to view details)
+- Scheduled time
+- Status
+- Number of partners linked (badge showing "2/3 partners")
+- **Pagination controls** (only when viewing closed contests)
+
+**IMPORTANT:**
+- Active contests: Returns ALL open contests (no pagination needed)
+- Closed contests: Returns max 100 at a time with pagination
+- Autolinking only processes ACTIVE contests
+
+**UI Example - Pagination for Closed Contests:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NBA → Contests                        [Status: Closed ▼]    │
+│                                                              │
+│  Showing 100 of 250 closed contests                         │
+│                                                              │
+│  [Contest List Table]                                        │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Page: [1] 2 3 ... 25              [Previous] [Next]    │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+
+When user clicks page 2:
+GET /contests/open/league-nba-123?status=closed&offset=100
+
+When user clicks page 3:
+GET /contests/open/league-nba-123?status=closed&offset=200
+```
+
+---
+
+### 3. **Contest Detail & Linking** (Click on a Contest)
+
+When admin clicks on a specific contest, show the contest detail page.
+
+#### a) Get Contest Info
+
+**Endpoint:** `GET /contests/:router_contest_id`
+
+Shows the contest and what's already linked:
+
+```json
+{
+  "router_contest": {
+    "router_contest_id": "contest-123",
+    "contest_label": "NBA: Lakers vs Celtics",
+    "scheduled_datetime": "2025-10-30T19:00:00Z"
+  },
+  "partner_contests": [
+    {
+      "partner_contest_id": "pc-1",
+      "partner_id": "bettoredge-partner-id",
+      "external_id": "be-event-789"
+    }
+  ]
+}
+```
+
+#### b) Get Available Partners
+
+**Endpoint:** `GET /partners`
+
+Shows which partners are active:
+
+```json
+[
+  {
+    "partner_id": "bettoredge-partner-id",
+    "name": "BettorEdge",
+    "status": "active"
+  },
+  {
+    "partner_id": "kalshi-partner-id",
+    "name": "Kalshi",
+    "status": "active"
+  },
+  {
+    "partner_id": "betopenly-partner-id",
+    "name": "BetOpenly",
+    "status": "active"
+  }
+]
+```
+
+#### c) Load Raw Contests for a Partner
+
+**NEW ENDPOINT:** `GET /contests/:router_contest_id/available-raw/:partner_id`
+
+This shows available raw contests from a specific partner that can be linked to this contest:
+
+```json
+{
+  "router_contest": {
+    "router_contest_id": "contest-123",
+    "contest_label": "NBA: Lakers vs Celtics"
+  },
+  "raw_contests": [
+    {
+      "raw_contest_id": "raw-kalshi-1",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-30OCT-LAL-BOS",
+      "pretty_title": "Lakers vs Celtics",
+      "scheduled_datetime": "2025-10-30T19:00:00Z"
+    },
+    {
+      "raw_contest_id": "raw-kalshi-2",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-30OCT-LAL-BOS-ALT",
+      "pretty_title": "Lakers @ Celtics",
+      "scheduled_datetime": "2025-10-30T19:00:00Z"
+    }
+  ],
+  "already_linked": []
+}
+```
+
+**Key Features:**
+- Only shows raw contests from the selected partner for this league
+- `raw_contests` array contains contests available to link (not yet linked to this router_contest)
+- `already_linked` array shows raw contests already linked to this router_contest
+- **UI should display BOTH sections** so admin can see what's already connected
+- **IMPORTANT:** The "Link Contest" or "Load Available Contests" button should ALWAYS be available, even if raw contests are already linked. Admins need to be able to add additional raw contests from different partners over time.
+
+#### d) Link Raw Contests
+
+**Endpoint:** `POST /contests/link`
+
+```json
+{
+  "raw_contest_ids": ["raw-kalshi-1"],
+  "router_contest_id": "contest-123"
+}
+```
+
+Response:
+
+```json
+{
+  "message": "Contest linking completed",
+  "count": 1,
+  "partner_contests": [
+    {
+      "partner_contest_id": "pc-new",
+      "raw_contest_id": "raw-kalshi-1",
+      "router_contest_id": "contest-123",
+      "partner_id": "kalshi-partner-id",
+      "external_id": "KXNBA-30OCT-LAL-BOS"
+    }
+  ]
+}
+```
+
+---
+
+### 4. **Auto-Link Contests** (Recommended for Bulk Linking)
+
+Instead of manually linking contests one-by-one, use auto-linking to automatically match and link contests for a partner based on scheduled time and participant matching.
+
+**IMPORTANT:** Auto-linking only processes ACTIVE router_contests (status='open'). This ensures:
+- Stats only count active contests (e.g., "23/25 matched" means 23 out of 25 active contests)
+- Closed or settled contests are excluded from the autolinking process
+- Partner contest counts only reflect links to active router contests
+
+#### **Endpoint:** `POST /autolinking/contests`
+
+**When to use:**
+- After loading raw contests from a partner
+- When you have many contests to link at once
+- To quickly connect a partner's contests without manual selection
+
+**Request:**
+```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"
+    },
+    {
+      "success": false,
+      "router_entity_id": "contest-456",
+      "partner_id": "kalshi-partner-id",
+      "partner_name": "Kalshi",
+      "confidence": 0,
+      "match_method": "none",
+      "error": "No matching raw contest found"
+    }
+  ]
+}
+```
+
+**UI Flow for Contest List:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NBA → Contests                              [🔗 Auto-Link]  │
+│                                                              │
+│  Showing 25 contests                                        │
+│                                                              │
+│  When clicked, show modal:                                  │
+│  ┌──────────────────────────────────────────────────────┐   │
+│  │  Auto-Link Contests                                  │   │
+│  │                                                      │   │
+│  │  Select partner to auto-link:                       │   │
+│  │                                                      │   │
+│  │  ○ Kalshi     (0/25 contests linked)                │   │
+│  │  ○ BetOpenly  (12/25 contests linked)               │   │
+│  │                                                      │   │
+│  │  This will attempt to automatically match and link   │   │
+│  │  contests based on scheduled time and participants.  │   │
+│  │                                                      │   │
+│  │  [Cancel]  [Auto-Link Selected Partner]             │   │
+│  └──────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+
+After auto-linking, show results:
+┌──────────────────────────────────────────────────────────┐
+│  Auto-Link Results                                       │
+│                                                          │
+│  ✅ Successfully linked: 23/25 contests                 │
+│  ❌ Failed: 2 contests                                  │
+│                                                          │
+│  Failed contests:                                        │
+│  • Lakers vs Celtics (Oct 30) - No match found          │
+│  • Warriors vs Nets (Oct 31) - No match found           │
+│                                                          │
+│  You can manually link these contests if needed.        │
+│                                                          │
+│  [Close]  [View Failed Contests]                        │
+└──────────────────────────────────────────────────────────┘
+```
+
+**Response Fields Explained:**
+- `total_router_entities`: Total number of ACTIVE router contests (status='open') checked for this league
+- `matched_count`: Number of active contests successfully matched
+- `created_count`: Number of new partner_contest records created
+- `updated_count`: Number of existing partner_contest records updated
+- `failed_count`: Number of active contests that couldn't be matched
+- `results[]`: Array of individual match results with details (only for active contests)
+  - `confidence`: 0-1 score indicating match quality (>0.8 is good)
+  - `match_method`: How the match was made (e.g., "date_and_participants", "exact_title_match")
+  - `partner_entity_id`: The created `partner_contest_id`
+
+**Best Practices:**
+1. **Load raw contests first** using `POST /contests/load-raw` before auto-linking
+2. **Review failed matches** - some contests may need manual linking
+3. **Run per partner** - auto-link one partner at a time to review results
+4. **Check confidence scores** - low confidence (<0.7) matches may need verification
+
+---
+
+## 🎨 Recommended UI Layout
+
+### Contest Detail Page
+
+**⚠️ IMPORTANT UI REQUIREMENT:**
+Each partner row should ALWAYS show a "Link Contest" or "Load Available Contests" button, regardless of whether a raw contest is already linked. This allows admins to:
+- Add additional raw contests from the same partner if multiple exist
+- Re-link if a contest was linked incorrectly
+- Maintain flexibility in the linking process
+
+**Never hide or disable the link button just because one raw contest is already linked.**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  ← Back to NBA Contests                                     │
+│                                                             │
+│  Lakers vs Celtics                                          │
+│  📅 October 30, 2025 at 7:00 PM ET                         │
+│  Status: Open                                               │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │ Partner Links                                         │ │
+│  ├───────────────────────────────────────────────────────┤ │
+│  │                                                       │ │
+│  │ BettorEdge        ✅ Linked                          │ │
+│  │   external_id: be-event-789                          │ │
+│  │   [+ Add Another] button  ← ALWAYS show this         │ │
+│  │                                                       │ │
+│  │ Kalshi            ❌ Not Linked                      │ │
+│  │   [Load Available Contests] button                   │ │
+│  │                                                       │ │
+│  │ BetOpenly         ✅ Linked                          │ │
+│  │   external_id: bo-game-456                           │ │
+│  │   [+ Add Another] button  ← ALWAYS show this         │ │
+│  │                                                       │ │
+│  └───────────────────────────────────────────────────────┘ │
+│                                                             │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │ Markets                                               │ │
+│  ├───────────────────────────────────────────────────────┤ │
+│  │                                                       │ │
+│  │ Moneyline         2 markets linked                   │ │
+│  │ Spread            0 markets linked                   │ │
+│  │                                                       │ │
+│  └───────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### When "Load Available Contests" is clicked:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Kalshi Contests for "Lakers vs Celtics"          [Close X] │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Already Linked (0)                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ No contests linked yet                                 │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Available to Link (2)                                  │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │                                                        │ │
+│  │ ☑ KXNBA-30OCT-LAL-BOS                                 │ │
+│  │   Lakers vs Celtics                                   │ │
+│  │   Oct 30, 2025 7:00 PM                                │ │
+│  │                                                        │ │
+│  │ ☑ KXNBA-30OCT-LAL-BOS-ALT                             │ │
+│  │   Lakers @ Celtics                                    │ │
+│  │   Oct 30, 2025 7:00 PM                                │ │
+│  │                                                        │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Link Selected]  [Cancel]                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🔄 Complete League Linking Flow
+
+```
+1. Admin views league list
+   ↓
+2. Admin clicks "NBA" league
+   ↓
+3. Page shows:
+   - League details
+   - Which partners are linked (✅ BettorEdge, ❌ Kalshi, ✅ BetOpenly)
+   ↓
+4. Admin clicks "Load Available Leagues" for Kalshi
+   ↓
+5. System calls: GET /leagues/:router_league_id/available-raw/:partner_id
+   ↓
+6. Modal/panel shows Kalshi raw leagues
+   ↓
+7. Admin selects matching league(s) - can select multiple (KXNBA, KXNBA-RS, etc.)
+   ↓
+8. Admin clicks "Link Selected"
+   ↓
+9. System calls: POST /leagues/link
+   ↓
+10. Success! Kalshi now shows ✅ Linked (2 leagues)
+```
+
+---
+
+## 🔄 Complete Contest Linking Flow
+
+```
+1. Admin selects "NBA" league (from league list)
+   ↓
+2. Admin clicks "View Contests" or navigates to contest list
+   ↓
+3. Admin sees list of contests (Lakers vs Celtics, etc.)
+   ↓
+4. Admin clicks "Lakers vs Celtics"
+   ↓
+5. Page shows:
+   - Contest details
+   - Which partners are linked (✅ BettorEdge, ❌ Kalshi, ✅ BetOpenly)
+   ↓
+6. Admin clicks "Load Available Contests" for Kalshi
+   ↓
+7. System calls: GET /contests/:router_contest_id/available-raw/:partner_id
+   ↓
+8. Modal/panel shows Kalshi contests from this league
+   ↓
+9. Admin selects matching contest(s)
+   ↓
+10. Admin clicks "Link Selected"
+    ↓
+11. System calls: POST /contests/link
+    ↓
+12. Success! Kalshi now shows ✅ Linked
+```
+
+---
+
+## 📋 Simplified Endpoint Summary
+
+### League Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/leagues/router` | List all leagues (entry point) |
+| GET | `/leagues/:router_league_id/available-raw/:partner_id` | Get available raw leagues to link |
+| POST | `/leagues/load-raw` | Load raw leagues from partner API |
+| POST | `/leagues/link` | Link raw leagues to router league (supports multiple) |
+
+### Contest Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/contests/load` | Load router contests from BettorEdge for a league |
+| POST | `/contests/load-raw` | Load raw contests from partner API for a league |
+| GET | `/contests/open/:router_league_id?status=open&offset=0` | List contests. Default: ACTIVE (status='open'). Closed: paginated (max 100) |
+| GET | `/contests/:router_contest_id` | Get contest details + existing links |
+| GET | `/contests/:router_contest_id/available-raw/:partner_id` | Get available raw contests to link |
+| POST | `/contests/link` | Link raw contests to router contest (manual) |
+| POST | `/autolinking/contests` | **Auto-link ACTIVE contests for a partner** (recommended) |
+
+### Participant Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/participants/router?router_league_id=xxx` | List participants for a specific league |
+| POST | `/participants/load` | Load router participants from BettorEdge for a league |
+| POST | `/participants/load-raw` | Load raw participants from partner API for a league |
+| GET | `/participants/:router_participant_id/available-raw/:partner_id/:router_league_id` | Get available raw participants to link |
+| POST | `/participants/link` | Link raw participants to router participant |
+
+### Other Endpoints
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/partners` | Get all active partners |
+
+---
+
+## 💡 Key Simplifications
+
+### What Changed:
+
+**BEFORE (Too Broad):**
+```http
+POST /contests/load-raw
+{
+  "partner_id": "kalshi-partner-id",
+  "router_league_id": "league-nba-123"
+}
+```
+Returns **ALL** Kalshi contests for NBA (could be 100+)
+
+**AFTER (Context-Specific):**
+```http
+GET /contests/:router_contest_id/available-raw/:partner_id
+```
+Returns only raw contests from that partner for that league, filtered to exclude already-linked ones
+
+### Why This is Better:
+
+1. **Scoped to context** - You're linking to a SPECIFIC contest, so you only see relevant raw contests
+2. **Already filtered** - Excludes raw contests that are already linked
+3. **Shows what you have** - Separate `already_linked` array so you know what's connected
+4. **Easier UI** - Can show directly in the contest detail page
+
+---
+
+## 🎯 Next Steps for Other Entities
+
+### 🏀 Participants (League-Level Management)
+
+Participants are managed at the **league level** - you access them through the league context, not separately.
+
+#### **Complete Participant Workflow**
+
+```
+1. Select league (NFL) from league list
+   ↓
+2. Click "View Participants" or navigate to Participants tab
+   ↓
+3. See list/search of router participants FOR THIS LEAGUE
+   - All NFL participants: Cowboys, 49ers, Mahomes, etc.
+   - Filter/search by name or type (team/athlete)
+   - Only shows participants belonging to the selected league
+   ↓
+4. Click on a router participant (e.g., "Dallas Cowboys")
+   ↓
+5. Participant detail page shows partner link status FOR THIS LEAGUE:
+   - BettorEdge: ✅ Linked in NFL (1 raw participant)
+   - Kalshi:     ❌ Not Linked in NFL [Load & Link]
+   - BetOpenly:  ✅ Linked in NFL (1 raw participant)
+   ↓
+6. Admin clicks "Load & Link" for Kalshi
+   ↓
+7. System calls: GET /participants/:router_participant_id/available-raw/:partner_id/:router_league_id
+   - Uses league context (NFL) to filter raw participants
+   ↓
+8. Modal shows:
+   - Already Linked in NFL section (if any)
+   - Available to Link in NFL section (raw participants from Kalshi for NFL)
+   ↓
+9. Admin selects matching raw participant(s)
+   ↓
+10. System calls: POST /participants/link
+    ↓
+11. Success! Kalshi now shows ✅ Linked in NFL
+```
+
+**Key Point:** Router participants are **league-specific** - each participant belongs to exactly one league. "Dallas Cowboys" exists as a router participant in NFL, and "LA Lakers" exists as a separate router participant in NBA.
+
+#### **Participant List Page (Accessed via League)**
+
+**Endpoint:** `GET /participants/router?router_league_id=league-nfl-123`
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NFL → Participants                              [Search 🔍] │
+│                                                              │
+│  Showing NFL participants (486 total)                       │
+│  League: NFL                                                │
+│                                                              │
+│  Filter: [All Types ▼] [Active ▼]                           │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Dallas Cowboys (Team)                                  │ │
+│  │ Partner links in NFL: BettorEdge ✅ Kalshi ❌ BO ✅   │ │
+│  │ [View Details]                                         │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ San Francisco 49ers (Team)                             │ │
+│  │ Partner links in NFL: BettorEdge ✅ Kalshi ✅ BO ✅   │ │
+│  │ [View Details]                                         │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ Patrick Mahomes (Athlete)                              │ │
+│  │ Partner links in NFL: BettorEdge ✅ Kalshi ❌ BO ❌   │ │
+│  │ [View Details]                                         │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ LeBron James (Athlete)                                 │ │
+│  │ Partner links in NFL: None (belongs to NBA)            │ │
+│  │ [View Details]                                         │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Note:** The list shows ALL router participants, but the link status shown is specific to the NFL league context. LeBron James would show up in the list, but with no NFL links since he belongs to NBA.
+
+#### **Participant Detail Page UI**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  NFL → Participants → Dallas Cowboys                         │
+│                                                              │
+│  Dallas Cowboys (Team)                                       │
+│  BettorEdge ID: team-dal-001                                │
+│  Tags: Dallas Cowboys, Cowboys, DAL                         │
+│                                                              │
+│  ┌───────────────────────────────────────────────────────┐ │
+│  │ Partner Links                                         │ │
+│  ├───────────────────────────────────────────────────────┤ │
+│  │                                                       │ │
+│  │ BettorEdge        ✅ Linked (1)                      │ │
+│  │   raw_name: Dallas Cowboys                           │ │
+│  │   external_id: team-dal-001                          │ │
+│  │                                                       │ │
+│  │ Kalshi            ❌ Not Linked                      │ │
+│  │   [Load & Link Participants] button                  │ │
+│  │                                                       │ │
+│  │ BetOpenly         ✅ Linked (2)                      │ │
+│  │   raw_name: Dallas Cowboys                           │ │
+│  │   external_id: dallas-cowboys-123                    │ │
+│  │   [View/Manage Links]                                │ │
+│  │                                                       │ │
+│  └───────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### **When "Load & Link Participants" is clicked:**
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Kalshi Participants for "Dallas Cowboys" (NFL)   [Close X] │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Already Linked (0)                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ No participants linked yet                             │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Available to Link (3)                                  │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │                                                        │ │
+│  │ ☑ kalshi-team-dallas-cowboys                          │ │
+│  │   Dallas Cowboys                                      │ │
+│  │   Type: Team                                          │ │
+│  │                                                        │ │
+│  │ ☐ kalshi-team-dallas                                  │ │
+│  │   Dallas                                              │ │
+│  │   Type: Team                                          │ │
+│  │                                                        │ │
+│  │ ☐ kalshi-team-cowboys                                 │ │
+│  │   Cowboys                                             │ │
+│  │   Type: Team                                          │ │
+│  │                                                        │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Link Selected]  [Cancel]                                  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### **Key Endpoints**
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/participants/router` | Get ALL router participants (global, not filtered by league) |
+| GET | `/participants/:router_participant_id/available-raw/:partner_id/:router_league_id` | Get available raw participants to link. Returns `{ raw_participants: [], already_linked: [] }`. League context determines which raw participants are shown. |
+| POST | `/participants/load-raw` | Load raw participants from partner API (if needed). Body: `{ partner_id, router_league_id }` |
+| POST | `/participants/link` | Link raw participants to router participant. Body: `{ raw_participant_ids[], router_participant_id }` |
+
+**Important:**
+- Router participants are **global entities** - the endpoint returns ALL of them
+- The league context (NFL, NBA, etc.) is only used when **viewing/linking raw participants** for a specific router participant
+- This allows admins to see all participants and manage their links across different leagues
+
+#### **Why Access via League Context?**
+
+- **League determines raw participants**: When linking, you need to know which league's raw participants to show
+- **Same name, different sports**: "Cowboys" might exist in NFL and college football - raw participants are scoped by league
+- **Participant types vary by sport**: NBA has teams + athletes, NFL has teams + athletes, horse racing has horses
+- **Workflow context**: Admin is managing NFL, so they access participants in that context
+- **BUT participants are global**: The router participant "Dallas Cowboys" exists once, can be linked to raw participants in multiple leagues if needed
+
+### Markets (Contest-Level)
+
+Markets are loaded at the **contest level**:
+
+```
+1. Select contest (Lakers vs Celtics)
+   ↓
+2. Go to "Markets" tab
+   ↓
+3. See list of router markets (Moneyline, Spread, etc.)
+   ↓
+4. For each router market:
+   - Show which partners have raw markets
+   - Button to load raw markets from missing partners
+   ↓
+5. Flow: GET /markets/:router_contest_id/:router_market_id/available-raw/:partner_id
+```
+
+---
+
+---
+
+## 📊 Step 4: Market Management (Within Contest)
+
+After contest linking, manage which markets are supported and link raw markets from partners.
+
+### Two-Step Market Process:
+
+#### **Step 4a: Define Supported Markets (market_contests)**
+
+**Get all available markets to manage:**
+
+```http
+GET /markets/available-to-support/:router_contest_id
+```
+
+Response shows all router markets and which are currently supported:
+
+```json
+{
+  "message": "Successfully fetched available markets",
+  "router_contest": {
+    "router_contest_id": "contest-123",
+    "contest_label": "Lakers vs Celtics"
+  },
+  "all_router_markets": [
+    {
+      "router_market_id": "rm-moneyline",
+      "market_label": "Moneyline",
+      "participant_type": "team"
+    },
+    {
+      "router_market_id": "rm-spread",
+      "market_label": "Spread",
+      "participant_type": "team"
+    },
+    {
+      "router_market_id": "rm-total",
+      "market_label": "Total Points",
+      "participant_type": "team"
+    }
+  ],
+  "market_contests": [
+    {
+      "market_contest_id": "mc-1",
+      "router_contest_id": "contest-123",
+      "router_market_id": "rm-moneyline",
+      "status": "open"
+    }
+  ]
+}
+```
+
+**UI Logic:**
+- Display all markets from `all_router_markets`
+- Check if each market is in `market_contests` to show as "supported" or "not supported"
+- Show add/remove buttons accordingly
+
+**Add a Supported Market:**
+
+```http
+POST /markets/supported
+{
+  "router_contest_id": "contest-123",
+  "router_market_id": "rm-spread"
+}
+```
+
+**Remove a Supported Market:**
+
+```http
+DELETE /markets/supported/:market_contest_id
+```
+
+#### **Step 4b: Link Raw Markets for Each Supported Market**
+
+**Endpoint:** `GET /markets/:router_contest_id/:router_market_id/available-raw/:partner_id`
+
+Shows available raw markets from a partner for a specific router market:
+
+```json
+{
+  "router_contest": { ... },
+  "router_market": {
+    "router_market_id": "rm-moneyline",
+    "market_label": "Moneyline"
+  },
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-moneyline",
+      "external_id": "2",
+      "pretty_title": "Winner"
+    }
+  ],
+  "already_linked": []
+}
+```
+
+**Link Raw Market:**
+
+```http
+POST /markets/link
+{
+  "raw_market_id": "raw-be-moneyline",
+  "router_market_id": "rm-moneyline",
+  "market_side_id": "side-home",
+  "partner_participant_id": "pp-lakers-123",
+  "timeframe_id": "tf-full-game",
+  "variable": 0,
+  "variable_type": "total",
+  "price_key": "yes"
+}
+```
+
+**🎯 SIMPLIFIED WORKFLOW:**
+
+**For Spread Markets:**
+- User enters the spread value **once** (e.g., `7` or `3.5`)
+- Single "Link Both Sides" button links both home and away
+- Client automatically:
+  - Creates home side with negative variable: `-7` (favorite)
+  - Creates away side with positive variable: `+7` (underdog)
+- Backend stores two separate signed variables
+
+**For Total Markets:**
+- User enters the total value **once** (e.g., `220.5`)
+- Both over/under sides use the same variable
+- Single variable created, both sides link to it
+
+**For Moneyline Markets:**
+- No variable needed (variable_required: false)
+- Link each side separately with just participant and timeframe
+
+**Variable Type Auto-Detection:**
+Each `router_market` now has a `default_variable_type` field:
+- Spread markets → defaults to `'spread'`
+- Total markets → defaults to `'total'`
+- The client can use this to determine the variable type automatically
+
+---
+
+## 📋 Adding Multiple Variables to a Market
+
+For markets that allow variables (like Spread), you can add **multiple variables** to the same market (e.g., -7, -3.5, -10).
+
+### New Endpoint: Variables and Raw Markets
+
+**Endpoint:** `GET /markets/:router_contest_id/:router_market_id/variables-and-raw/:partner_id`
+
+This endpoint shows:
+1. All existing variables for this market
+2. All available raw markets (can be linked with new variables)
+3. Which raw markets are already linked to which variables
+
+**Response:**
+```json
+{
+  "message": "Successfully fetched market variables and raw markets",
+  "router_contest": { ... },
+  "router_market": {
+    "router_market_id": "rm-spread",
+    "market_label": "Spread",
+    "default_variable_type": "spread",
+    ...
+  },
+  "existing_variables": [
+    {
+      "router_market_variable_id": "var-1",
+      "variable": -7,
+      "variable_type": "spread",
+      "linked_count": 2  // 2 partner markets (home + away)
+    },
+    {
+      "router_market_variable_id": "var-2",
+      "variable": -3.5,
+      "variable_type": "spread",
+      "linked_count": 2
+    }
+  ],
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-spread-1",
+      "external_id": "2000003|1",
+      "pretty_title": "Spread",
+      ...
+    }
+  ],
+  "already_linked_by_variable": {
+    "var-1": ["raw-be-spread-1"],  // This variable is already linked to this raw market
+    "var-2": ["raw-be-spread-1"]   // Same raw market can be linked multiple times
+  }
+}
+```
+
+### UI Workflow: Adding a Variable
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Spread Market - Lakers vs Celtics                      │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Existing Variables:                                     │
+│   • -7.0 (2 sides linked) ✓                            │
+│   • -3.5 (2 sides linked) ✓                            │
+│                                                         │
+│ [+ Add Variable]  ← Button to add new variable         │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+When "+ Add Variable" is clicked:
+
+┌─────────────────────────────────────────────────────────┐
+│ Add New Variable to Spread Market                      │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Variable: [10] ← User enters new variable value        │
+│                                                         │
+│ Raw Market:                                            │
+│   Partner: BettorEdge                                  │
+│   Market: Spread (GAME:Spread:Game)                   │
+│                                                         │
+│ Home Side:                                             │
+│   Participant: [Lakers ▼]                              │
+│   Timeframe: [Full Game ▼]                             │
+│   Price Key: [yes ▼]                                   │
+│                                                         │
+│ Away Side:                                             │
+│   Participant: [Celtics ▼]                             │
+│   Timeframe: [Full Game ▼]                             │
+│   Price Key: [no ▼]                                    │
+│                                                         │
+│ [Link Both Sides]  [Cancel]                            │
+└─────────────────────────────────────────────────────────┘
+```
+
+**What happens:**
+1. Client makes 2 API calls to `POST /markets/link`:
+   - First call: variable = `-10`, side = home
+   - Second call: variable = `+10`, side = away
+2. Backend automatically creates new `router_market_variable` records if they don't exist
+3. Backend creates `partner_market` records linking to the raw market
+
+**Result:** The same raw market is now linked 3 times:
+- With variable -7 (home) and +7 (away)
+- With variable -3.5 (home) and +3.5 (away)
+- With variable -10 (home) and +10 (away)
+
+---
+
+## 🏀 Multiple Participants for Prop Markets
+
+For **player prop markets** (like Passing Yards, Points, Rebounds), the `allow_multiple_participants` field enables linking multiple players to the same market.
+
+### How It Works
+
+**Market Setup:**
+```typescript
+{
+  "market_key": "passing_yards",
+  "market_label": "Passing Yards",
+  "category": "player_stat",
+  "participant_type": "player",
+  "variable_required": true,
+  "default_variable_type": "total",
+  "allow_multiple_participants": true  // ← Key feature
+}
+```
+
+### Endpoint Response
+
+The same `GET /markets/:router_contest_id/:router_market_id/variables-and-raw/:partner_id` endpoint now includes participant information:
+
+```json
+{
+  "router_market": {
+    "market_label": "Passing Yards",
+    "allow_multiple_participants": true,
+    ...
+  },
+  "existing_variables": [
+    {
+      "router_market_variable_id": "var-1",
+      "variable": 250.5,
+      "variable_type": "total",
+      "linked_count": 2  // over + under
+    },
+    {
+      "router_market_variable_id": "var-2",
+      "variable": 275.5,
+      "variable_type": "total",
+      "linked_count": 2
+    }
+  ],
+  "existing_participants": [
+    {
+      "partner_participant_id": "pp-mahomes",
+      "name": "Patrick Mahomes",
+      "participant_type": "player",
+      "linked_count": 2,  // over + under
+      "variables": [250.5]  // This player is linked with this variable
+    },
+    {
+      "partner_participant_id": "pp-allen",
+      "name": "Josh Allen",
+      "participant_type": "player",
+      "linked_count": 2,
+      "variables": [275.5]
+    }
+  ],
+  "raw_markets": [
+    {
+      "raw_market_id": "raw-be-passing-yards",
+      "external_id": "2000005|3",
+      "pretty_title": "Passing Yards",
+      ...
+    }
+  ]
+}
+```
+
+### UI Workflow: Adding a Participant
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ Passing Yards - Chiefs vs Bills                        │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Existing Participants:                                 │
+│   • Patrick Mahomes (250.5 yards) ✓                    │
+│   • Josh Allen (275.5 yards) ✓                         │
+│                                                         │
+│ [+ Add Participant]  ← Button to add new participant   │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+
+When "+ Add Participant" is clicked:
+
+┌─────────────────────────────────────────────────────────┐
+│ Add Participant to Passing Yards Market                │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│ Select Participant:                                    │
+│   [Joe Burrow ▼]                                       │
+│                                                         │
+│ Variable (Total): [265.5]                              │
+│                                                         │
+│ Raw Market:                                            │
+│   Partner: BettorEdge                                  │
+│   Market: Passing Yards (2000005|3)                   │
+│                                                         │
+│ Over Side:                                             │
+│   Market Side: [Over ▼]                                │
+│   Timeframe: [Full Game ▼]                             │
+│   Price Key: [yes ▼]                                   │
+│                                                         │
+│ Under Side:                                            │
+│   Market Side: [Under ▼]                               │
+│   Timeframe: [Full Game ▼]                             │
+│   Price Key: [no ▼]                                    │
+│                                                         │
+│ [Link Both Sides]  [Cancel]                            │
+└─────────────────────────────────────────────────────────┘
+```
+
+**What happens:**
+1. Client makes 2 API calls to `POST /markets/link`:
+   - First call: Joe Burrow, over, variable = 265.5
+   - Second call: Joe Burrow, under, variable = 265.5
+2. Backend creates `router_market_variable` if it doesn't exist
+3. Backend creates `partner_market` records
+
+**Result:** The same raw market now has 3 participants:
+```
+Patrick Mahomes:
+  - Over 250.5 yards
+  - Under 250.5 yards
+
+Josh Allen:
+  - Over 275.5 yards
+  - Under 275.5 yards
+
+Joe Burrow:
+  - Over 265.5 yards
+  - Under 265.5 yards
+```
+
+### Key Benefits
+
+✅ **Same raw market, multiple participants** - Efficient linking
+✅ **Each participant has their own variable** - Different lines for different players
+✅ **Track existing participants** - See who's already linked
+✅ **Easy to add more** - Just select participant and enter variable
+✅ **Automatic variable management** - Backend handles variable creation
+
+### UI Layout - Markets Tab
+
+**Step 1: Manage Supported Markets**
+
+Click "Manage Markets" button to show modal:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Manage Markets for Lakers vs Celtics            [Close X]  │
+│                                                              │
+│  Select which markets are supported for this contest:       │
+│                                                              │
+│  ☑ Moneyline                              [Currently Active]│
+│  ☐ Spread                                                    │
+│  ☐ Total Points                                              │
+│  ☐ Player Props - Points                                     │
+│  ☐ Player Props - Rebounds                                   │
+│  ☐ Player Props - Assists                                    │
+│                                                              │
+│  [Save Changes]  [Cancel]                                    │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Step 2: Link Raw Markets for Supported Markets**
+
+Main markets view after managing:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Lakers vs Celtics - Markets                [Manage Markets]│
+│                                                              │
+│  ✅ Moneyline                                                │
+│     BettorEdge: ✅ Linked (2 sides)                         │
+│     Kalshi:     ❌ Not Linked [Link Markets]                │
+│     BetOpenly:  ✅ Linked (2 sides)                         │
+│                                                              │
+│  ✅ Spread                                                   │
+│     BettorEdge: ❌ Not Linked [Link Markets]                │
+│     Kalshi:     ❌ Not Linked [Link Markets]                │
+│     BetOpenly:  ❌ Not Linked [Link Markets]                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**📖 For detailed market linking guide, see:** [MARKET_LINKING_WORKFLOW.md](./MARKET_LINKING_WORKFLOW.md)
+
+---
+
+## 📋 Job Manager
+
+The Job Manager allows admins to manage automated background jobs that handle data loading, autolinking, and other scheduled tasks.
+
+### **Job List View**
+
+**Endpoint:** `GET /jobs`
+
+View all configured jobs in the system:
+
+```json
+{
+  "message": "Jobs retrieved successfully",
+  "count": 5,
+  "jobs": [
+    {
+      "router_job_id": "job-001",
+      "job_key": "loadContests",
+      "name": "Load Contests",
+      "description": "Loads contests for all active leagues",
+      "frequency": 15,
+      "frequency_type": "minutes",
+      "last_success_datetime": "2025-11-03T10:30:00Z",
+      "create_datetime": "2025-11-01T00:00:00Z"
+    }
+  ]
+}
+```
+
+**UI Display:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Job Manager                                    [+ New Job] │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ Load Contests                              [Run Now]   │ │
+│  │ Runs every 15 minutes                      [Edit]      │ │
+│  │ Last success: 5 minutes ago                [Delete]    │ │
+│  │ Status: ✅ Success                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ Load Participants                          [Run Now]   │ │
+│  │ Runs every 1 hour                          [Edit]      │ │
+│  │ Last success: 30 minutes ago               [Delete]    │ │
+│  │ Status: ✅ Success                                     │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ Auto-Link Markets                          [Run Now]   │ │
+│  │ Runs every 5 minutes                       [Edit]      │ │
+│  │ Last success: Never                        [Delete]    │ │
+│  │ Status: ⏸️  Never run                                  │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### **Create New Job**
+
+**Endpoint:** `POST /jobs/create`
+
+```json
+{
+  "job_key": "loadMarkets",
+  "name": "Load Markets",
+  "description": "Loads market data for all active contests",
+  "frequency": 10,
+  "frequency_type": "minutes"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Job created successfully",
+  "job": {
+    "router_job_id": "job-new-123",
+    "job_key": "loadMarkets",
+    "name": "Load Markets",
+    ...
+  }
+}
+```
+
+### **Update Job**
+
+**Endpoint:** `PUT /jobs/update`
+
+```json
+{
+  "router_job_id": "job-001",
+  "frequency": 30,
+  "frequency_type": "minutes"
+}
+```
+
+### **Delete Job**
+
+**Endpoint:** `DELETE /jobs/:router_job_id`
+
+Removes a job from the system.
+
+### **Queue/Run Job**
+
+**Endpoint:** `POST /jobs/queue`
+
+Manually trigger a job to run immediately:
+
+```json
+{
+  "job_key": "loadContests"
+}
+```
+
+**Response:**
+```json
+{
+  "message": "Job loadContests queued and executed successfully",
+  "job_key": "loadContests",
+  "job_name": "Load Contests",
+  "status_count": 1,
+  "job_statuses": [
+    {
+      "job_status_id": "status-123",
+      "router_job_id": "job-001",
+      "status": "success",
+      "start_datetime": "2025-11-03T10:45:00Z",
+      "end_datetime": "2025-11-03T10:45:15Z"
+    }
+  ]
+}
+```
+
+**Important:**
+- The server automatically determines if the job is a parent or child job
+- Parent jobs will orchestrate child jobs based on priorities
+- Returns all job statuses created during execution
+
+---
+
+### **Job Status History**
+
+**Endpoint:** `GET /jobs/statuses/recent?limit=50&offset=0`
+
+View recent job executions with pagination:
+
+```json
+{
+  "message": "Recent job statuses retrieved successfully",
+  "count": 50,
+  "total_count": 250,
+  "has_more": true,
+  "statuses": [
+    {
+      "job_status_id": "status-123",
+      "router_job_id": "job-001",
+      "job_name": "Load Contests",
+      "job_key": "loadContests",
+      "status": "success",
+      "start_datetime": "2025-11-03T10:45:00Z",
+      "end_datetime": "2025-11-03T10:45:15Z",
+      "is_parent_job": true,
+      "child_job_count": 3,
+      "create_datetime": "2025-11-03T10:45:00Z"
+    },
+    {
+      "job_status_id": "status-122",
+      "router_job_id": "job-002",
+      "job_name": "Load Participants",
+      "job_key": "loadParticipants",
+      "status": "failed",
+      "start_datetime": "2025-11-03T10:30:00Z",
+      "end_datetime": "2025-11-03T10:30:05Z",
+      "is_parent_job": false,
+      "child_job_count": 0,
+      "create_datetime": "2025-11-03T10:30:00Z"
+    }
+  ]
+}
+```
+
+**UI Display:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Job Execution History                                       │
+│                                                              │
+│  Showing 50 of 250 executions                [Page 1 of 5] │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ ✅ Load Contests (Parent)              [View Children] │ │
+│  │    Started: 2025-11-03 10:45:00                        │ │
+│  │    Duration: 15 seconds                                │ │
+│  │    3 child jobs executed                               │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ ❌ Load Participants                                   │ │
+│  │    Started: 2025-11-03 10:30:00                        │ │
+│  │    Duration: 5 seconds                                 │ │
+│  │    Failed with error                                   │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ ⏳ Auto-Link Markets (Parent)          [View Children] │ │
+│  │    Started: 2025-11-03 10:25:00                        │ │
+│  │    Status: In Progress                                 │ │
+│  │    2 child jobs completed, 1 in progress               │ │
+│  └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│  [Previous]  1  2  3  4  5  [Next]                          │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Query Parameters:**
+- `limit` (optional): Number of statuses to return (default: 50)
+- `offset` (optional): Pagination offset (default: 0)
+
+**Status Icons:**
+- ✅ Success
+- ❌ Failed
+- ⏳ In Progress
+- 📅 Scheduled
+
+---
+
+### **View Child Job Statuses**
+
+**Endpoint:** `GET /jobs/statuses/:job_status_id/children`
+
+When a parent job is executed, you can view the status of all child jobs:
+
+```json
+{
+  "message": "Child job statuses retrieved successfully",
+  "parent_job_status_id": "status-123",
+  "count": 3,
+  "child_statuses": [
+    {
+      "job_status_id": "status-124",
+      "router_job_id": "job-child-001",
+      "job_name": "Load Raw Contests",
+      "job_key": "loadRawContests",
+      "status": "success",
+      "start_datetime": "2025-11-03T10:45:01Z",
+      "end_datetime": "2025-11-03T10:45:05Z",
+      "parent_job_id": "status-123"
+    },
+    {
+      "job_status_id": "status-125",
+      "router_job_id": "job-child-002",
+      "job_name": "Auto-Link Contests",
+      "job_key": "autoLinkContests",
+      "status": "success",
+      "start_datetime": "2025-11-03T10:45:06Z",
+      "end_datetime": "2025-11-03T10:45:10Z",
+      "parent_job_id": "status-123"
+    },
+    {
+      "job_status_id": "status-126",
+      "router_job_id": "job-child-003",
+      "job_name": "Load Markets",
+      "job_key": "loadMarkets",
+      "status": "success",
+      "start_datetime": "2025-11-03T10:45:11Z",
+      "end_datetime": "2025-11-03T10:45:15Z",
+      "parent_job_id": "status-123"
+    }
+  ]
+}
+```
+
+**UI Dropdown/Modal:**
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Load Contests - Child Jobs                      [Close X]  │
+│                                                              │
+│  Parent Job Started: 2025-11-03 10:45:00                    │
+│  Total Duration: 15 seconds                                 │
+│                                                              │
+│  ┌────────────────────────────────────────────────────────┐ │
+│  │ 1. Load Raw Contests                                   │ │
+│  │    ✅ Success                                          │ │
+│  │    Started: 10:45:01                                   │ │
+│  │    Duration: 4 seconds                                 │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ 2. Auto-Link Contests                                  │ │
+│  │    ✅ Success                                          │ │
+│  │    Started: 10:45:06                                   │ │
+│  │    Duration: 4 seconds                                 │ │
+│  ├────────────────────────────────────────────────────────┤ │
+│  │ 3. Load Markets                                        │ │
+│  │    ✅ Success                                          │ │
+│  │    Started: 10:45:11                                   │ │
+│  │    Duration: 4 seconds                                 │ │
+│  └────────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+### **Job Endpoints Summary**
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| GET | `/jobs` | Get all jobs |
+| GET | `/jobs/:job_key` | Get specific job by key |
+| POST | `/jobs/create` | Create new job |
+| PUT | `/jobs/update` | Update existing job |
+| DELETE | `/jobs/:router_job_id` | Delete job |
+| POST | `/jobs/queue` | Run job immediately |
+| GET | `/jobs/statuses/recent?limit=50&offset=0` | Get recent job execution history (paginated) |
+| GET | `/jobs/statuses/:job_status_id/children` | Get child job statuses for a parent job |
+
+---
+
+### **Job Types**
+
+**Parent Jobs:**
+- Orchestrate multiple child jobs based on priorities
+- Examples: `loadContests`, `loadParticipants`
+- Run child jobs sequentially in priority order
+
+**Child Jobs:**
+- Individual tasks that can be run standalone or as part of a parent
+- Examples: `loadRawContests`, `autoLinkContests`, `loadMarkets`
+- Accept optional `parent_job_id` parameter
+
+**How Parent/Child Works:**
+1. Admin queues `loadContests` job
+2. Server checks `parent_job_priorities` table
+3. Finds 3 child jobs: priority 1=`loadRawContests`, priority 2=`autoLinkContests`, priority 3=`loadMarkets`
+4. Runs each child job in order
+5. Creates status records for parent + all children
+
+---
+
+## 🚀 Implementation Priority
+
+1. **Phase 0:** League linking (foundation - must be done first!) ✅
+2. **Phase 1:** Contest linking (described above) ✅
+3. **Phase 2:** Participant linking (league-level, similar pattern) ✅
+4. **Phase 3:** Market supported setup (add/remove supported markets) ✅
+5. **Phase 4:** Market raw linking (link raw markets to supported markets) ✅
+6. **Phase 5:** Bulk operations, analytics, status checks
+
+**Important:** Leagues must be linked before contests, participants, or markets can be linked!
+
+---
+
+## 🗺️ Complete Navigation Flow Summary
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│                      LEAGUES (Entry Point)                    │
+│  • View all router leagues                                   │
+│  • Select a league to manage                                 │
+└────────────┬─────────────────────────────────────────────────┘
+             │
+             ├─── League Detail Page
+             │    • See partner link status (BettorEdge, Kalshi, BetOpenly)
+             │    • Load & link raw leagues for each partner
+             │    • [Manage League Links] [View Contests] [View Participants]
+             │
+             ├─── CONTESTS (League Context)
+             │    │
+             │    ├─── Contest List
+             │    │    • All contests in this league
+             │    │    • Search/filter by status, date
+             │    │    • Click contest to view details
+             │    │
+             │    └─── Contest Detail Page
+             │         • See partner link status
+             │         • Load & link raw contests for each partner
+             │         • Navigate to Markets tab
+             │         │
+             │         └─── MARKETS (Contest Context)
+             │              • Manage supported markets (which market types)
+             │              • For each market type, link raw markets from partners
+             │              • Add variables (spreads, totals) as needed
+             │
+             └─── PARTICIPANTS (League Context)
+                  │
+                  ├─── Participant List
+                  │    • All participants in this league
+                  │    • Search/filter by name, type
+                  │    • Quick view of partner link status
+                  │    • Click participant to view details
+                  │
+                  └─── Participant Detail Page
+                       • See partner link status
+                       • Load & link raw participants for each partner
+                       • Multiple raw participants can link to one router participant
+```
+
+### **Key Concepts:**
+
+1. **League-First Navigation**: Everything starts with selecting a league
+2. **Consistent Linking Pattern**: Load available → Select → Link (same for leagues, contests, participants, markets)
+3. **Partner Status Visibility**: Always show which partners are linked (✅/❌)
+4. **Already Linked Section**: Every modal shows both "Already Linked" and "Available to Link"
+5. **Context Scoping**:
+   - Contests belong to a league
+   - Participants belong to a league
+   - Markets belong to a contest
+6. **Search & Filter**: Enable at every level for better UX