Frequently Asked Questions

A: Frontend keeps /api/ in the path for namespace clarity in code, while backend removes it to avoid redundancy since the api. subdomain already indicates it's an API.

Frontend: altsportsleagues.ai/api/v1/leagues - Clear it's an API call
Backend: api.altsportsleagues.ai/v1/leagues - Clean, matches industry standards

Vercel's rewrite connects them invisibly!

A: We use each platform's strengths:

• Vercel - Best for static/SSR frontends (global edge, zero config for Next.js)
• Cloud Run - Best for Python backends (containers, auto-scale to zero, long-running tasks)

Benefits:

• Better performance (edge for static, centralized for compute)
• Lower cost (right tool for each job)
• Platform-specific features (Vercel previews, Cloud Run scale-to-zero)
• Flexibility (can move services independently)

Trade-off: Slight complexity in managing two platforms, but deployment scripts handle it.

A: Cloud Run automatically scales down to 0 instances after 5 minutes of inactivity to save costs.

First request after idle:

• Cold start: ~1-2 seconds (our optimized Docker image)
• Container spins up automatically
• Request completes normally (slight delay)

Subsequent requests:

• No cold start (container is warm)
• Response time: ~300ms (normal)

Cost savings: You pay $0 when no one is using the API!

To disable scale-to-zero (if cold starts are an issue):

gcloud run services update altsportsleagues-backend \
  --min-instances 1 \
  --region us-central1

A: Cloudflare provides a unified security layer across all services:

• Single DNS management - One place to configure all subdomains
• Extra DDoS protection - 100+ Tbps network (much larger than platform defaults)
• WAF - Block malicious requests before they hit your infrastructure
• Analytics - Unified view of all traffic
• Cost: Free tier handles massive traffic

It's defense in depth - Multiple security layers protect better than one.

Deployment times:

• Backend (Cloud Run): 4-8 minutes (Docker build + deploy)
• Frontend (Vercel): 2-5 minutes (Next.js build)
• Docs (Vercel): 3-5 minutes (Nextra build + schema sync)
• Domain mapping: 5-30 minutes (DNS propagation + SSL)

Total first-time setup: ~45-60 minutes

After first deploy:

• Parallel deploy (backend + frontend): ~10 minutes
• Backend only: ~8 minutes
• Frontend only: ~5 minutes

A: Yes! Services are completely independent:

# Deploy only backend
./deploy-all.sh  # Option 2
 
# Deploy only frontend
./deploy-all.sh  # Option 3
 
# Deploy docs
cd apps/docs-site && vercel --prod

Frontend and docs auto-deploy on Git push (if Vercel Git integration is enabled)

Backend requires manual deployment (controlled releases)

A: Rollback is quick and easy:

Backend (Cloud Run):

# Instant traffic switch to previous revision
gcloud run services update-traffic altsportsleagues-backend \
  --to-revisions PREVIOUS_REVISION=100 \
  --region us-central1

Frontend/Docs (Vercel):

# One command rollback
vercel rollback
 
# Or via dashboard (click "Promote to Production" on old deploy)

Zero downtime - Traffic switches instantly to previous version.

A: Very affordable, especially early on:

Low traffic (< 10K requests/day):

• Cloud Run: $5-20/month
• Vercel: $0 (free tier)
• Cloudflare: $0 (free tier)
• Databases: $0-25/month
• Total: $5-45/month

Medium traffic (100K requests/day):

• Cloud Run: $20-50/month
• Vercel: $20/month (Pro)
• Cloudflare: $0
• Databases: $50-100/month
• Total: $90-170/month

High traffic (1M+ requests/day):

• Cloud Run: $100-200/month
• Vercel: $20/month
• Cloudflare: $0-20/month
• Databases: $100-300/month
• Total: $220-540/month

Key factor: Scales with usage (pay only for what you use)

A: Yes! Optimization strategies:

1. Use Cloud Run scale-to-zero (already enabled)
2. Aggressive caching (Cloudflare + Redis)
3. Optimize database queries (indexes, batching)
4. Image optimization (Next.js Image component)
5. Committed use discounts (Google Cloud, 37-55% off)
6. Vercel free tier (100GB bandwidth is generous)

At 10K requests/day, you'll likely stay under $50/month total.

A: FastAPI is ideal for AI/ML workloads:

• ✅ Python ecosystem - Best AI/ML libraries (OpenAI, Anthropic, transformers)
• ✅ Async native - Handles concurrent requests efficiently
• ✅ Auto documentation - OpenAPI/Swagger out of the box
• ✅ Type safety - Pydantic validation
• ✅ Performance - As fast as Node.js (async + uvloop)

