Source: data_layer/docs/QUICKSTART.md

League Database Quick Start Guide

🚀 Get Started in 5 Minutes

Step 1: Set Up Supabase (2 minutes)

Go to https://supabase.com (opens in a new tab) and create a free account
Create a new project

Go to SQL Editor and run:

# Copy and paste the SQL from:
database/schemas/supabase_migration_001_prospective_leagues.sql

Go to Settings → API to get your credentials:
- Project URL → SUPABASE_URL
- anon public key → SUPABASE_ANON_KEY
- service_role key → SUPABASE_SERVICE_KEY

Step 2: Configure Environment Variables (1 minute)

Add to your .env file:

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key-here
SUPABASE_SERVICE_KEY=your-service-key-here
 
# Frontend
NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
NEXT_PUBLIC_BACKEND_URL=http://localhost:8000
 
# Firebase (optional for now)
FIREBASE_SERVICE_ACCOUNT_PATH=/path/to/service-account.json

Step 3: Test the Backend (1 minute)

cd apps/backend
python -m services.unified_league_database

You should see:

✅ Supabase adapter initialized (MOCK MODE)
✅ Firebase adapter initialized (MOCK MODE)
✅ Initialized Unified League Database

=== Test 1: Scraped League ===
✅ Mock upserted league: International Basketball League (ID: 1)
...

Step 4: Test the Frontend (1 minute)

cd clients/frontend-001-nextjs-ui-grok-chat-polymarket-micro-betting-altsport-opportunities
npm install
npm run dev

Navigate to the league query interface and try:

"Show me all basketball leagues"
"Find high-potential soccer leagues"

🎯 Common Use Cases

Use Case 1: Add a Scraped League

from apps.backend.services.unified_league_database import upsert_scraped_league
 
result = await upsert_scraped_league({
    "name": "New Basketball League",
    "sport_name": "Basketball",
    "sport_tier": "TIER2",
    "source_url": "https://example.com/nbl",
    "opportunity_score": 75
})
 
print(result)
# {
#   "supabase": {"success": True, "id": "..."},
#   "firebase": {"status": "skipped"}
# }

What happens:

✅ Added to Supabase with source_type: 'web_scrape' and verification_status: 'unverified'
❌ NOT added to Firebase (only verified leagues go there)

Use Case 2: Add a Verified League (Both Databases)

from apps.backend.services.unified_league_database import upsert_verified_league
 
result = await upsert_verified_league(
    {
        "name": "Premier Volleyball League",
        "sport_name": "Volleyball",
        "contact_info": {"email": "info@pvl.com"}
    },
    user_context={"email": "partner@altsportsdata.com"}
)
 
print(result)
# {
#   "supabase": {"success": True, "id": "..."},
#   "firebase": {"success": True, "id": "premier_volleyball_league"}
# }

What happens:

✅ Added to Supabase with source_type: 'human_verified' and verification_status: 'human_verified'
✅ ALSO added to Firebase (human-verified leagues get promoted automatically)

Use Case 3: Query from Frontend

import { getLeagueDatabaseClient } from '@/lib/league-database-client'
 
const client = getLeagueDatabaseClient()
 
// Natural language query
const result = await client.query(
  "Show me high-potential basketball leagues we haven't contacted"
)
 
console.log(result.leagues)
// [
//   {
//     name: "International Basketball League",
//     sport_name: "Basketball",
//     source_type: "web_scrape",
//     verification_status: "unverified",
//     opportunity_score: 75
//   }
// ]

Use Case 4: Promote Scraped → Verified

from apps.backend.services.unified_league_database import UnifiedLeagueDatabase
 
db = UnifiedLeagueDatabase()
 
# After human contact confirms legitimacy
result = await db.promote_to_firebase(
    supabase_league_id="abc-123",
    user_context={"email": "sales@altsportsdata.com"}
)
 
print(result)
# {
#   "success": True,
#   "league_id": "abc-123",
#   "firebase_id": "international_basketball_league"
# }

What happens:

Updates Supabase: verification_status → 'human_verified', promoted_to_firebase → true
Adds to Firebase: Creates document in verified_leagues collection

🔍 Query Examples

Frontend (TypeScript)

const client = getLeagueDatabaseClient()
 
// 1. Get all basketball leagues
const basketball = await client.executeQuery({ sport: "Basketball" })
 
// 2. Get high-potential opportunities (score > 80)
const highPotential = await client.getHighPotentialOpportunities(80)
 
// 3. Get verified partnerships only
const verified = await client.getVerifiedPartnerships()
 
// 4. Get leagues needing contact (score > 70, unverified)
const needsContact = await client.getLeaguesNeedingContact(70)
 
// 5. Search by name
const search = await client.searchByName("Premier")
 
