Scalability Patterns

┌─────────────────────────────────────┐
│ Vertical Scaling: CPU/Memory        │ (Limited)
├─────────────────────────────────────┤
│ Horizontal Scaling: More pods       │ (Better)
├─────────────────────────────────────┤
│ Multi-region: Geographic            │ (Complex)
├─────────────────────────────────────┤
│ Sharding: Data partitioning         │ (Advanced)
└─────────────────────────────────────┘

# cascade.yaml
tenants:
  - id: acme
    database:
      url: postgres://user:pass@postgres-acme:5432/acme_db
  
  - id: globex
    database:
      url: postgres://user:pass@postgres-globex:5432/globex_db

-- Single database, schema per tenant
CREATE SCHEMA acme;
CREATE SCHEMA globex;
 
CREATE TABLE acme.orders (...);
CREATE TABLE globex.orders (...);

# Workflow spans multiple regions
states:
  - name: ValidateRegional
    type: Parallel
    branches:
      - name: ValidateUS
        type: Task
        resource: urn:cascade:activity:validate@us-east
        timeout: 10s
      
      - name: ValidateEU
        type: Task
        resource: urn:cascade:activity:validate@eu-west
        timeout: 10s
    
    completion_strategy: ALL
    next: CombineResults

// Shard workflows by customer ID
func ShardWorkflow(customerID string) string {
    hash := fnv.New32a()
    hash.Write([]byte(customerID))
    shardID := hash.Sum32() % 10  // 10 shards
    return fmt.Sprintf("shard-%d", shardID)
}
 
// In CDL
// - name: ProcessOrder
//   type: Task
//   parameters:
//     shard: "{{ workflow.input.customer_id | shard }}"

# cascade.yaml
deployments:
  # API Gateway
  api:
    replicas: 3
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
  
  # Activity Workers
  workers:
    replicas: 10
    resources:
      requests:
        cpu: 1000m
        memory: 1Gi
  
  # Workflow Engine
  engine:
    replicas: 5
    resources:
      requests:
        cpu: 500m
        memory: 512Mi

autoscaling:
  enabled: true
  
  api:
    min_replicas: 3
    max_replicas: 20
    cpu_threshold: 70%
    memory_threshold: 80%
  
  workers:
    min_replicas: 10
    max_replicas: 50
    activity_queue_depth: 100
    target_queue_depth: 50

# Kafka/NATS scaling
messaging:
  broker: kafka
  partitions: 50           # Match shard count
  replication: 3           # High availability
  
  topics:
    - name: orders
      partitions: 20       # Scale with throughput
      retention: 24h

Queue Depth = Messages Published - Messages Consumed
If Queue Depth > threshold:
  Scale workers up (add N replicas)
If Queue Depth < threshold:
  Scale workers down

# Redis cluster for horizontal caching
cache:
  provider: redis-cluster
  replicas: 3
  nodes: 6
  
  partitioning: hash-slot
  eviction_policy: allkeys-lru
  max_memory: 100GB

┌─────────┐  ┌─────────┐  ┌─────────┐
│ Node 1  │  │ Node 2  │  │ Node 3  │
│ Slot    │  │ Slot    │  │ Slot    │
│ 0-5460  │  │ 5461-10921  │ 10922-16383
└─────────┘  └─────────┘  └─────────┘
  ↓             ↓             ↓
Single logical cache (16384 slots)

-- Partition orders by date
CREATE TABLE orders_2024_q1 PARTITION OF orders
  FOR VALUES FROM ('2024-01-01') TO ('2024-04-01');
 
CREATE TABLE orders_2024_q2 PARTITION OF orders
  FOR VALUES FROM ('2024-04-01') TO ('2024-07-01');

-- Partition by customer ID range
CREATE TABLE orders_shard_0 PARTITION OF orders
  FOR VALUES FROM (0) TO (100000);
 
CREATE TABLE orders_shard_1 PARTITION OF orders
  FOR VALUES FROM (100000) TO (200000);

database:
  primary:
    host: db-primary.prod.svc.cluster.local
    pool_size: 10
  
  replicas:
    - host: db-replica-1.prod.svc.cluster.local
    - host: db-replica-2.prod.svc.cluster.local
    - host: db-replica-3.prod.svc.cluster.local

// Route reads to replicas
func GetCustomer(ctx context.Context, id string) (*Customer, error) {
    db := selectReplicaRoundRobin()  // Load balance
    return db.GetCustomer(ctx, id)
}
 
// Route writes to primary
func UpdateCustomer(ctx context.Context, customer *Customer) error {
    return primary.Update(customer)
}

# Synchronous workflow
states:
  - name: ProcessOrder
    type: Task
    resource: urn:cascade:activity:heavy_processing
    timeout: 300s        # 5 minutes!
    end: true
 
# ✅ Asynchronous workflow
states:
  - name: QueueOrder
    type: Task
    resource: urn:cascade:activity:queue_processing
    timeout: 5s          # Fast
    next: ReturnResult
  
  - name: ReturnResult
    type: Task
    end: true
  
  # Separate async workflow
  # Consumes from queue, processes in background

alerts:
  - name: HighQueueDepth
    condition: "queue_depth > 100"
    action: scale_up
    target: "+5 workers"
  
  - name: LowQueueDepth
    condition: "queue_depth < 10 for 5m"
    action: scale_down
    target: "-2 workers"