Complete Platform Guide

Full-Context Overview: Everything you need to know about the AltSportsLeagues.ai platform in one place.

Platform Overview

AltSportsLeagues.ai is a comprehensive sports league data platform combining business intelligence, MCP (Model Context Protocol) integration, and modern web technologies to deliver a complete ecosystem for sports data management and analysis.

Core Architecture

┌─────────────────────────────────────────────────────────────┐
│                 Production Infrastructure                    │
├─────────────────────────────────────────────────────────────┤
│                                                               │
│  1. altsportsleagues.ai (Frontend - Vercel)                 │
│     ├─ Next.js 16 application                               │
│     ├─ User dashboard & league search                       │
│     ├─ Graph visualization                                  │
│     └─ /api/v1/* → api.altsportsleagues.ai/v1/*           │
│                                                               │
│  2. api.altsportsleagues.ai (Backend - Cloud Run)           │
│     ├─ FastAPI + Python 3.11                               │
│     ├─ MCP server implementations                           │
│     ├─ AI agents & processing                               │
│     └─ Clean URL pattern: /v1/* (no redundant /api/)       │
│                                                               │
│  3. docs.altsportsleagues.ai (Docs - Vercel)                │
│     ├─ Nextra 4 + Next.js 16                               │
│     ├─ Interactive schema explorer                          │
│     └─ Real-time schema injection                           │
│                                                               │
│  4. n8n.altsportsleagues.ai (Automation - Self-Hosted)      │
│     ├─ n8n workflow automation                              │
│     └─ League onboarding workflows                          │
│                                                               │
└─────────────────────────────────────────────────────────────┘

Key Components

1. Backend Services (apps/backend/)

• Platform: Google Cloud Run (containerized with Docker)
• URL: https://api.altsportsleagues.ai
• URL Pattern: /v1/* (clean, industry-standard)
• Technology: FastAPI + Python 3.11, FastMCP, Uvicorn
• Features:
  • RESTful API endpoints
  • MCP server implementations
  • AI-powered analysis
  • Real-time processing

2. Frontend Application (clients/frontend/)

• Platform: Vercel (edge network)
• URL: https://altsportsleagues.ai
• Technology: Next.js 16, React 18.2, TypeScript
• Features:
  • League discovery and search
  • Graph visualization (D3.js)
  • Firebase authentication
  • Responsive design
  • Dark mode support

3. Documentation Site (clients/docs-site/)

• Platform: Vercel (separate deployment)
• URL: https://docs.altsportsleagues.ai
• Technology: Next.js 16 + Nextra 4
• Features:
  • 150+ schema documentation
  • Interactive schema explorer
  • Auto-generated API docs
  • Real-time schema injection
  • Full-text search

4. Data Layer (data_layer/)

• Purpose: Unified data management
• Components:
  • Schema definitions
  • Data generators
  • Utilities (Python, TypeScript, Neo4j)
  • Triple index system
  • Prompt retrieval system

5. n8n Automation (n8n_workflows/)

• Platform: Self-hosted n8n
• URL: https://n8n.altsportsleagues.ai
• Features:
  • Gmail email processing
  • League onboarding workflows
  • Calendar integration
  • Contact management
  • Automated content creation

Data Flow & Processing

League Onboarding Pipeline

New League Discovery
        ↓
Gmail Processing (n8n)
        ↓
Document Extraction (Python + AI)
        ↓
Data Validation & Normalization
        ↓
Storage (Neo4j + Supabase + Firebase)
        ↓
Graph Indexing
        ↓
Available for Query & Analysis

Database Architecture

• Neo4j: Graph relationships (leagues, teams, players)
• Supabase: Relational data (PostgreSQL)
• Firebase: Authentication & real-time updates
• ChromaDB: Local embeddings (documentation search)

URL Strategy & Routing

Clean Backend URLs (Industry Standard)

✅ Correct Pattern:

api.altsportsleagues.ai/v1/leagues
api.altsportsleagues.ai/v1/teams
api.altsportsleagues.ai/v1/players

❌ Avoid Redundancy:

# Don't do this:
api.altsportsleagues.ai/api/v1/leagues  ← Redundant "api"

Frontend Proxy Pattern

// Frontend makes same-origin calls
const response = await fetch('/api/v1/leagues');
 
// Vercel rewrites to backend
// altsportsleagues.ai/api/v1/leagues
//   ↓
// api.altsportsleagues.ai/v1/leagues

Benefits:

• ✅ No CORS issues (same origin)
• ✅ Clean, non-redundant URLs
• ✅ SEO optimized
• ✅ Industry standard pattern

Deployment Architecture

Production Deployment Flow

1. Backend to Cloud Run

   cd apps/backend
   ./deploy-to-cloud-run.sh
   # 4-8 minutes deployment time

2. Frontend to Vercel

   cd clients/frontend
   vercel --prod
   # 2-5 minutes deployment time

3. Docs to Vercel

   cd clients/docs-site
   vercel --prod
   # 3-5 minutes deployment time

Local Development

# Backend (Docker sandbox)
cd apps/backend
./deploy-local-docker.sh  # Port 8090
 
# Frontend
cd clients/frontend
npm run dev  # Port 3031
 
# Docs
cd clients/docs-site
npm run dev  # Port 3001

MCP Integration

Available MCP Servers

1. n8n-mcp (Production)

   • Endpoint: https://altsportsdata.app.n8n.cloud
   • 525+ nodes, 263 AI-ready tools
   • Workflow management

2. league-discovery-cross-comparison

   • League discovery and analysis
   • Cross-league comparison
   • Supabase integration

3. atlassian (Jira & Confluence)

   • Project management
   • Issue tracking
   • Documentation integration

4. Google Workspace

   • Gmail, Calendar, Drive, Sheets
   • Automated workflows

MCP Usage Patterns

# Example: Using MCP for league analysis
from fastmcp import FastMCP
 
mcp = FastMCP("league-analysis")
 
@mcp.tool()
def analyze_league(league_id: str) -> dict:
    """Analyze league data and return insights"""
    # Implementation
    pass

Business Intelligence

4-Stage Partnership Pipeline

1. Document Intelligence

   • AI-powered document processing
   • OCR and structured extraction
   • Quality scoring

2. Partnership Scoring

   • Automated evaluation
   • AI analysis
   • Risk assessment

3. League Analysis

   • Market intelligence
   • Opportunity identification
   • Competitive analysis

4. Email Intelligence

   • Gmail integration
   • AI-powered classification
   • Automated routing

API Endpoint Structure

api.altsportsleagues.ai/
├─ /                    # API info & version
├─ /health              # Health check
├─ /docs                # Swagger UI
├─ /openapi.json        # OpenAPI 3.0 spec
└─ /v1/*                # Version 1 API
    ├─ /leagues         # League operations
    ├─ /teams           # Team operations
    ├─ /players         # Player operations
    ├─ /stats           # Statistics
    ├─ /markets         # Market data
    ├─ /predictions     # AI predictions
    └─ /rag             # RAG queries

Development Workflow

Frontend Development

1. Component Development

   cd clients/frontend
   npm run dev
   # Components in: app/components/

2. State Management

   • Zustand stores in store/
   • React Query for data fetching

3. Styling

   • Tailwind CSS
   • shadcn/ui components

Backend Development

1. API Development

   cd apps/backend
   uv run uvicorn server:app --reload

2. MCP Server Development

   # Location: apps/backend/mcp_servers/servers/
   from fastmcp import FastMCP
    
   mcp = FastMCP("my-server")
   # Add tools and resources

3. Testing

   pytest tests/

Testing Strategy

E2E Testing (Frontend)

cd clients/frontend
npm run test:e2e  # Playwright tests

Backend Testing

cd apps/backend
pytest tests/

Integration Testing

• n8n workflow testing
• MCP tool validation
• Database connectivity tests

Monitoring & Observability

Cloud Run Logs

gcloud run services logs tail altsportsleagues-backend \
  --region us-central1

Vercel Logs

vercel logs

Health Checks

• Backend: https://api.altsportsleagues.ai/health
• Frontend: https://altsportsleagues.ai/
• Docs: https://docs.altsportsleagues.ai/

Security

Authentication

• Firebase Authentication
• Google Sign-In
• JWT tokens

Authorization

• Role-based access control (RBAC)
• API key management
• Rate limiting

Data Protection

• HTTPS everywhere
• Environment variable encryption
• Secure credential storage

Performance Optimization

Frontend

• Next.js App Router for optimal routing
• Image optimization
• Code splitting
• Edge caching (Vercel)

Backend

• Async Python (uvloop)
• Connection pooling
• Query optimization
• Caching strategy

Database

• Neo4j query optimization
• Supabase connection pooling
• Firebase real-time optimizations

Troubleshooting

Common Issues

1. CORS Errors

   • Use frontend proxy pattern
   • Check vercel.json rewrites

2. Deployment Failures

   • Check Cloud Run logs
   • Verify environment variables
   • Test Docker build locally

3. API Connection Issues

   • Verify backend URL
   • Check authentication
   • Test health endpoints

Debug Tools

# Backend health
curl https://api.altsportsleagues.ai/health
 
# Test local Docker
cd apps/backend
./test-local-deployment.sh
 
# Check Vercel deployment
vercel inspect [deployment-url]

Next Steps

1. Getting Started Guide - Quick start for new developers
2. API Reference - Complete API documentation
3. Frontend Guide - Frontend development
4. Integration Playbook - Integration patterns
5. Developer Handbook - Development best practices

Resources

• Repository: GitHub (contact for access)
• Documentation: https://docs.altsportsleagues.ai (opens in a new tab)
• API Docs: https://api.altsportsleagues.ai/docs (opens in a new tab)
• Support: Contact team for assistance

Last Updated: November 2024 Version: 2.1.0