// 6. Get analytics
const analytics = await client.getAnalytics()
console.log(`Total: ${analytics.total_leagues}`)
console.log(`Verified: ${analytics.verified_count}`)
console.log(`Scraped: ${analytics.scraped_count}`)

Backend (Python)

from apps.backend.services.unified_league_database import (
    query_all_leagues,
    query_verified_leagues_only,
    query_scraped_leagues_only
)
 
# Get all leagues
all_leagues = await query_all_leagues()
 
# Get only verified
verified = await query_verified_leagues_only()
 
# Get only scraped
scraped = await query_scraped_leagues_only()
 
# Filter by sport
basketball = await query_all_leagues({"sport_name": "Basketball"})

📊 Understanding the Data Flow

┌─────────────────────────────────────────────────┐
│                WEB SCRAPING                      │
│            (Discovers Leagues)                   │
└─────────────────┬───────────────────────────────┘
                  │
                  ↓
         ┌────────────────────┐
         │ Supabase Database  │ ← ALL LEAGUES
         │  (prospective_     │   • Scraped (unverified)
         │   leagues)         │   • Verified (human contact)
         └────────┬───────────┘
                  │
        ┌─────────┴─────────┐
        │                   │
        ↓                   ↓
  UNVERIFIED          VERIFIED
  (Scraped)           (Human Contact)
        │                   │
        │                   ↓
        │          ┌────────────────────┐
        │          │ Firebase Database  │
        │          │  (verified_        │
        │          │   leagues)         │
        └──────────┤                    │
                   │ ONLY VERIFIED      │
                   │ PARTNERSHIPS       │
                   └────────────────────┘

🎨 Frontend Integration

Add the query interface to any page:

import { LeagueQueryInterface } from '@/components/league-query-interface'
 
export default function LeagueDashboard() {
  return (
    <div className="container mx-auto p-6">
      <h1 className="text-3xl font-bold mb-6">League Database</h1>
      <LeagueQueryInterface />
    </div>
  )
}

🔐 Access Control

Supabase (Public + Authenticated)

✅ Public read access (for discovery)
✅ Authenticated write (for data entry)
✅ Service role full access (for backend)

Firebase (Restricted)

❌ No public access
✅ Authenticated users only
✅ League owners can edit their own data
✅ Internal team has full access

📈 Monitoring

Check database health:

from apps.backend.services.unified_league_database import UnifiedLeagueDatabase
 
db = UnifiedLeagueDatabase()
analytics = await db.get_league_analytics()
 
print(f"Supabase: {analytics['supabase']['total_leagues']} leagues")
print(f"Firebase: {analytics['firebase']['total_leagues']} verified")
print(f"Promotion rate: {analytics['promotion_rate']:.1%}")

🐛 Troubleshooting

"Supabase client not initialized"

Check .env file has correct Supabase credentials
Verify project URL and keys from Supabase dashboard

"Firebase adapter in mock mode"

Normal during development
Add FIREBASE_SERVICE_ACCOUNT_PATH to use real Firebase

"Query returns no results"

Run the sample data INSERT from the migration SQL
Or add leagues manually using the backend service

Frontend can't connect

Check NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY
Verify Supabase project is running
Check CORS settings in Supabase dashboard

🎓 Next Steps

Build a web scraper to populate Supabase with leagues
Create an onboarding portal for league owners to register
Add email integration to auto-classify incoming league inquiries
Build analytics dashboard to track promotion rates
Add Neo4j integration for relationship mapping (optional)

📚 Further Reading

DATABASE_ARCHITECTURE.md - Complete architecture docs
IMPLEMENTATION_SUMMARY.md - Implementation details
Supabase docs: https://supabase.com/docs (opens in a new tab)
Firebase docs: https://firebase.google.com/docs (opens in a new tab)

Data Fabric Architecture Multi-Database Quick Start

League Database Quick Start Guide

🚀 Get Started in 5 Minutes

Step 1: Set Up Supabase (2 minutes)

Step 2: Configure Environment Variables (1 minute)

Step 3: Test the Backend (1 minute)

Step 4: Test the Frontend (1 minute)

🎯 Common Use Cases

Use Case 1: Add a Scraped League

Use Case 2: Add a Verified League (Both Databases)

Use Case 3: Query from Frontend

Use Case 4: Promote Scraped → Verified

🔍 Query Examples

Frontend (TypeScript)

Backend (Python)

📊 Understanding the Data Flow

🎨 Frontend Integration

🔐 Access Control

Supabase (Public + Authenticated)

Firebase (Restricted)

📈 Monitoring

🐛 Troubleshooting

"Supabase client not initialized"

"Firebase adapter in mock mode"

"Query returns no results"

Frontend can't connect

🎓 Next Steps

📚 Further Reading

Platform

Documentation

Community

Support