Architecture
This document describes Waxell's data flow architecture, including tenant isolation, security features, and enterprise capabilities.
Overview Diagram
┌─────────────────────────────────────────────────────────────────────────────────┐
│ TENANT REQUEST FLOW │
└─────────────────────────────────────────────────────────────────────────────────┘
┌──────────────────┐
│ Client/SDK │
│ (API Request) │
└────────┬─────────┘
│
┌──────────────────▼──────────────────┐
│ AWS WAF │
│ • Rate limiting (100 req/sec) │
│ • SQL injection protection │
│ • XSS filtering │
└──────────────────┬──────────────────┘
│
┌──────────────────▼──────────────────┐
│ Application Load Balancer │
│ • TLS termination │
│ • Request routing │
└──────────────────┬──────────────────┘
│
┌──────────────────────────────┼──────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ Controlplane │ │ Runtime │ │ Celery │
│ (Django) │ │ Workers │ │ Workers │
└───────┬───────┘ └───────┬───────┘ └───────┬───────┘
│ │ │
└────────────────────────────┼────────────────────────────┘
│
┌────────────────┴────────────────┐
│ │
┌───────────▼───────────┐ ┌───────────▼───────────┐
│ Tenant Middleware │ │ Region Router │
│ • Schema selection │ │ • DB routing │
│ • X-Tenant-Slug │ │ • Cache routing │
└───────────┬───────────┘ └───────────┬───────────┘
│ │
└────────────────┬────────────────┘
│
┌────────────────────────────┼────────────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ PostgreSQL │ │ Redis │ │ S3 │
│ (per-schema) │ │ (TLS+AUTH) │ │ (encrypted) │
│ • RDS SSL │ │ • Celery │ │ • per-region │
│ • Multi-AZ │ │ • Cache │ │ • Object Lock│
└───────────────┘ └───────────────┘ └───────────────┘
Package Architecture
Waxell enforces strict boundaries between packages:
| Package | Responsibility | Dependencies |
|---|---|---|
| SDK | Intent-only definitions | stdlib, pydantic |
| Runtime | Execution engine | SDK |
| Controlplane | Views, APIs, admin | SDK, Runtime |
| Generation | RAG, LLM synthesis | SDK |
| Infra | Production backends | All packages |
SDK ────────► Runtime
│ ▲
│ │
└──────► Generation
Controlplane ──► SDK
Controlplane ──► Runtime (APIs/queues only)
Infra orchestrates all packages
Data Residency
Data residency allows enterprise tenants to select where their data is stored:
┌─────────────────────┐
│ Tenant Request │
│ tenant_id: abc123 │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ TenantRegionRouter │
│ get_tenant_region() │
└──────────┬──────────┘
│
┌────────────────────┴────────────────────┐
│ │
┌───────────▼───────────┐ ┌────────────▼────────────┐
│ US East (Default) │ │ EU West (+$500/mo) │
│ ───────────────── │ │ ──────────────────── │
│ • RDS: us-east-1 │ │ • RDS: eu-west-1 │
│ • Redis: us-east-1 │ │ • Redis: eu-west-1 │
│ • S3: waxell-us │ │ • S3: waxell-eu │
│ │ │ │
│ Compliance: │ │ Compliance: │
│ • HIPAA, SOC2 │ │ • GDPR, SOC2 │
└───────────────────────┘ └─────────────────────────┘
Field-Level Encryption
Sensitive data is encrypted using tenant-specific keys:
WRITE PATH:
Model.save() → EncryptedJSONField → TenantEncryptionService
│
┌───────────────────────┴───────────────────────┐
▼ ▼
AWS KMS (Get DEK) AES-256-GCM Encrypt
│ │
└───────────────────────┬───────────────────────┘
▼
Ciphertext [key_id|nonce|data]
READ PATH:
Model.query() → EncryptedJSONField → Parse key_id → KMS Decrypt DEK
│
▼
Plaintext JSON
Security Components
| Component | Purpose | Implementation |
|---|---|---|
| TLS Everywhere | Encryption in transit | ALB, RDS, Redis |
| Field Encryption | Encryption at rest | AES-256-GCM + KMS |
| Schema Isolation | Tenant data separation | PostgreSQL schemas |
| Hash Chain Audit | Tamper-evident logging | SHA-256 chaining |
| WAF | Request filtering | AWS WAF |
Next Steps
- Enterprise Guide - Configure enterprise features
- Backends Reference - Configure production backends