Internal Developer Guide

The comprehensive guide for AltSportsLeagues.ai team members. Everything you need to know about developing, testing, and deploying across our platform.

Quick Start

Get up and running in under 10 minutes:

# Clone the repository
git clone https://github.com/altsportsleagues/platform.git
cd platform
 
# Backend setup (Python)
cd apps/backend
uv sync  # Install dependencies with uv
cp .env.example .env  # Configure environment
uv run uvicorn server:app --reload --port 8080
 
# Frontend setup (in new terminal)
cd clients/frontend
npm install
npm run dev  # Runs on port 3031
 
# Docs site (in new terminal)
cd clients/frontend-docs-site
npm install
npm run dev  # Runs on port 3001

Architecture Overview

Development Workflows

Backend Development (FastAPI)

Directory Structure:

apps/backend/
├── server.py              # Main FastAPI app
├── routers/               # API route handlers
│   └── api/v1/            # Version 1 endpoints
├── services/              # Business logic
├── mcp_servers/           # MCP server implementations
│   └── servers/           # Individual MCP servers
├── flows/                 # Data processing pipelines
├── models/                # Pydantic models
├── integrations/          # External service adapters
└── tests/                 # Test suites

Adding a New Endpoint:

# routers/api/v1/my_feature.py
from fastapi import APIRouter, Depends
from pydantic import BaseModel
 
router = APIRouter(prefix="/v1/my-feature", tags=["my-feature"])
 
class MyRequest(BaseModel):
    name: str
    value: int
 
class MyResponse(BaseModel):
    id: str
    status: str
 
@router.post("/", response_model=MyResponse)
async def create_feature(request: MyRequest):
    # Implementation
    return MyResponse(id="123", status="created")

Register the router in server.py:

from routers.api.v1 import my_feature
app.include_router(my_feature.router)

Running Tests:

cd apps/backend
uv run pytest tests/ -v
uv run pytest tests/test_my_feature.py -v --tb=short

Deployment

Deployment Pipeline

Deployment Commands

# Test locally with Docker
cd apps/backend
./deploy-local-docker.sh
./test-local-deployment.sh
 
# Deploy to Cloud Run (production)
./deploy-all.sh
# Select option 2 for backend only
 
# Deploy frontend to Vercel
cd clients/frontend
vercel --prod
 
# Deploy docs to Vercel
cd clients/frontend-docs-site
vercel --prod

Environment Variables

⚠️

Security Note: Never commit .env files. Use environment variable injection in CI/CD.

Required Environment Variables:

Variable	Description	Where to Get
`OPENAI_API_KEY`	OpenAI API access	OpenAI Dashboard
`ANTHROPIC_API_KEY`	Claude API access	Anthropic Console
`SUPABASE_URL`	Supabase project URL	Supabase Dashboard
`SUPABASE_KEY`	Supabase service key	Supabase Dashboard
`NEO4J_URI`	Neo4j connection URI	Neo4j Aura
`FIREBASE_PROJECT_ID`	Firebase project	Firebase Console
`GOOGLE_CLOUD_PROJECT`	GCP project ID	GCP Console

Database Operations

Supabase (PostgreSQL)

-- Create a new table migration
-- migrations/001_add_my_table.sql
 
CREATE TABLE my_features (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    data JSONB,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    updated_at TIMESTAMPTZ DEFAULT NOW()
);
 
CREATE INDEX idx_my_features_name ON my_features(name);
 
-- Add RLS policies
ALTER TABLE my_features ENABLE ROW LEVEL SECURITY;
 
CREATE POLICY "Public read access"
    ON my_features FOR SELECT
    USING (true);

Neo4j (Graph Database)

// Create league-team relationships
CREATE (l:League {id: $league_id, name: $league_name})
CREATE (t:Team {id: $team_id, name: $team_name})
CREATE (l)-[:HAS_TEAM]->(t)
 
// Query related leagues
MATCH (l:League)-[:HAS_TEAM]->(t:Team)-[:PLAYS_IN]->(e:Event)
WHERE e.date > datetime()
RETURN l, t, e
ORDER BY e.date
LIMIT 10

Debugging & Troubleshooting

Common Issues

Backend Issues:

# Check if backend is running
curl http://localhost:8080/health
 
# View logs
cd apps/backend
uv run uvicorn server:app --reload --log-level debug
 
# Test specific endpoint
curl -X POST http://localhost:8080/v1/my-feature \
  -H "Content-Type: application/json" \
  -d '{"name": "test"}'

Common Fixes:

Port already in use: lsof -i :8080 and kill process
Import errors: uv sync to reinstall dependencies
Database connection: Check environment variables

Git Workflow

Branch Naming:

feature/ - New features
fix/ - Bug fixes
refactor/ - Code refactoring
docs/ - Documentation updates

Commit Messages:

feat: Add league onboarding workflow
fix: Resolve score calculation error
docs: Update API reference
refactor: Simplify contract generation

Resources

Internal Links

External Documentation

Need Help?

Slack: #dev-help
Email: dev@altsportsleagues.ai
Wiki: Internal Confluence

📘 Complete Platform Guide 📘 Developer Handbook