Architecture Best Practices

# ✅ DO: Be specific with allowed origins
allow_origins = [
    "https://altsportsleagues.ai",
    "https://docs.altsportsleagues.ai",
]
 
# ❌ DON'T: Allow all origins in production
allow_origins = ["*"]  # Security risk!

# ✅ GOOD: Parallel queries
async def get_league_data(league_id: str):
    # Run simultaneously
    graph_data, relational_data = await asyncio.gather(
        neo4j.query(league_id),
        supabase.query(league_id)
    )
    return combine(graph_data, relational_data)
 
# ❌ BAD: Sequential queries
async def get_league_data_slow(league_id: str):
    graph_data = await neo4j.query(league_id)  # Wait
    relational_data = await supabase.query(league_id)  # Then wait again
    return combine(graph_data, relational_data)

# ✅ GOOD: All or nothing
async with transaction_manager() as tx:
    await neo4j.create_league(league_data, tx=tx)
    await supabase.create_league(league_data, tx=tx)
    await firebase.notify_update(league_data)
    # Commits all if successful, rolls back if any fail
 
# ❌ BAD: Inconsistent state possible
await neo4j.create_league(league_data)
await supabase.create_league(league_data)  # If this fails, Neo4j has orphaned data

# Use event bus pattern
from fastapi import BackgroundTasks
 
@app.post("/v1/leagues")
async def create_league(
    league: LeagueCreate,
    background_tasks: BackgroundTasks
):
    # Primary write
    league_id = await supabase.create_league(league)
    
    # Background sync (eventual consistency)
    background_tasks.add_task(sync_to_neo4j, league_id)
    background_tasks.add_task(notify_firebase, league_id)
    
    return {"id": league_id}

# Deploy new revision (doesn't affect traffic)
gcloud run deploy altsportsleagues-backend \
  --image gcr.io/project/image:v1.1.0 \
  --no-traffic \
  --region us-central1
 
# Test new revision
curl https://REVISION-URL.run.app/health
 
# If good, switch traffic
gcloud run services update-traffic altsportsleagues-backend \
  --to-latest \
  --region us-central1
 
# If bad, rollback instantly (traffic still on old revision)

# ✅ GOOD: Clear, RESTful, versioned
@router.get("/v1/leagues", response_model=LeagueListResponse)
async def list_leagues(
    page: int = Query(1, ge=1),
    per_page: int = Query(20, ge=1, le=100),
    sport: Optional[str] = Query(None)
):
    """
    List all leagues with pagination.
    
    - **page**: Page number (starts at 1)
    - **per_page**: Items per page (max 100)
    - **sport**: Filter by sport (optional)
    """
    total = await db.count_leagues(sport=sport)
    leagues = await db.get_leagues(
        skip=(page - 1) * per_page,
        limit=per_page,
        sport=sport
    )
    
    return LeagueListResponse(
        leagues=leagues,
        total=total,
        page=page,
        per_page=per_page,
        pages=math.ceil(total / per_page)
    )

# Backend unit tests
cd apps/backend
pytest tests/ -v --cov=.
 
# Frontend E2E tests
cd clients/frontend
npm run test:e2e
 
# Integration test
./test-local-deployment.sh

// Docs use live schema injection
// In MDX file:
{{schema:schemas/league/tier_classification.py}}
 
// Always shows current schema
// Never gets out of sync
// One source of truth: data_layer/

name: Backend CI/CD
 
on:
  push:
    branches: [main]
    paths:
      - 'apps/backend/**'
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install dependencies
        run: pip install -r apps/backend/requirements.txt
      - name: Run tests
        run: pytest apps/backend/tests/
      
  deploy:
    needs: test
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Deploy to Cloud Run
        run: ./deploy-all.sh
        env:
          GCLOUD_SERVICE_KEY: ${{ secrets.GCLOUD_SERVICE_KEY }}

# ✅ GOOD: Validate on startup
from pydantic import BaseSettings, Field
 
class Settings(BaseSettings):
    openai_api_key: str = Field(..., env='OPENAI_API_KEY')
    database_url: str = Field(..., env='DATABASE_URL')
    environment: str = Field('development', env='ENV')
    
    class Config:
        env_file = '.env'
 
# Fails fast if required vars missing
settings = Settings()

# ✅ GOOD: Descriptive errors
@app.exception_handler(LeagueNotFoundError)
async def league_not_found_handler(request, exc):
    return JSONResponse(
        status_code=404,
        content={
            "error": "league_not_found",
            "message": f"League '{exc.league_id}' does not exist",
            "suggestion": "Check the league ID or search for leagues",
            "docs": "https://docs.altsportsleagues.ai/api/reference#leagues"
        }
    )
 
# ❌ BAD: Generic error
@app.exception_handler(Exception)
async def catch_all(request, exc):
    return JSONResponse(
        status_code=500,
        content={"error": "Something went wrong"}  # Not helpful!
    )