Node.js would require:

• Python interop for AI libraries (slow)
• Manual API documentation
• Less robust type validation

Result: FastAPI gives us Python's AI ecosystem + Node.js-like performance.

A: Separation provides benefits:

• ✅ Independent deployment - Update docs without touching main app
• ✅ Different theme - Nextra optimized for documentation
• ✅ Performance - Static generation for all docs (fast!)
• ✅ SEO - docs. subdomain is recognized pattern
• ✅ Caching - Can cache docs aggressively (rarely changes)

Cost: $0 extra (Vercel free tier covers both projects)

Link between them: Main site redirects /documentation/* to docs site

A: Yes, each serves different purposes:

Neo4j (Graph Database):

• Complex relationship queries (teams → players → leagues)
• Path finding (player career across teams)
• Relationship-heavy data (perfect for sports)
• Example: "Find all players who played for 3+ teams in this league"

Supabase (PostgreSQL):

• Structured tabular data (schedules, stats)
• Fast indexed queries
• Transactions and ACID guarantees
• Example: "Get all games on 2025-11-15"

Together: Best of both worlds (graph relationships + relational efficiency)

Alternative: Could use just PostgreSQL, but graph queries would be complex and slow.

A: data_layer/ is our single source of truth for:

• Schema definitions (Python + TypeScript)
• Data models and validation
• Shared utilities
• Type definitions

Shared by all services:

• Backend imports Python schemas
• Frontend imports TypeScript types
• Docs injects schemas into pages
• n8n uses for validation

Benefit: Change schema once, all services stay in sync!

Example:

# In data_layer/schemas/league.py
class League(BaseModel):
    id: str
    name: str
    tier: int

// Auto-generated in TypeScript
interface League {
  id: string;
  name: string;
  tier: number;
}

Both stay synchronized automatically.

A: Check these indicators:

Immediate (right after deploy):

# Backend health
curl https://api.altsportsleagues.ai/health
# Should return: {"status":"healthy"}
 
# Frontend loads
curl https://altsportsleagues.ai
# Should return: HTTP 200

Cloud Run Console:

• Latest revision shows "Serving 100% traffic"
• No errors in recent logs
• Metrics show requests being handled

Vercel Dashboard:

• Deployment status: "Ready"
• No build errors
• Preview works correctly

If all green ✅, deployment succeeded!

A: Don't panic! Rollback is quick:

Backend:

# List revisions
gcloud run revisions list --service altsportsleagues-backend --region us-central1
 
# Rollback (instant traffic switch)
gcloud run services update-traffic altsportsleagues-backend \
  --to-revisions PREVIOUS_REVISION=100 \
  --region us-central1

Frontend:

vercel rollback

Recovery time: < 2 minutes

Then:

1. Fix the issue locally
2. Test thoroughly
3. Deploy again

A: Depends on your needs:

Recommended:

• Critical bugs: Immediately (after testing)
• New features: Weekly or bi-weekly
• Documentation: As needed (auto-deploys)
• Dependencies: Monthly security updates

Best practice:

• Deploy during low-traffic hours (if possible)
• Never deploy late Friday (weekend coverage)
• Batch small changes (less deploy overhead)
• Monitor for 30 minutes after deploy

Continuous deployment (auto-deploy every commit) is NOT recommended for backend - manual control prevents issues.

A: Scales to millions of users with proper optimization:

Current configuration supports:

• ~10K concurrent users
• ~1M API requests/day
• ~100K page views/day

With optimization (caching, CDN, query optimization):

• ~100K concurrent users
• ~10M+ API requests/day
• ~1M+ page views/day

Bottlenecks appear at:

• Database connections (easily fixed: connection pooling)
• Cloud Run max instances (easily fixed: increase limit)
• Cost (addressed with caching and committed use discounts)

Reference: Similar architectures power apps with 100M+ users (e.g., many startups on Vercel + Cloud platforms)

A: Add regions when:

1. > 20% users outside North America with latency complaints
2. Regulatory requirements (data residency laws)
3. Latency SLA requires < 100ms globally
4. High availability needs (multi-region failover)

Current setup:

• Frontend already global (Vercel edge network)
• Backend in us-central1 (good for US users)
• EU/Asia users see ~150-200ms latency (acceptable for most use cases)

Cost: Multi-region backend costs 2-3x more (run in multiple regions)

A: Automatic backups are enabled:

Neo4j:

• Configure automated snapshots
• Export to Cloud Storage weekly
• Point-in-time recovery available

Supabase:

• Daily automated backups (built-in)
• Point-in-time recovery (7-30 days depending on plan)
• Manual backup: Export via Supabase dashboard

Firebase:

• Daily automated backups
• 30-day retention
• Export via Firebase console

Recommended:

• Test restore procedures monthly
• Keep backups in separate region
• Document recovery process

A: Very secure with multiple layers of protection:

Layer 1 - Cloudflare:

• DDoS protection (automatic)
• WAF (blocks OWASP Top 10 attacks)
• SSL/TLS 1.2+ (forced)

Layer 2 - Platform:

• Vercel: Edge security, rate limiting
• Cloud Run: IAM, VPC, service accounts

Layer 3 - Application:

• Firebase Auth (industry standard)
• API key validation
• Input validation (Pydantic/Zod)
• CORS policies

Layer 4 - Data:

• Database encryption at rest
• TLS for all connections
• Row-level security (Supabase)

Compliance: Suitable for GDPR, SOC 2 (with proper configuration)

A: Immediate actions:

1. Rotate the key immediately:

   # In Google Secret Manager or Vercel
   # Generate new key
   # Update Secret Manager
   # Redeploy services

2. Check usage logs:

   # Find unauthorized requests
   gcloud logging read \
     'resource.type="cloud_run_revision" 
      AND textPayload=~"API_KEY_VALUE"'

3. Block old key:

   • Remove from Secret Manager
   • Add to blocklist if applicable

4. Monitor for 24 hours:

   • Watch for unusual activity
   • Verify new key works
   • Confirm old key is blocked

Prevention:

• Use Secret Manager (not .env in Git)
• Rotate keys every 90 days
• Monitor key usage patterns
• Use scoped keys (minimum permissions)

A: Simple process:

1. Create route in backend:

# apps/backend/routers/new_feature.py
from fastapi import APIRouter
 
router = APIRouter(prefix="/v1")
 
@router.get("/new-endpoint")
async def new_endpoint():
    return {"message": "New feature!"}

2. Include router:

# apps/backend/server.py
from routers import new_feature
 
app.include_router(new_feature.router)

3. Test locally:

./deploy-local-docker.sh
curl http://localhost:8090/v1/new-endpoint

4. Deploy:

./deploy-all.sh  # Option 2

5. Use in frontend:

// Automatically available via rewrite
const data = await fetch('/api/v1/new-endpoint').then(r => r.json());

No changes needed in frontend config! Rewrite handles it automatically.

A: Next.js App Router makes it easy:

1. Create page:

// clients/frontend/app/my-page/page.tsx
export default function MyPage() {
  return <div>My New Page</div>;
}

2. Test locally:

npm run dev
open http://localhost:3031/my-page

3. Deploy:

vercel --prod

That's it! Routing is automatic with App Router.

For API data:

export default async function MyPage() {
  // Fetch data (uses rewrite to backend)
  const data = await fetch('/api/v1/my-data').then(r => r.json());
  
  return <div>{JSON.stringify(data)}</div>;
}

A: Docs auto-sync from source:

For schema documentation:

1. Update schema in data_layer/schemas/
2. Deploy docs site: cd apps/docs-site && vercel --prod
3. Schema injection auto-updates content

For new doc pages:

1. Create MDX file: apps/docs-site/pages/my-doc.mdx
2. Add to _meta.ts for navigation
3. Deploy: vercel --prod

For API documentation:

• Updates automatically from FastAPI OpenAPI spec
• No manual updates needed
• Just deploy backend with new endpoints

Best practice: Update docs in same PR as code changes

A: Use the observability tools:

Step 1: Check logs

# Backend
gcloud run services logs tail altsportsleagues-backend \
  --region us-central1 \
  --limit 100
 
# Frontend
vercel logs

Step 2: Check metrics

• Cloud Run Console → Metrics tab
• Vercel Dashboard → Analytics
• Cloudflare Dashboard → Analytics

Step 3: Reproduce locally

# Start local environment
cd apps/backend && ./deploy-local-docker.sh
cd clients/frontend && npm run dev
 
# Try to reproduce the issue
# Debug with full access to logs and tools

Step 4: Test fix

• Fix locally first
• Verify fix works
• Deploy to production

Never debug directly in production!

A: Multiple sources:

Backend Errors:

# Cloud Run logs
gcloud run services logs read altsportsleagues-backend \
  --region us-central1 \
  --format "value(textPayload)" \
  | grep ERROR

Frontend Errors:

• Vercel Dashboard → Deployment → Runtime Logs
• Browser DevTools → Console tab
• Network tab for API failures

Database Errors:

• Supabase Dashboard → Logs
• Neo4j browser → Query logs
• Firebase Console → Error reporting

Best tool: Cloud Logging (aggregates all Google Cloud logs)