AltSportsLeagues.ai Glossary & Reference

Comprehensive reference guide for AltSportsLeagues.ai's intelligent sports business intelligence platform. This glossary provides detailed definitions, cross-references, and navigation for all system components, concepts, and terminology.

📖 Quick Navigation

🎯 Core Concepts

AltSportsLeagues.ai Platform

Definition: An AI-powered business intelligence platform specifically designed for sports league partnerships and alternative sports betting markets.

Key Components:

• League Partnership Pipeline: 4-stage intelligent pipeline for league acquisition
• AI Intelligence Service: Multi-model AI system for sports analysis
• Contract Generation Engine: Automated contract creation and management
• Multi-Database Architecture: Unified data layer across multiple storage systems

Business Value: Transforms traditional sports league management into data-driven, AI-enhanced operations.

Intelligence Service

Definition: Core AI processing engine combining multiple language models and specialized agents.

Components:

• Central Intelligence Agent: Primary reasoning and orchestration
• Specialized Agents: Domain-specific AI assistants (email, contracts, leagues)
• MCP Integration: Model Context Protocol for tool orchestration
• RAG System: Retrieval-Augmented Generation with ChromaDB vectors

Capabilities:

• Email classification and processing
• Contract analysis and generation
• League opportunity evaluation
• Sports market intelligence

🏗️ System Architecture

Backend Architecture (FastAPI + MCP)

Core Technologies:

• FastAPI: High-performance async web framework
• FastMCP: Model Context Protocol server implementation
• Pydantic v2: Data validation and serialization
• AsyncIO: Concurrent processing for AI operations

Key Endpoints:

/api/v1/intelligence/sports-intelligence  # AI sports analysis
/api/v1/leagues                           # League management
/api/v1/contracts/generate               # Contract creation
/api/v1/email/process                    # Email processing
/api/v1/betting/opportunities           # Betting markets

Frontend Architecture (Next.js + Vercel)

Technology Stack:

• Next.js 15: React framework with App Router
• TypeScript: Type-safe development
• Tailwind CSS: Utility-first styling
• Vercel: Edge network deployment

Application Categories:

• AI Chat Interfaces: Natural language sports intelligence
• Betting Platforms: Polymarket-style betting markets
• League Portals: Management dashboards for league owners
• Analytics Tools: Business intelligence and reporting

Data Layer Architecture

Multi-Database Design:

• Firestore: Real-time document storage
• Supabase: PostgreSQL-compatible relational data
• ChromaDB: Vector embeddings for AI search
• Google Sheets: Spreadsheet data for analysis
• Google Drive: Document storage and RAG

Schema System:

• Pydantic Models: Python data validation
• TypeScript Interfaces: Frontend type safety
• JSON Schemas: Cross-platform compatibility
• Zustand Stores: Client-side state management

Workflow Orchestration (n8n)

Workflow Types:

• Atomic Workflows: Single-purpose operations
• Composite Workflows: Multi-step business processes
• Integration Workflows: External system connections
• Monitoring Workflows: Health checks and alerts

Key Workflows:

• League Onboarding: Complete partnership acquisition
• Email Processing: AI-powered email intelligence
• Contract Generation: Automated agreement creation
• Jira Integration: Project management synchronization

🤖 AI & Intelligence Components

Agent Portfolio

Central Intelligence Agent:

• Purpose: Primary reasoning and decision-making
• Capabilities: Multi-modal analysis, strategic planning
• Integration: Coordinates all specialized agents

Specialized Agents:

MCP Server Ecosystem

MCP Servers:

• Business Intelligence MCP: Financial analysis and reporting
• Email Processing MCP: Gmail integration and automation
• Jira Integration MCP: Project management synchronization
• Data Layer MCP: Unified data access and queries
• Sports Intelligence MCP: AI-powered sports analysis

MCP Tools:

• Database Query Tools: Cross-system data retrieval
• AI Processing Tools: Model inference and analysis
• Workflow Tools: n8n integration and automation
• External API Tools: Third-party service integration

📊 Data Models & Schemas

Core Data Schemas

League Questionnaire Schema:

interface LeagueQuestionnaire {
  league_name: string;
  sport_category: string;
  founded_year: number;
  number_of_teams: number;
  total_annual_events: number;
  betting_market_interest: boolean;
  contact_email: string;
  website_url?: string;
  social_media?: SocialMedia[];
  league_structure: LeagueStructure;
}

Contract Terms Schema:

