Savannah Cloud

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_email
  • send_sms
  • webhook
  • git_deploy
  • stack_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 failed

This 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

On this page