Development Documentation

Welcome to the AltSportsLeagues.ai development documentation. This section provides comprehensive guides for developers working with the platform's architecture, tools, and workflows.

Quick Links

🤖 Claude Code Setup

Complete guide to Claude Code integration, MCP servers, slash commands, and custom agents

🔌 MCP Architecture

Model Context Protocol server architecture, implementation patterns, and best practices

🗄️ Data Layer

Unified data layer architecture covering Supabase, Neo4j, Firebase, and vector databases

Overview

The AltSportsLeagues.ai platform is built on a modern, scalable architecture that integrates:

Core Technologies

Backend: Python (FastAPI, FastMCP) on Google Cloud Run
Frontend: Next.js 15 with TypeScript, Tailwind CSS, shadcn/ui
Databases:
- Supabase (PostgreSQL) for relational data
- Neo4j for graph relationships
- Firebase for real-time updates
- FAISS/ChromaDB for vector search
Automation: n8n workflows with 525+ nodes
AI Integration: Claude Code with 15+ MCP servers
Project Management: Atlassian (Jira/Confluence)

Architecture Layers

┌─────────────────────────────────────────────────┐
│           Frontend (Next.js 15)                  │
│         altsportsleagues.ai (Vercel)            │
└────────────────────┬────────────────────────────┘
                     │ API Calls
┌────────────────────▼────────────────────────────┐
│      Backend API (Python FastAPI)               │
│    api.altsportsleagues.ai (Cloud Run)          │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │   MCP    │  │   Data   │  │ Business │     │
│  │ Servers  │  │  Layer   │  │  Logic   │     │
│  └──────────┘  └──────────┘  └──────────┘     │
└────────────────────┬────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────┐
│              Database Layer                      │
│                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐     │
│  │ Supabase │  │  Neo4j   │  │ Firebase │     │
│  │(Postgres)│  │ (Graph)  │  │(Real-time)│    │
│  └──────────┘  └──────────┘  └──────────┘     │
│                                                  │
│              ┌──────────────┐                   │
│              │ FAISS/       │                   │
│              │ ChromaDB     │                   │
│              │ (Vector)     │                   │
│              └──────────────┘                   │
└─────────────────────────────────────────────────┘

Development Workflows

1. Local Development Setup

Prerequisites:

Python 3.11+ with uv package manager
Node.js 20+
Docker Desktop
Claude Code (VS Code extension)

Setup Steps:

# Clone repository
cd /path/to/altsportsleagues.ai
 
# Install Python dependencies
uv pip install -r apps/backend/requirements.txt
 
# Install Node dependencies
cd apps/docs-site && npm install
cd ../frontend && npm install
 
# Set up environment variables
cp .env.sample .env.local
# Edit .env.local with your credentials
 
# Start local backend
uv run python apps/backend/server.py
 
# Start docs site
cd apps/docs-site && npm run dev
 
# Start frontend
cd clients/frontend && npm run dev

2. Claude Code Integration

Configure MCP Servers:

The .cursor/mcp.json file contains all MCP server configurations. Key servers:

n8n-mcp: Workflow automation (525+ nodes)
atlassian: Jira/Confluence integration
league-discovery: Custom league discovery MCP
Database MCPs: Supabase, Neo4j, Firebase connectors

Use Slash Commands:

# Prime for development
/prime-python          # Python backend
/prime-nextjs          # Next.js frontend
/prime-mcp             # MCP server development
 
# Test databases
/database:etl:database.etl.supabase.health-check
/database:etl:database.etl.neo4j.graph-database-connectivity
 
# Deploy
/deploy:google.cloud-deployment

Launch Agents:

# System architecture
@system-architect
 
# Backend development
@backend-typescript-architect
 
# Frontend development
@ui-engineer
 
# MCP development
@mcp-engineer

3. Data Pipeline Development

Complete Pipeline Example:

# 1. Extract league data from email
from data_layer.shared import LeagueProcessor
 
processor = LeagueProcessor()
league_data = await processor.extract_from_email(email_content)
 
# 2. Validate with Pydantic
from data_layer.schemas import LeagueSchema
validated = LeagueSchema(**league_data)
 
# 3. Store in Supabase
from data_layer.shared.python.supabase_client import SupabaseClient
supabase = SupabaseClient()
league_id = await supabase.upsert_league(validated.dict())
 
# 4. Create Neo4j graph
from data_layer.shared.neo4j_utils import Neo4jClient
neo4j = Neo4jClient()
await neo4j.create_league_graph(validated.dict())
 
# 5. Generate embeddings
from data_layer.shared.python.vector_client import VectorClient
vector = VectorClient()
embedding = await generate_embedding(validated.description)
await vector.add_embeddings([embedding], [league_id])
 
