Service Map & Details

Detailed breakdown of each service, its purpose, technology stack, and deployment configuration.

📊 Service Overview

1. Backend API Service

Google Cloud Run

api.altsportsleagues.ai

Purpose: Core API serving all business logic, MCP servers, AI processing, and data operations.

Technology Stack:

Framework: FastAPI (async Python web framework)
Language: Python 3.11
Protocol: FastMCP (Model Context Protocol)
Server: Uvicorn with uvloop
Container: Docker (multi-stage build)

Deployment Details:

Platform: Google Cloud Run (us-central1)
Resources: 4Gi memory, 2 CPU
Scaling: 0-10 instances (auto-scale to zero)
Port: 8080 (production), 8090 (local Docker)
Build Time: 4-8 minutes
Local Testing: cd apps/backend && ./deploy-local-docker.sh

API Endpoints:

/                      API info and version
/health                Health check
/docs                  Swagger UI
/openapi.json          OpenAPI 3.0 schema
/v1/*                  Version 1 API endpoints
  ├─ /leagues
  ├─ /teams
  ├─ /players
  └─ /stats

Environment Requirements:

OPENAI_API_KEY - OpenAI API key
ANTHROPIC_API_KEY - Anthropic Claude API key
GOOGLE_CLOUD_PROJECT - GCP project ID
FIRESTORE_PROJECT_ID - Firestore project
SUPABASE_URL + SUPABASE_KEY - Database
NEO4J_URI + credentials - Graph database

Quick Commands:

# Local development
cd apps/backend
./deploy-local-docker.sh
 
# Production deployment
./deploy-all.sh  # Select option 2
 
# View logs
gcloud run services logs tail altsportsleagues-backend --region us-central1
 
# Test health
curl https://api.altsportsleagues.ai/health

2. Main Frontend Service

Vercel

altsportsleagues.ai

Purpose: Public-facing web application for league discovery, user dashboard, and graph visualization.

Technology Stack:

Framework: Next.js 16 (App Router)
Language: TypeScript
UI Library: React 18.2
Styling: Tailwind CSS + shadcn/ui
State: Zustand + React Query
Auth: Firebase Authentication
Animations: Framer Motion
Graphs: D3.js

Deployment Details:

Platform: Vercel Edge Network (global CDN)
Build Time: 2-5 minutes
Port: 3031 (local dev), 3017 (local prod)
API Integration: Rewrites /api/v1/* to backend

Features:

🏆 League search and discovery
📊 Interactive D3-powered graphs
🔐 Firebase Google Sign-In
📱 Mobile-first responsive design
🌙 Dark mode support
⚡ Real-time WebSocket updates
🧪 E2E testing with Playwright

API Integration Pattern:

// Frontend code uses relative URLs
const leagues = await fetch('/api/v1/leagues').then(r => r.json());
 
// Vercel rewrites to: api.altsportsleagues.ai/v1/leagues
// Browser sees same origin - no CORS!

Quick Commands:

# Local development
cd clients/frontend
npm run dev  # Port 3031
 
# Production deployment
vercel --prod
 
# E2E tests
npm run test:e2e

3. Documentation Service

Vercel (Separate Project)

docs.altsportsleagues.ai

Purpose: Comprehensive documentation hub with dynamic schema injection, interactive explorers, and auto-generated API references.

Technology Stack:

Framework: Next.js 16 + Nextra 4
Language: TypeScript
UI: React 18.3
Styling: Tailwind CSS
Content: MDX (Markdown + React)
Search: Built-in Nextra search

Deployment Details:

Platform: Vercel (separate project from main frontend)
Build Time: 3-5 minutes
Port: 3001 (local dev)
Schema Sync: Auto-syncs from ../../data_layer/

Features:

📚 150+ schema documentation
🔍 Interactive schema explorer
📖 Auto-generated API docs
🎨 Material Design UI
🌙 Dark mode
🔎 Full-text search

Content Structure:

/                      Documentation homepage
/getting-started       Onboarding guides
/architecture          Architecture docs
/api                   API documentation
/schemas               Schema explorer
/integrations          Integration guides
/guides                How-to guides
/business              Business intelligence
/prompts               AI prompt library

Schema Injection:

<!-- Dynamic content injection -->
{{schema:path/to/schema.py}}
{{example:example.json}}
{{contract:tier-1-partnership}}

Quick Commands:

# Local development
cd apps/docs-site
npm run dev  # Port 3001
 
# Production deployment
vercel --prod
 
# Build with schema sync
npm run build

4. Automation Service (n8n)

Self-Hosted

n8n.altsportsleagues.ai

Purpose: Automated workflow orchestration for email processing, league onboarding, and business intelligence.

Technology Stack:

Platform: n8n Workflow Automation
Runtime: Node.js
UI: n8n Web Interface
Access: Password protected

Deployment Details:

Platform: Self-hosted or n8n Cloud
Port: 5678 (local/self-hosted)
Webhooks: https://n8n.altsportsleagues.ai/webhook/*
Management: Via n8n UI or MCP tools

Workflow Architecture:

n8n_workflows/workflows/
├─ orchestrator/      Parent agent (routing)
├─ agents/            Specialized domain agents
└─ tools/             22+ atomic operations

Key Workflows:

Gmail email processing and triage
League questionnaire processing
PDF extraction from attachments
Calendar scheduling automation
Contact management (CRM)
Contract generation
Business intelligence reports

Integration Pattern:

Gmail → n8n webhook → Orchestrator
                   → Specialized agent
                   → api.altsportsleagues.ai/v1/*
                   → Database updates
                   → Response actions

Quick Commands:

# Upload workflows
cd n8n_workflows
python scripts/upload_workflows_to_n8n.py
 
# Access UI
open https://n8n.altsportsleagues.ai
 
# Test webhook
curl -X POST https://n8n.altsportsleagues.ai/webhook/test

5. Data Layer (Shared)

Shared Resource

data_layer/

Purpose: Unified data management layer providing centralized access to schemas, models, and utilities across all services.

Technology Stack:

Languages: Python + TypeScript
Models: Pydantic (Python) + Zod (TypeScript)
Formats: JSON Schema, TypeScript types, Python classes

Used By:

✅ Backend - Schema validation, data models
✅ Frontend - TypeScript types, client models
✅ Docs Site - Schema injection, examples
✅ n8n - Workflow schemas, validation

Key Components:

data_layer/
├─ schemas/          Schema definitions (150+)
├─ shared/           Cross-platform utilities
│  ├─ python/        Python utilities
│  ├─ typescript/    TypeScript utilities
│  └─ zustand/       State management patterns
├─ output_styles/    Output formats
├─ n8n_integration/  n8n-specific code
└─ triple_index/     Efficient querying

Features:

🔄 Cross-platform compatibility (Python ↔ TypeScript)
📦 Centralized schema registry
🎯 Type-safe data validation
🔍 Efficient data querying (triple index)
📚 150+ sports data schemas

🗺️ Service Interaction Map

📈 Scaling Strategy

Auto-Scaling Configuration

Service	Min Instances	Max Instances	Trigger
Backend (Cloud Run)	0	10	Request-based
Frontend (Vercel)	Edge	Edge	Global CDN
Docs (Vercel)	Edge	Edge	Global CDN
n8n	1	1	Always on

Backend Scaling Behavior:

Cold Start: < 2 seconds (optimized Docker)
Scale to Zero: After 5 minutes idle
Max Concurrency: 80 requests per instance
CPU Always Allocated: Yes (faster response)

Frontend Scaling:

Edge Network: Deployed to 100+ global locations
ISR: Incremental Static Regeneration enabled
API Routes: Serverless functions

🔗 Integration Patterns

Frontend → Backend

// In Next.js component
const response = await fetch('/api/v1/leagues');
// Vercel rewrites to: api.altsportsleagues.ai/v1/leagues

n8n → Backend

// In n8n HTTP Request node
{
  "url": "https://api.altsportsleagues.ai/v1/process-questionnaire",
  "method": "POST",
  "authentication": "headerAuth",
  "headers": {
    "Authorization": "Bearer {{$env.API_KEY}}"
  }
}

Backend → Databases

# In FastAPI route
from data_layer.shared.python import neo4j_utils, supabase_client
 
async def get_leagues():
    # Query graph database
    graph_data = await neo4j_utils.query(cypher_query)
    
    # Query relational database
    relational_data = await supabase_client.query()
    
    # Combine and return
    return combine_results(graph_data, relational_data)

📊 Resource Allocation

By Service

Service	CPU	Memory	Storage	Cost Model
Backend	2 vCPU	4Gi	Ephemeral	Pay per use
Frontend	Edge	Edge	Cache	Free tier + overage
Docs	Edge	Edge	Cache	Free tier + overage
n8n	Varies	Varies	Persistent	Fixed (self-host)

Estimated Monthly Costs

Cloud Run (Backend): ~$20-50/month (low traffic)
Vercel (Frontend + Docs): $0-20/month (free tier covers most)
Cloudflare: $0/month (free tier)
Databases: Variable (depends on usage)
n8n: $0 (self-hosted) or $20+ (cloud)

Total Estimated: $20-90/month for low to medium traffic

🎯 Domain Mapping Summary

DNS Configuration (Cloudflare)

All domains use Cloudflare as the DNS provider with proxy enabled (☁️ orange cloud).

Subdomain	CNAME Target	Platform	Service
`altsportsleagues.ai`	`cname.vercel-dns.com`	Vercel	Frontend
`api.altsportsleagues.ai`	`ghs.googlehosted.com`	Google Cloud	Backend
`docs.altsportsleagues.ai`	`cname.vercel-dns.com`	Vercel	Docs
`n8n.altsportsleagues.ai`	(varies)	Self-hosted	n8n

Why Use Platform-Native Mapping?

✅ Optimal Performance - Direct to platform
✅ Automatic SSL - Platform provisions certificates
✅ Platform Features - Full feature access
✅ Simpler Troubleshooting - Native tooling

💡 Pro Tip: Each service can be deployed and tested independently. Always test locally first using ./deploy-local-docker.sh for the backend and npm run dev for frontends.

Security Supabase Multi-Database Implementation Summary

Service Map & Details

📊 Service Overview

1. Backend API Service

api.altsportsleagues.ai

2. Main Frontend Service

altsportsleagues.ai

3. Documentation Service

docs.altsportsleagues.ai

4. Automation Service (n8n)

n8n.altsportsleagues.ai

5. Data Layer (Shared)

data_layer/

🗺️ Service Interaction Map

📈 Scaling Strategy

Auto-Scaling Configuration

🔗 Integration Patterns

Frontend → Backend

n8n → Backend

Backend → Databases

📊 Resource Allocation

By Service

Estimated Monthly Costs

🎯 Domain Mapping Summary

DNS Configuration (Cloudflare)

Why Use Platform-Native Mapping?

📖 Related Pages

Platform

Documentation

Community

Support