Architecture
How Savannah Cloud components fit together across deploys, DNS, jobs, billing, and security.
System overview
┌──────────────────────────────────────────────────────┐
│ Client / Deployed App │
│ (API Key · JWT · MCP tool call · Dashboard UI) │
└────────────────────────┬─────────────────────────────┘
│
┌─────────▼──────────┐
│ Go API Server │ :8080
│ auth · jobs │
│ deploy · domains │
│ email · sms · mcp · ml │
└──┬──────────────┬──┘
│ │
┌─────────▼──┐ ┌───────▼────────┐
│ Redis │ │ PostgreSQL │
│ Job Queue │ │ orgs · users │
│ Sessions │ │ jobs · domains│
└────────────┘ │ deployments │
│ api_keys │
└───────────────-┘
│
┌─────────▼──────────┐ ┌─────────────────┐
│ Worker Pool (x4) │ │ PowerDNS │
│ send_email │ │ (custom domains │
│ send_sms │ │ ns1/ns2 │
│ webhook · deploy │ │ savannahcloud) │
└────────────────────┘ └─────────────────┘
│ WebSocket
┌─────────▼──────────────────────┐
│ TanStack Console :3000 │
│ Deployments · Domains · Email │
│ SMS · Pipelines · Team · Billing│
└────────────────────────────────┘Core components
Go API server
The API server is the central control plane for the platform. It handles:
- auth and session management
- deployment orchestration
- billing and usage
- DNS and custom domain management
- job ingestion and queue coordination
- WAF, audit, security, and tenant metadata
- MCP endpoint integration
Redis queue
Redis is the transport used for asynchronous work. It supports:
- BLPOP-based worker polling
- FIFO ordering
- retry and exponential backoff behavior
- job serialization and status tracking
PostgreSQL
PostgreSQL stores the durable state for the platform:
- organizations and users
- API keys and auth records
- deployment metadata and logs
- queued jobs and statuses
- DNS and domain state
- security, billing, and audit records
Worker pool
The platform runs multiple workers to process jobs concurrently:
send_emailsend_smswebhookgit_deploystack_deploy- custom user-defined job types
DNS and nameservers
PowerDNS manages custom domain records and nameserver delegation for org-level domains.
Object storage
Cloudflare R2 stores deployment artifacts and build outputs for public serving and CDN-backed delivery.
Job lifecycle
POST /jobs
│
├─ validate auth (JWT or API key)
├─ insert job into Postgres
├─ enqueue in Redis
└─ return 202 Accepted
│
▼
Worker picks up Redis job
│
├─ mark processing
├─ execute handler
├─ success → mark done + logs
└─ failure → retry or mark failedThis keeps the API request lightweight while work executes asynchronously in background workers.
Multi-tenancy and isolation
Every org has its own tenant-scoped data model. Auth middleware binds the request to an org context, and every relevant query is scoped to that tenant. This keeps deployments, jobs, domains, and usage isolated per organization.
Security architecture
Savannah Cloud includes:
- bcrypt password hashing
- JWT-based sessions
- hashed API keys and scoped permissions
- rate limiting and WAF inspection
- audit logging for admin operations
- ML-based anomaly detection for suspicious traffic
HA and reliability
- Redis cluster support with failover
- PostgreSQL streaming replication and promotion support
- health checks for HTTP/TCP/process/log monitoring
- automatic failover and cluster status tracking
- metrics exposed via Prometheus
Frontend and operator console
The console provides the visual operations layer for:
- deployments and logs
- domains and DNS records
- billing and usage
- team and permission management
- job monitoring and queue health
- support tickets and security state