Rodrigo Rodriguez (Pragmatismo) 6bfab51293 Add Scale chapter with sharding and database optimization docs

New Chapter 18 - Scale:
- README with overview of scaling architecture
- Sharding Architecture: tenant routing, shard config, data model, operations
- Database Optimization: SMALLINT enums, indexing, partitioning, connection pooling

Enum reference tables for all domain values (Channel, Message, Task, etc.)
Best practices for billion-user scale deployments

2025-12-29 12:55:32 -03:00

3.6 KiB

Raw Blame History

Scale

This chapter covers horizontal scaling strategies for General Bots to support millions to billions of users across global deployments.

Overview

General Bots is designed from the ground up to scale horizontally. The architecture supports:

Multi-tenancy: Complete isolation between organizations
Regional sharding: Data locality for compliance and performance
Database partitioning: Efficient handling of high-volume tables
Stateless services: Easy horizontal pod autoscaling

Chapter Contents

Sharding Architecture - How data is distributed across shards
Database Optimization - Schema design for billion-scale
Regional Deployment - Multi-region setup
Performance Tuning - Optimization strategies

Key Concepts

Tenant Isolation

Every piece of data in General Bots is associated with a tenant_id. This enables:

Complete data isolation between organizations
Per-tenant resource limits and quotas
Tenant-specific configurations
Easy data export/deletion for compliance

Shard Architecture

┌─────────────────────────────────────────────────────────────┐
│                      Load Balancer                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
   ┌─────────┐       ┌─────────┐       ┌─────────┐
   │ Region  │       │ Region  │       │ Region  │
   │   USA   │       │   EUR   │       │   APAC  │
   └────┬────┘       └────┬────┘       └────┬────┘
        │                 │                 │
   ┌────┴────┐       ┌────┴────┐       ┌────┴────┐
   │ Shard 1 │       │ Shard 2 │       │ Shard 3 │
   │ Shard 4 │       │ Shard 5 │       │ Shard 6 │
   └─────────┘       └─────────┘       └─────────┘

Database Design Principles

SMALLINT enums instead of VARCHAR for domain values (2 bytes vs 20+ bytes)
Partitioned tables for high-volume data (messages, sessions, analytics)
Composite primary keys including shard_id for distributed queries
Snowflake-like IDs for globally unique, time-sortable identifiers

When to Scale

Users	Sessions/day	Messages/day	Recommended Setup
< 10K	< 100K	< 1M	Single node
10K-100K	100K-1M	1M-10M	2-3 nodes, single region
100K-1M	1M-10M	10M-100M	Multi-node, consider sharding
1M-10M	10M-100M	100M-1B	Regional shards
> 10M	> 100M	> 1B	Global shards with Citus/CockroachDB

Quick Start

To enable sharding in your deployment:

Configure shard mapping in shard_config table
Set SHARD_ID environment variable per instance
Deploy region-specific instances
Configure load balancer routing rules

See Sharding Architecture for detailed setup instructions.

3.6 KiB Raw Blame History