Architecture Overview#

ChatAPI is designed as a lightweight, production-ready chat service with a focus on simplicity, reliability, and multi-tenant operation.

🏛️ System Architecture#

ChatAPI follows a service-oriented architecture with clear separation of concerns:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   HTTP Server   │    │  WebSocket      │    │ Background      │
│   (REST API)    │    │  Server         │    │   Workers       │
└─────────────────┘    └─────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                    ┌─────────────────┐
                    │   Services      │
                    │   Layer         │
                    └─────────────────┘
                             │
                    ┌─────────────────┐
                    │   Database      │
                    │   (SQLite)      │
                    └─────────────────┘

📦 Core Components#

HTTP Server (REST API)#

  • Framework: Standard Go net/http
  • Endpoints: RESTful API for chat operations
  • Middleware: Authentication, rate limiting, CORS
  • Serialization: JSON request/response handling

WebSocket Server#

  • Library: Gorilla WebSocket
  • Protocol: Custom JSON-based protocol
  • Features: Real-time messaging, presence, typing indicators
  • Connection Management: Per-user connection pooling

Background Workers#

  • Delivery Worker: Processes undelivered messages and notifications
  • WAL Checkpoint Worker: Manages SQLite WAL file growth
  • Scheduler: Configurable intervals with graceful shutdown

Services Layer#

  • Tenant Service: API key validation and tenant management
  • Chatroom Service: Room creation and membership management
  • Message Service: Message storage and retrieval
  • Realtime Service: WebSocket connection and pub/sub
  • Notification Service: Notification creation and delivery
  • Delivery Service: Message delivery with retry logic

Database Layer#

  • Engine: SQLite with WAL mode
  • Migrations: Version-controlled schema updates
  • Connection Pooling: Single-writer, multiple-reader pattern

🔐 Security Model#

Authentication#

  • API Keys: Tenant-level authentication via X-API-Key header
  • User Context: User identification via X-User-Id header
  • WebSocket Auth: Header or query parameter authentication
  • No Sessions: Stateless authentication for horizontal scaling

Authorization#

  • Room Membership: Users can only access rooms they belong to
  • Message Ownership: Users can only modify their own messages
  • Tenant Isolation: Complete data isolation between tenants
  • Rate Limiting: Per-tenant request throttling

💾 Database Schema#

Core Tables#

