Back to DocumentationAPI Reference

Scaling Guide

Scaling Guide

Guide to scaling the SCORM API for high traffic and large deployments.

Table of Contents

Overview

Scaling strategies for:

  • High request volumes
  • Large package processing
  • Many concurrent sessions
  • Growing data storage

Horizontal Scaling

Stateless Architecture

The SCORM API is designed for horizontal scaling:

  • Stateless Requests: No server-side session storage
  • Database-Backed: All state in database
  • Shared Storage: Cloud storage (R2/Supabase)
  • Load Balancer Ready: Works behind load balancer

Scaling Strategy

1. Add More Instances:

Load Balancer
    ├── Instance 1
    ├── Instance 2
    ├── Instance 3
    └── Instance N

2. Auto-Scaling:

  • Scale based on CPU usage
  • Scale based on request rate
  • Scale based on queue depth

3. Regional Distribution:

  • Deploy in multiple regions
  • Route traffic to nearest region
  • Reduce latency

Vertical Scaling

Instance Sizes

Small (Development):

  • 1 CPU, 1GB RAM
  • Handles ~100 req/min
  • Suitable for testing

Medium (Production):

  • 2 CPU, 4GB RAM
  • Handles ~500 req/min
  • Suitable for small deployments

Large (High Traffic):

  • 4 CPU, 8GB RAM
  • Handles ~2000 req/min
  • Suitable for medium deployments

XLarge (Enterprise):

  • 8+ CPU, 16+ GB RAM
  • Handles ~5000+ req/min
  • Suitable for large deployments

When to Scale Vertically

  • Consistent high CPU usage (>70%)
  • Memory pressure
  • Single-threaded bottlenecks
  • Cost-effective for your traffic

Database Scaling

Read Replicas

Setup:

-- Primary database (writes)
PRIMARY_DB_URL=postgresql://primary...

-- Read replica (reads)
READ_REPLICA_URL=postgresql://replica...

Usage:

// Writes to primary
await supabaseAdmin.from('packages').insert(data);

// Reads from replica
await supabaseReplica.from('packages').select('*');

Connection Pooling

PgBouncer:

# Use connection pooler
DATABASE_URL=postgresql://pooler:5432/dbname

Benefits:

  • Reduces connection overhead
  • Better resource utilization
  • Handles connection spikes

Partitioning

Partition by Tenant:

-- Partition packages table by tenant
CREATE TABLE scorm_packages_tenant_1 PARTITION OF scorm_packages
  FOR VALUES IN ('550e8400-...');

CREATE TABLE scorm_packages_tenant_2 PARTITION OF scorm_packages
  FOR VALUES IN ('660e8400-...');

Storage Scaling

Cloudflare R2 (Recommended)

Benefits:

  • Unlimited scaling
  • Global CDN
  • Lower costs
  • Better performance

Setup:

CLOUDFLARE_R2_ACCOUNT_ID=your-account-id
CLOUDFLARE_R2_ACCESS_KEY_ID=your-access-key
CLOUDFLARE_R2_SECRET_ACCESS_KEY=your-secret-key
CLOUDFLARE_R2_BUCKET_NAME=allurelms
CLOUDFLARE_R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com

Supabase Storage

Scaling:

  • Automatic scaling
  • CDN integration
  • Global distribution

Limits:

  • Check plan limits
  • Monitor usage
  • Upgrade if needed

Load Balancing

Configuration

Round Robin:

Request 1 → Instance 1
Request 2 → Instance 2
Request 3 → Instance 3
Request 4 → Instance 1

Least Connections:

Request → Instance with fewest active connections

Health Checks:

// Health check endpoint
GET /api/health

// Response
{
  "status": "ok",
  "database": "connected",
  "storage": "accessible"
}

Session Affinity

Sticky Sessions:

  • Not required (stateless)
  • Can use for optimization
  • Optional for performance

Monitoring

Key Metrics

API Metrics:

  • Request rate (req/min)
  • Response time (p50, p95, p99)
  • Error rate
  • Success rate

System Metrics:

  • CPU usage
  • Memory usage
  • Network I/O
  • Disk I/O

Database Metrics:

  • Connection count
  • Query time
  • Replication lag
  • Storage usage

Alerting

Set Alerts For:

  • High error rate (>1%)
  • Slow responses (p95 > 2s)
  • High CPU (>80%)
  • Database connection issues
  • Storage quota warnings

Scaling Checklist

  • Horizontal scaling configured
  • Database read replicas setup
  • Connection pooling enabled
  • Storage backend optimized (R2)
  • Load balancer configured
  • Health checks implemented
  • Monitoring and alerting setup
  • Auto-scaling rules configured
  • Performance tested under load
  • Disaster recovery plan

Related Documentation

Last Updated: 2025-01-15