interface ContractTerms {
  league_id: string;
  tier: 'premium' | 'growth' | 'entry';
  duration_months: number;
  revenue_share_percentage: number;
  payment_terms: PaymentTerms;
  termination_clauses: TerminationClause[];
  exclusivity_requirements?: ExclusivityTerms;
}

Partnership Scoring Schema:

interface PartnershipScore {
  league_id: string;
  total_score: number; // 0-100
  tier_recommendation: 'premium' | 'growth' | 'entry';
  scoring_breakdown: {
    market_size: number;
    betting_interest: number;
    league_stability: number;
    data_quality: number;
    competitive_advantage: number;
  };
  confidence_level: number; // 0-1
}

Database Schemas

Firestore Collections:

• leagues: League profile and metadata
• contracts: Partnership agreements
• emails: Processed email communications
• opportunities: Partnership opportunities
• users: User accounts and permissions

Supabase Tables:

• league_questionnaires: Detailed league intake data
• contract_templates: Reusable contract components
• analytics_events: Usage and performance metrics
• workflow_executions: n8n workflow tracking

🔄 Workflow Definitions

League Partnership Pipeline

Stage 1: Initial Contact

• Email classification and routing
• Basic league information extraction
• Initial interest assessment

Stage 2: Qualification

• Detailed questionnaire processing
• Partnership scoring and tiering
• Risk assessment and due diligence

Stage 3: Proposal Development

• Contract generation and customization
• Terms negotiation and refinement
• Legal review and approval

Stage 4: Activation

• Contract execution and signing
• System integration and setup
• Ongoing partnership management

Email Intelligence Pipeline

Processing Steps:

1. Ingestion: Email receipt and parsing
2. Classification: AI-powered intent recognition
3. Extraction: Structured data extraction
4. Routing: Automated workflow triggering
5. Response: Intelligent reply generation

Email Types:

• Partnership Inquiries: New league interest
• Support Requests: Technical assistance
• Contract Negotiations: Terms discussions
• Data Requests: Information requests

🚀 Deployment & Infrastructure

Cloud Architecture

Google Cloud Run (Backend):

• Scaling: 0-100 instances based on load
• Memory: 4Gi per instance
• CPU: 2 vCPUs for AI workloads
• Concurrency: 80 requests per instance

Vercel (Frontend):

• Edge Network: Global CDN distribution
• SSR: Server-side rendering for SEO
• API Routes: Serverless function integration
• Preview Deployments: Branch-based testing

n8n (Workflows):

• Cloud Run: Containerized workflow execution
• Redis: Queue management and caching
• PostgreSQL: Workflow data persistence
• Webhook Integration: Real-time trigger processing

Environment Management

Development Environment:

• Local Development: Docker Compose for full stack
• Hot Reloading: Real-time code updates
• Debug Tools: Integrated debugging and logging
• Test Databases: Isolated testing environments

Production Environment:

• Multi-region: Active-active deployment
• Load Balancing: Global traffic distribution
• Auto-scaling: Demand-based resource allocation
• Monitoring: Comprehensive observability

🔒 Security & Compliance

Authentication Methods

JWT Bearer Tokens:

• Expiration: 15-minute access tokens
• Refresh Tokens: 7-day refresh capability
• Scopes: Granular permission control
• Rotation: Automatic token refresh

API Keys:

• Service Accounts: Machine-to-machine authentication
• Rate Limiting: Per-key usage controls
• Audit Logging: Complete access tracking
• Rotation: Automated key management

Data Protection

Encryption Standards:

• At Rest: AES-256 encryption for all data
• In Transit: TLS 1.3 for all communications
• Key Management: Cloud KMS for encryption keys
• Backup Encryption: Encrypted backup storage

Compliance Frameworks:

• GDPR: EU data protection compliance
• SOC 2: Security and availability controls
• ISO 27001: Information security management
• Industry Specific: Sports betting regulations

📈 Performance Metrics

System Performance Targets

API Response Times:

• Health Checks: < 100ms
• Standard Queries: < 500ms
• AI Operations: < 2000ms
• File Processing: < 30000ms

System Availability:

• Uptime SLA: 99.9% availability
• Error Rate: < 0.1% error rate
• Recovery Time: < 15 minutes RTO

Business Metrics

Processing Capacities:

• Emails Processed: 500/hour sustained
• Contracts Generated: 100/hour peak
• Leagues Onboarded: 50/month average
• API Requests: 1000/minute sustained

🔧 Development Tools

Code Quality

Linting & Formatting:

• Python: Ruff for fast, comprehensive linting
• TypeScript: ESLint with strict rules
• Pre-commit Hooks: Automated quality checks
• CI/CD: GitHub Actions for automated testing

Testing Framework

Test Categories:

