Architecture Overview

Satusky is a multi-tenant PaaS built directly on Kubernetes. It does not replace Kubernetes with a proprietary scheduler; it uses Kubernetes as the workload runtime and wraps it with a purpose-built API for tenancy, deployment orchestration, networking, billing, machine management, and observability.

This architecture section documents both:

current implementation — what the system does today, and
target architecture — the shape the platform is intentionally moving toward where a migration is already underway.

When those differ, the docs call the difference out explicitly instead of presenting the target state as though it already exists.

The three planes

┌─────────────────────────────────────────────────────────────┐
│  Control Plane                                              │
│  Satusky API (Go/Fiber) + PostgreSQL                        │
│  Auth, desired state, billing, orchestration, WebSockets    │
└────────────────────┬────────────────────────────────────────┘
                     │  client-go / Talos API / SideroLink
┌────────────────────▼────────────────────────────────────────┐
│  Workload Plane                                             │
│  Kubernetes clusters — Deployments, Services, HTTPRoutes,   │
│  legacy Ingresses, Secrets, PVCs                            │
└────────────────────┬────────────────────────────────────────┘
                     │  nodes, storage, edge networking
┌────────────────────▼────────────────────────────────────────┐
│  Infrastructure Plane                                       │
│  Talos Linux nodes, SideroLink, Gateway API, cert-manager,  │
│  external-dns, Ceph RGW, Prometheus                         │
└─────────────────────────────────────────────────────────────┘

Control plane. The Satusky API stores platform metadata in PostgreSQL and drives other systems: Kubernetes through client-go, Talos machines through Talos APIs, and machine discovery through SideroLink. It is the source of truth for desired platform state, not for every live runtime fact.

Workload plane. Kubernetes clusters run user workloads. PostgreSQL says what should exist; Kubernetes says what is actually running now. The API reconciles between the two.

Infrastructure plane. Talos nodes provide the machine substrate; SideroLink provides management reachability; Gateway API / legacy Ingress, cert-manager, external-dns, Ceph RGW, and Prometheus provide networking, storage, and telemetry primitives.

High-level request path

Developer
  │
  ▼
1ctl / dashboard
  │  HTTPS REST + WebSocket
  ▼
Satusky API ───── PostgreSQL
  │       │
  │       ├──── Talos API over SideroLink
  │       └──── Prometheus / metrics APIs
  │
  └──── client-go
        ▼
Kubernetes clusters
  Deployments / Services / routes / PVCs

A single API service coordinates multiple clusters. PostgreSQL stores tenant metadata, deployment intent, billing records, and domain state. Kubernetes stores workload runtime state. SideroLink and Talos extend the control plane below Kubernetes for bring-your-own-machine workflows.

Four-layer API architecture

Layer	Responsibility
Routes	HTTP registration, middleware, path parameters
Controllers	Request parsing, validation, response shaping
Services	Business orchestration across DB, Kubernetes, Talos, DNS, and events
Queriers	SQL access through generated query code

Services are where platform meaning lives. A deploy is not merely an insert plus a Kubernetes call; it is desired-state resolution, persistence, reconciliation, and event publication.

Multi-tenancy model

Current model

User
  └── Organization
        └── Kubernetes namespace
              └── Deployments / routes / Secrets / PVCs

An Organization is the primary billing and isolation boundary. In the current backend, each organization has one stored Kubernetes namespace, and resources for that organization are created in that namespace. Users can belong to multiple organizations through organization_users membership records.

Deployments also carry an environment field, but that is metadata/configuration — it is not currently a second Kubernetes namespace hierarchy beneath the organization namespace.

Target direction

If Satusky later introduces richer project/environment isolation inside an organization, the architecture should state that explicitly and define whether it becomes:

separate Kubernetes namespaces,
labels inside one namespace, or
a higher-level Satusky-only grouping.

Until then, the clean mental model is organization = Kubernetes namespace boundary.

Key infrastructure components

Component	Current role
Gateway API	Default/generated app domains use `HTTPRoute` when Gateway mode is enabled.
Legacy Ingress	Still used today for custom domains, aliases, and `www` redirects. It is a compatibility path, not the target end state.
cert-manager	Provisions TLS certificates for public hostnames.
external-dns / DNS automation	Publishes platform-managed records and participates in domain reconciliation.
SideroLink	Discovers Talos machines and gives the control plane stable management reachability through a WireGuard overlay.
Talos API	Supplies machine lifecycle and low-level OS state below Kubernetes.
Ceph RGW	S3-compatible object storage.
Prometheus + Kubernetes metrics APIs	Power live telemetry, historical observations, machine health, and billing-adjacent measurement.
NATS	Internal coordination primitive for platform workflows such as TCP port allocation.

Current seams under active evolution

Area	Current state	Target state
Public routing	Default domains use Gateway API; custom domains still use legacy Ingress.	Gateway API becomes the single public routing primitive.
Marketplace workloads	Separate marketplace deployment path eventually creates ordinary deployment records.	Template resolution feeds the shared deployment pipeline.
Machine management	Backend has rich SideroLink/Talos primitives; CLI is still thin.	Tenant-facing fleet management through `1ctl machine`.
Domain diagnostics	Metadata exists, but reconciliation is not yet fully user-visible.	One domain model spanning metadata, route, DNS, TLS, and probe health.
Observability	Backend has useful metrics, WebSockets, and health jobs.	One coherent user-facing model for workload, endpoint, and machine health.