System Architecture Overview
A comprehensive visual guide to the AltSportsLeagues.ai platform architecture, from data ingestion to end-user delivery.
High-Level Architecture
Domain Architecture
The platform is organized around key domains that handle specific business functions:
Deployment Architecture
Production URL Map
URL Routing Strategy:
| URL | Service | Platform | Port |
|---|---|---|---|
altsportsleagues.ai | Main Frontend | Vercel | 443 |
api.altsportsleagues.ai | Backend API | Cloud Run | 8080 |
docs.altsportsleagues.ai | Documentation | Vercel | 443 |
n8n.altsportsleagues.ai | Automation | Cloud Run | 5678 |
Component Relationships
Backend Services Architecture
Frontend Component Architecture
Schema Relationships
The data layer uses a unified schema system connecting all components:
n8n Workflow Architecture
Quick Reference
Key Architecture Decisions:
- Monorepo Structure: All services in one repository for easier coordination
- API Gateway Pattern: Single entry point through
api.altsportsleagues.ai - Event-Driven: n8n workflows handle async processing
- Graph-First: Neo4j for relationship queries, Supabase for transactions
- Edge Deployment: Vercel for frontend, Cloud Run for backend
Technology Stack Summary
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | Next.js 16, React 18, Tailwind | User interfaces |
| Backend | FastAPI, Python 3.11 | REST API, business logic |
| MCP | FastMCP | AI tool integration |
| Automation | n8n | Workflow orchestration |
| Database | Supabase (PostgreSQL) | Relational data |
| Graph | Neo4j | Relationship queries |
| Realtime | Firebase | Live updates |
| Storage | Google Cloud Storage | Files, documents |
| Auth | Firebase Auth | User authentication |
| CDN | Cloudflare | Edge caching, security |
Port Reference
| Service | Local Port | Production Port |
|---|---|---|
| Frontend | 3031 | 443 |
| Backend | 8080 | 8080 |
| Docs Site | 3001 | 443 |
| n8n | 5678 | 5678 |
| Redis | 6379 | 6379 |
| PostgreSQL | 5432 | 5432 |
Next Steps:
- Backend Development Guide - Learn to work with the backend
- MCP Integration Guide - Build and extend MCP servers
- Deployment Guide - Deploy changes safely
- API Reference - Explore available endpoints