# tonioot/cloudbase architecture

> Architecture diagram of the GitHub repository tonioot/cloudbase, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tonioot/cloudbase
- Repository: https://github.com/tonioot/cloudbase

## Overview

Cloudbase is a self-hosted deployment and operations panel for running Docker applications and managed databases across a primary server and remote nodes. The main workflow is: an operator configures an app in the panel, the API coordinates repository builds and instance placement, node agents reconcile desired state, and NGINX routes visitors to healthy instances. Separate branches cover databases and backups, scheduled jobs, node networking, and operations such as metrics and notifications. The README supports the high-level workflow; source excerpts and the index support only selected internal calls, so unsampled relationships are omitted.

Main entry points: [`backend/apps/runtime.py`](https://github.com/tonioot/cloudbase/blob/main/backend/apps/runtime.py) (Instance runtime), [`backend/routers/applications`](https://github.com/tonioot/cloudbase/tree/main/backend/routers/applications) (Application routes), [`backend/apps/deployments.py`](https://github.com/tonioot/cloudbase/blob/main/backend/apps/deployments.py) (Deploy and rollout), [`backend/routers/databases`](https://github.com/tonioot/cloudbase/tree/main/backend/routers/databases) (Database routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_panel["Panel and API"]
  node_frontend["Web panel<br/>[app.js]"]
  node_api["HTTP API<br/>[main.py]"]
  node_auth["Auth and permissions<br/>[auth.py]"]
  node_app_routes["Application routes"]
end

subgraph group_apps["Application runtime"]
  node_app_records[("App configuration<br/>[models.py]")]
  node_git["Repository builds<br/>[git.py]"]
  node_rollout["Deploy and rollout<br/>[deployments.py]"]
  node_runtime["Instance runtime<br/>[runtime.py]"]
  node_containers["Docker containers<br/>[client.py]"]
  node_cron["Cron scheduler<br/>[scheduler.py]"]
end

subgraph group_fleet["Nodes and networking"]
  node_nginx["Traffic routing<br/>[files.py]"]
  node_node_registry["Node registry<br/>[registry.py]"]
  node_desired["Desired workloads<br/>[desired.py]"]
  node_agent["Node agent<br/>[loop.py]"]
  node_mesh["Private node mesh<br/>[hub.py]"]
end

subgraph group_data["Databases and backups"]
  node_database_api["Database routes"]
  node_db_engines["Database engines<br/>[engines.py]"]
  node_db_docker["Database containers<br/>[docker.py]"]
  node_backups["Database backups<br/>[backups.py]"]
end

subgraph group_operations["Operations"]
  node_metrics["Metrics and logs<br/>[stats.py]"]
  node_notifications["Notifications<br/>[dispatch.py]"]
  node_transfer["Export and import<br/>[full.py]"]
end

node_operator(("Operator"))
node_visitor(("App visitor"))

node_operator -->|"manages"| node_frontend
node_frontend -.->|"calls API"| node_api
node_api -->|"registers routes"| node_app_routes
node_app_routes -.->|"checks permissions"| node_auth
node_app_routes -.->|"configures apps"| node_app_records
node_app_routes -.->|"requests deploy"| node_rollout
node_rollout -.->|"builds source"| node_git
node_git -->|"builds image"| node_containers
node_rollout -.->|"coordinates instances"| node_runtime
node_runtime -->|"uses node registry"| node_node_registry
node_runtime -->|"ensures source"| node_git
node_runtime -->|"syncs routing"| node_nginx
node_runtime -->|"sets workloads"| node_desired
node_agent -->|"reconciles desired state"| node_desired
node_agent -->|"matches Docker state"| node_containers
node_visitor -->|"requests app"| node_nginx
node_nginx -->|"routes to healthy instances"| node_runtime
node_node_registry -->|"joins private network"| node_mesh
node_operator -->|"manages databases"| node_database_api
node_database_api -.->|"selects engine"| node_db_engines
node_database_api -.->|"manages database"| node_db_docker
node_db_docker -->|"uses engine configuration"| node_db_engines
node_operator -->|"backs up data"| node_backups
node_operator -->|"configures schedules"| node_cron
node_cron -->|"runs job containers"| node_containers
node_operator -->|"observes fleet"| node_metrics
node_operator -->|"configures alerts"| node_notifications
node_operator -->|"exports or imports"| node_transfer

click node_frontend "https://github.com/tonioot/cloudbase/blob/main/frontend/js/app.js"
click node_api "https://github.com/tonioot/cloudbase/blob/main/backend/main.py"
click node_auth "https://github.com/tonioot/cloudbase/blob/main/backend/core/auth.py"
click node_app_routes "https://github.com/tonioot/cloudbase/tree/main/backend/routers/applications"
click node_app_records "https://github.com/tonioot/cloudbase/blob/main/backend/core/models.py"
click node_git "https://github.com/tonioot/cloudbase/blob/main/backend/apps/git.py"
click node_rollout "https://github.com/tonioot/cloudbase/blob/main/backend/apps/deployments.py"
click node_runtime "https://github.com/tonioot/cloudbase/blob/main/backend/apps/runtime.py"
click node_containers "https://github.com/tonioot/cloudbase/blob/main/backend/containers/client.py"
click node_cron "https://github.com/tonioot/cloudbase/blob/main/backend/cron/scheduler.py"
click node_nginx "https://github.com/tonioot/cloudbase/blob/main/backend/nginx/files.py"
click node_node_registry "https://github.com/tonioot/cloudbase/blob/main/backend/nodes/registry.py"
click node_desired "https://github.com/tonioot/cloudbase/blob/main/backend/nodes/desired.py"
click node_agent "https://github.com/tonioot/cloudbase/blob/main/backend/agent/loop.py"
click node_mesh "https://github.com/tonioot/cloudbase/blob/main/backend/mesh/hub.py"
click node_database_api "https://github.com/tonioot/cloudbase/tree/main/backend/routers/databases"
click node_db_engines "https://github.com/tonioot/cloudbase/blob/main/backend/dbs/engines.py"
click node_db_docker "https://github.com/tonioot/cloudbase/blob/main/backend/dbs/docker.py"
click node_backups "https://github.com/tonioot/cloudbase/blob/main/backend/dbs/backups.py"
click node_metrics "https://github.com/tonioot/cloudbase/blob/main/backend/workers/stats.py"
click node_notifications "https://github.com/tonioot/cloudbase/blob/main/backend/notify/dispatch.py"
click node_transfer "https://github.com/tonioot/cloudbase/blob/main/backend/transfer/full.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_frontend,node_api,node_auth,node_app_routes toneBlue
class node_app_records,node_git,node_rollout,node_runtime,node_containers,node_cron toneAmber
class node_nginx,node_node_registry,node_desired,node_agent,node_mesh toneMint
class node_database_api,node_db_engines,node_db_docker,node_backups toneRose
class node_metrics,node_notifications,node_transfer,node_operator,node_visitor toneIndigo
```

## Components

### Panel and API

- [Web panel](https://github.com/tonioot/cloudbase/blob/main/frontend/js/app.js): `frontend/js/app.js`
- [HTTP API](https://github.com/tonioot/cloudbase/blob/main/backend/main.py): `backend/main.py`
- [Auth and permissions](https://github.com/tonioot/cloudbase/blob/main/backend/core/auth.py): `backend/core/auth.py`
- [Application routes](https://github.com/tonioot/cloudbase/tree/main/backend/routers/applications): `backend/routers/applications`

### Application runtime

- [App configuration](https://github.com/tonioot/cloudbase/blob/main/backend/core/models.py): `backend/core/models.py`
- [Repository builds](https://github.com/tonioot/cloudbase/blob/main/backend/apps/git.py): `backend/apps/git.py`
- [Deploy and rollout](https://github.com/tonioot/cloudbase/blob/main/backend/apps/deployments.py): `backend/apps/deployments.py`
- [Instance runtime](https://github.com/tonioot/cloudbase/blob/main/backend/apps/runtime.py): `backend/apps/runtime.py`
- [Docker containers](https://github.com/tonioot/cloudbase/blob/main/backend/containers/client.py): `backend/containers/client.py`
- [Cron scheduler](https://github.com/tonioot/cloudbase/blob/main/backend/cron/scheduler.py): `backend/cron/scheduler.py`

### Nodes and networking

- [Traffic routing](https://github.com/tonioot/cloudbase/blob/main/backend/nginx/files.py): `backend/nginx/files.py`
- [Node registry](https://github.com/tonioot/cloudbase/blob/main/backend/nodes/registry.py): `backend/nodes/registry.py`
- [Desired workloads](https://github.com/tonioot/cloudbase/blob/main/backend/nodes/desired.py): `backend/nodes/desired.py`
- [Node agent](https://github.com/tonioot/cloudbase/blob/main/backend/agent/loop.py): `backend/agent/loop.py`
- [Private node mesh](https://github.com/tonioot/cloudbase/blob/main/backend/mesh/hub.py): `backend/mesh/hub.py`

### Databases and backups

- [Database routes](https://github.com/tonioot/cloudbase/tree/main/backend/routers/databases): `backend/routers/databases`
- [Database engines](https://github.com/tonioot/cloudbase/blob/main/backend/dbs/engines.py): `backend/dbs/engines.py`
- [Database containers](https://github.com/tonioot/cloudbase/blob/main/backend/dbs/docker.py): `backend/dbs/docker.py`
- [Database backups](https://github.com/tonioot/cloudbase/blob/main/backend/dbs/backups.py): `backend/dbs/backups.py`

### Operations

- [Metrics and logs](https://github.com/tonioot/cloudbase/blob/main/backend/workers/stats.py): `backend/workers/stats.py`
- [Notifications](https://github.com/tonioot/cloudbase/blob/main/backend/notify/dispatch.py): `backend/notify/dispatch.py`
- [Export and import](https://github.com/tonioot/cloudbase/blob/main/backend/transfer/full.py): `backend/transfer/full.py`

### Other components

- **Operator**
- **App visitor**

## Connections

- Operator → Web panel: manages
- Web panel → HTTP API: calls API
- HTTP API → Application routes: registers routes (evidence: `backend/main.py`)
- Application routes → Auth and permissions: checks permissions (evidence: `backend/routers/applications/webhook.py`)
- Application routes → App configuration: configures apps
- Application routes → Deploy and rollout: requests deploy
- Deploy and rollout → Repository builds: builds source
- Repository builds → Docker containers: builds image (evidence: `backend/apps/git.py`)
- Deploy and rollout → Instance runtime: coordinates instances
- Instance runtime → Node registry: uses node registry (evidence: `backend/apps/runtime.py`)
- Instance runtime → Repository builds: ensures source (evidence: `backend/apps/runtime.py`)
- Instance runtime → Traffic routing: syncs routing (evidence: `backend/apps/runtime.py`)
- Instance runtime → Desired workloads: sets workloads (evidence: `backend/apps/runtime.py`)
- Node agent → Desired workloads: reconciles desired state
- Node agent → Docker containers: matches Docker state
- App visitor → Traffic routing: requests app
- Traffic routing → Instance runtime: routes to healthy instances
- Node registry → Private node mesh: joins private network
- Operator → Database routes: manages databases
- Database routes → Database engines: selects engine
- Database routes → Database containers: manages database
- Database containers → Database engines: uses engine configuration (evidence: `backend/dbs/docker.py`)
- Operator → Database backups: backs up data
- Operator → Cron scheduler: configures schedules
- Cron scheduler → Docker containers: runs job containers (evidence: `backend/cron/scheduler.py`)
- Operator → Metrics and logs: observes fleet
- Operator → Notifications: configures alerts
- Operator → Export and import: exports or imports