# 6. Trigger n8n workflow
await trigger_workflow("league-onboarding", {"league_id": league_id})

Development Guides

Claude Code Setup

Learn how to configure Claude Code with MCP servers, custom slash commands, and specialized agents. Includes:

Complete MCP server configuration
350+ slash command reference
50+ custom agent documentation
Development workflow examples

Read Claude Code Setup →

MCP Architecture

Comprehensive guide to Model Context Protocol server architecture, including:

MCP server implementation patterns
n8n workflow integration
Atlassian (Jira/Confluence) automation
Custom MCP server development
Testing and deployment

Read MCP Architecture →

Data Layer

Deep dive into the unified data layer that orchestrates all data sources:

Multi-database coordination (Supabase, Neo4j, Firebase)
Triple index system for efficient querying
Schema generation and validation
Cross-platform utilities (Python, TypeScript, Next.js)
Vector search with FAISS/ChromaDB

Read Data Layer Documentation →

Common Development Tasks

Task 1: Add New League

# 1. Prime Claude Code
/prime-altsportsdata
 
# 2. Process league questionnaire
/media:email:process-email-attachments
 
# 3. Generate contract
/altsportsdata:convert-league-questionnaire-to-contracts
 
# 4. Deploy to database
/database:etl:database.etl.supabase.altsports-league-onboarding

Task 2: Create MCP Server

# 1. Prime for MCP development
/prime-mcp
 
# 2. Scaffold server
@mcp-server-scaffolder
 
# 3. Test integration
# Use n8n-mcp to validate
 
# 4. Deploy
/deploy:google.cloud-deployment

Task 3: Build Frontend Feature

# 1. Prime for Next.js
/prime-nextjs
 
# 2. Generate UI components
@ui-generation-agent
 
# 3. Test with Playwright
# Use playwright MCP for automation
 
# 4. Deploy
/deploy:deploy-docs

Testing & Quality Assurance

Evaluation Commands

# Master evaluation loop (80% → 100% production)
/evals:cook-eval-loop
 
# Email system testing
/evals:email-testing-orchestration
 
# Contract download verification
/evals:test-contract-downloads

Database Testing

# Supabase health check
/database:etl:database.etl.supabase.health-check
 
# Neo4j connectivity
/database:etl:database.etl.neo4j.graph-database-connectivity
 
# Firebase connectivity
/database:etl:database.etl.firebase.firestore-connectivity-test

Deployment

Backend Deployment (Google Cloud Run)

# Build and deploy
/deploy:google.cloud-deployment
 
# Or manually
cd apps/backend
docker build -t gcr.io/project-id/backend .
gcloud run deploy api --image gcr.io/project-id/backend

Frontend Deployment (Vercel)

# Deploy docs site
/deploy:deploy-docs
 
# Or via Vercel CLI
cd apps/docs-site
vercel --prod
 
cd clients/frontend
vercel --prod

Additional Resources

Documentation

Tools & Services

External Documentation

Support & Community

For development support:

Internal Documentation: Review this development guide and CLAUDE.md
Claude Code Agents: Use specialized agents like @system-architect, @mcp-engineer
Slash Commands: Leverage 350+ commands for rapid development
MCP Tools: Use n8n-mcp, atlassian, and custom servers
Project CLAUDE.md: Comprehensive project overview at repository root

Getting Help

Common Issues:

MCP Server Not Available: Check .cursor/mcp.json configuration
Database Connection Failed: Verify environment variables in .env.local
Slash Command Not Found: Ensure command exists in .claude/commands/
Agent Not Loading: Check agent configuration in .claude/agents/

Debug Steps:

# Check MCP server status
cat .cursor/mcp.json | jq '.mcpServers'
 
# Verify environment variables
cat .env.local
 
# Test database connectivity
/database:etl:database.etl.supabase.database-connectivity-test
 
# Review logs
tail -f apps/backend/logs/app.log

Ready to start developing? Begin with Claude Code Setup to configure your development environment.

Data Layer Architecture MCP Server Architecture

Development Documentation

Quick Links

🤖 Claude Code Setup

🔌 MCP Architecture

🗄️ Data Layer

Overview

Core Technologies

Architecture Layers

Development Workflows

1. Local Development Setup

2. Claude Code Integration

3. Data Pipeline Development

Development Guides

Claude Code Setup

MCP Architecture

Data Layer

Common Development Tasks

Task 1: Add New League

Task 2: Create MCP Server

Task 3: Build Frontend Feature

Testing & Quality Assurance

Evaluation Commands

Database Testing

Deployment

Backend Deployment (Google Cloud Run)

Frontend Deployment (Vercel)

Additional Resources

Documentation

Tools & Services

External Documentation

Support & Community

Getting Help

Platform

Documentation

Community

Support