-- Tenants (multi-tenant isolation)
CREATE TABLE tenants (
  tenant_id TEXT PRIMARY KEY,
  api_key TEXT UNIQUE NOT NULL,
  name TEXT,
  config JSON,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Rooms (chat rooms and channels)
CREATE TABLE rooms (
  room_id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  type TEXT NOT NULL,           -- 'dm'|'group'|'channel'
  unique_key TEXT NULL,         -- deterministic key for DMs
  name TEXT NULL,
  last_seq INTEGER DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Room membership
CREATE TABLE room_members (
  chatroom_id TEXT NOT NULL,
  tenant_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  role TEXT DEFAULT 'member',
  joined_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY(chatroom_id, user_id)
);

-- Messages with sequencing
CREATE TABLE messages (
  message_id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  chatroom_id TEXT NOT NULL,
  sender_id TEXT NOT NULL,
  seq INTEGER NOT NULL,          -- per-room sequence
  content TEXT NOT NULL,
  meta JSON NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

-- Delivery tracking
CREATE TABLE delivery_state (
  tenant_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  chatroom_id TEXT NOT NULL,
  last_ack INTEGER DEFAULT 0,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (tenant_id, user_id, chatroom_id)
);

-- Undelivered message queue
CREATE TABLE undelivered_messages (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  tenant_id TEXT NOT NULL,
  user_id TEXT NOT NULL,
  chatroom_id TEXT NOT NULL,
  message_id TEXT NOT NULL,
  seq INTEGER NOT NULL,
  attempts INTEGER DEFAULT 0,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  last_attempt_at DATETIME NULL
);

-- Notifications system
CREATE TABLE notifications (
  notification_id TEXT PRIMARY KEY,
  tenant_id TEXT NOT NULL,
  topic TEXT NOT NULL,
  payload JSON NOT NULL,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  status TEXT DEFAULT 'pending',
  attempts INTEGER DEFAULT 0,
  last_attempt_at DATETIME NULL
);

Indexes and Performance#

-- Room queries
CREATE INDEX idx_rooms_tenant ON rooms(tenant_id, room_id);
CREATE UNIQUE INDEX idx_rooms_unique_key ON rooms(tenant_id, unique_key);

-- Membership queries
CREATE INDEX idx_members_tenant_user ON room_members(tenant_id, user_id);
CREATE INDEX idx_members_tenant_room ON room_members(tenant_id, chatroom_id);

-- Message queries with pagination
CREATE INDEX idx_messages_room_seq ON messages(tenant_id, chatroom_id, seq);

-- Delivery state
CREATE INDEX idx_delivery_user_room ON delivery_state(tenant_id, user_id, chatroom_id);

-- Undelivered queue processing
CREATE INDEX idx_undelivered_user_room_seq ON undelivered_messages(tenant_id, user_id, chatroom_id, seq);
CREATE INDEX idx_undelivered_attempts ON undelivered_messages(tenant_id, attempts, created_at);

-- Notification processing
CREATE INDEX idx_notifications_status ON notifications(tenant_id, status, created_at);

🔄 Data Flow#

Message Sending Flow#

  1. Client Request: User sends message via REST or WebSocket
  2. Authentication: Validate API key and user identity
  3. Rate Limiting: Check tenant request limits
  4. Transaction: Atomically increment room sequence and store message
  5. Real-time Delivery: Broadcast to online room members
  6. Queue Undelivered: Store for offline users
  7. Response: Return message ID and sequence number

Message Delivery Flow#

  1. Store-then-Send: Messages stored before delivery attempts
  2. Online Delivery: Immediate WebSocket delivery for connected users
  3. Offline Queueing: Persistent queue for disconnected users
  4. Retry Logic: Exponential backoff with configurable limits
  5. Dead Letter: Failed deliveries moved to dead-letter queue
  6. Cleanup: Periodic removal of acknowledged messages

WebSocket Connection Flow#

  1. Connection: Client establishes WebSocket connection
  2. Authentication: Validate credentials on connection
  3. Registration: Add to user’s connection pool
  4. Presence Update: Broadcast online status to room members
  5. Message Sync: Stream missed messages since last ACK
  6. Real-time Events: Bidirectional message exchange
  7. Disconnection: Clean up with grace period for reconnection

📊 Performance Characteristics#

Throughput#

  • Messages/second: 10,000+ (depending on hardware)
  • Concurrent Connections: 100,000+ WebSocket connections
  • Database: SQLite handles 1,000+ concurrent readers

Latency#

  • REST API: <10ms typical response time
  • WebSocket Delivery: <1ms for local delivery
  • Database Queries: <5ms for typical operations

Scalability Limits#

  • Single Instance: 10,000 concurrent users
  • Database Size: 100GB+ SQLite databases supported
  • Memory Usage: ~50MB base + 1KB per active WebSocket connection

🛡️ Reliability Features#

Data Durability#

  • WAL Mode: Write-ahead logging for crash recovery
  • Atomic Transactions: Multi-table operations are atomic
  • Backup Strategy: Hot backups with WAL preservation

High Availability#

  • Graceful Shutdown: Clean connection draining
  • Connection Recovery: Automatic reconnection with message sync
  • Health Checks: Comprehensive service monitoring

Error Handling#

  • Retry Logic: Configurable retry attempts with backoff
  • Circuit Breakers: Prevent cascade failures
  • Dead Letter Queues: Failed message handling

🔧 Operational Aspects#

Monitoring#

  • Health Endpoints: /health for service status
  • Metrics: Structured JSON logging
  • Admin Endpoints: /admin/dead-letters for debugging

Configuration#

  • Environment Variables: Runtime configuration
  • Tenant Config: Per-tenant feature flags
  • Database Tuning: WAL and connection parameters

Deployment#

  • Single Binary: Self-contained Go application
  • Docker Support: Container-ready deployment
  • Systemd: Service integration for Linux systems

🚀 Extensibility#

Plugin Architecture#

  • Service Interfaces: Clean interfaces for custom implementations
  • Middleware: Extensible request processing pipeline
  • Event Hooks: Integration points for custom logic

API Evolution#

  • Versioning: URL-based API versioning
  • Backward Compatibility: Non-breaking changes maintained
  • Deprecation Notices: Clear migration paths

Storage Backend#

  • SQLite Default: Embedded, zero-configuration
  • PostgreSQL: Planned enterprise option
  • Custom Storage: Interface-based abstraction

📈 Scaling Strategy#

Vertical Scaling#

  • Memory: Increase RAM for more connections
  • CPU: More cores for concurrent processing
  • Storage: Faster disks for database performance

Horizontal Scaling (Future)#

  • Load Balancer: Distribute requests across instances
  • Shared Database: PostgreSQL for multi-instance deployments
  • Pub/Sub: NATS or Redis for cross-instance communication
  • Session Store: Shared session state for WebSocket connections

Multi-Region (Future)#

  • Database Replication: Cross-region data synchronization
  • CDN: Static asset delivery
  • Global Load Balancing: Geographic request routing

This architecture is designed for simplicity while maintaining production reliability. The service-oriented design allows for independent scaling and maintenance of components.

Backward Guides