• Unit Tests: Individual function testing
• Integration Tests: Component interaction validation
• End-to-End Tests: Complete workflow testing
• Performance Tests: Load and stress testing

AI-Powered Testing:

• Ghost AI Personas: Automated testing with AI agents
• Multi-Database Validation: Cross-system consistency checks
• Business Logic Testing: AI-powered requirement validation

📚 Documentation Standards

Content Organization

Navigation Structure:

• Overview Pages: High-level system descriptions
• Reference Pages: Detailed API and component docs
• Tutorial Pages: Step-by-step implementation guides
• Troubleshooting: Common issues and solutions

Documentation Types:

• Technical Documentation: API references, architecture guides
• Business Documentation: Process flows, business rules
• User Documentation: Interface guides, best practices
• Operational Documentation: Deployment, monitoring, maintenance

Search & Discovery

Vector Search Integration:

• ChromaDB Indexing: Semantic search across all documentation
• Multi-Source Content: Nextra pages, specifications, schemas
• Real-time Updates: Automatic index updates on content changes
• AI-Powered Results: Intelligent result ranking and filtering

📋 Cross-Reference Index

By Component Type

AI & Intelligence:

• Central Intelligence Agent → Architecture
• Email Intelligence Agent → Workflows
• Contract Generator Agent → Data Models
• League Vetting Agent → API Endpoints

Data & Storage:

• Firestore Integration → Data Layer
• Supabase Tables → Data Models
• ChromaDB Vectors → AI Components
• Google Sheets API → Integrations

Workflows & Automation:

• n8n Workflows → Integrations
• League Onboarding → Workflows
• Email Processing → Integrations
• Contract Generation → API Endpoints

Frontend Applications:

• Next.js Apps → Applications
• Streamlit Apps → Applications
• API Clients → Applications
• Mobile Apps → Applications

By Business Process

League Partnership Management:

• Initial Contact → Email Intelligence Pipeline
• Qualification → League Scoring System
• Proposal → Contract Generation Engine
• Activation → System Integration Workflows

Data Processing Pipeline:

• Ingestion → Multi-format Document Processing
• Classification → AI-Powered Categorization
• Extraction → Structured Data Parsing
• Storage → Multi-Database Distribution

Business Intelligence:

• Market Analysis → Sports Intelligence Service
• Performance Tracking → Analytics Dashboard
• Risk Assessment → Automated Scoring Systems
• Reporting → Custom Analytics Workflows

By Technical Domain

Backend Development:

• FastAPI Routes → API Reference
• MCP Integration → Integrations
• Database Operations → Data Layer
• Agent Orchestration → Architecture

Frontend Development:

• Next.js Components → Applications
• API Integration → API Reference
• State Management → Data Models
• UI/UX Patterns → Testing

DevOps & Infrastructure:

• Cloud Run Deployment → Deployment
• CI/CD Pipelines → Testing
• Monitoring & Logging → Security
• Security Controls → Security

🔍 Search & Discovery

Intelligent Search Features

Semantic Search:

• Natural Language Queries: Ask questions in plain English
• Context-Aware Results: Understands user intent and role
• Multi-Source Aggregation: Combines results from all documentation sources
• Real-time Relevance: Updates search index with content changes

Search Capabilities:

• Code Examples: Find implementation patterns
• API Endpoints: Locate specific API functionality
• Configuration Options: Discover system settings
• Troubleshooting: Find solutions to common issues

Content Sources

Indexed Documentation:

• Nextra Pages: Main documentation content
• Specifications: Technical and business specifications
• API Schemas: Data model definitions
• Code Comments: Implementation documentation
• Configuration Files: System setup and deployment docs

🎯 Quick Reference Guides

Getting Started

1. Platform Overview: Home → Understanding the platform
2. API Integration: API Reference → Technical integration
3. Deployment: Deployment Guide → Getting systems running
4. Development: Testing Framework → Development workflow

Common Tasks

For Developers:

• API Authentication → How to authenticate API calls
• Schema Definitions → Understanding data structures
• Testing Guide → Writing and running tests
• Deployment Guide → Deploying changes

For Business Users:

• League Onboarding → Partnership process
• Contract Generation → Agreement creation
• Analytics Dashboard → Business intelligence
• Integration Options → System connections

For Administrators:

• Security Policies → Access and permissions
• Monitoring Setup → System observability
• Backup & Recovery → Disaster recovery
• Compliance Reporting → Regulatory compliance

This comprehensive glossary and reference serves as the central knowledge hub for AltSportsLeagues.ai, providing structured access to all platform components, processes, and documentation.