Architecture Uncloud follows a hybrid intent/runtime architecture where SQLite stores what the user requested (intent) and Kubernetes holds the actual running state (runtime truth). A sync loop reconciles the two every 15 seconds.

​
System Overview

​
Core Design Principles

​
Hybrid DB/K8s Model

Intent Layer

SQLite stores what the user requested — resource names, configs, and relationships.

Runtime Layer

Kubernetes holds what’s actually running — IPs, pod phases, and ready replicas.

Sync Layer

Go goroutine reconciles every 15 seconds between intent and runtime.
This design means:
  • The API is fast — reads from SQLite, not the K8s API
  • Kubernetes is the source of truth for running state
  • If K8s is temporarily unreachable, the API still serves data
  • New resources are created in SQLite first, then provisioned to K8s

​
Resource Lifecycle

​
Tech Stack

​
Backend

​
Frontend

​
Backend Architecture

​
Layer Structure

​
Domain Models

Resources use prefixed IDs for clarity:

​
Multi-Tenancy

Projects are the isolation boundary. Each project maps to a Kubernetes namespace. All resources are scoped to a project via project_id.

Project: production

  • Droplet web-server
  • App api-service
  • Database main-pg
  • Volume data-vol
Maps to K8s namespace production

Project: staging

  • Droplet test-vm
  • App api-staging
  • Database staging-pg
Maps to K8s namespace staging

​
Kubernetes Integration

​
Resource Mapping

​
Provisioner System

Infrastructure components installed via admin setup: