Architecture

SupaCloud is a self-hosted orchestrator for AI coding agents. Three interfaces share one service layer.

Interfaces over one service layer

• Web UI + web terminal — SvelteKit (Svelte 5 runes), Paraglide i18n.
• Telegram / Discord bots — command handlers plus live-mode event streaming.
• Management API — M2M bearer-token auth, OpenAPI, desired-state seeding.

Below the interfaces sits the service layer (business logic), and below that the persistence layer (PostgreSQL via sqlx). Agents run in hardened Docker containers whose image is chosen per project language — a lean node image, or a full image carrying Python, Rust, .NET, Go and Java SDKs when those languages are detected (server/src/runtime/agent/stack.rs).

The dependency direction

The boundary rule is interface → service → persistence. Services never import from interfaces/. This is not a convention you have to remember by hand — it is enforced:

• Architecture tests assert the module boundaries (cargo test arch).
• Source files stay below 500 LOC.

Note

Because the service layer has no interface dependencies, the same business logic backs the web UI, the chat bots, and the Management API — which is why feature parity across surfaces is the default, not extra work.

Workflows

Beyond one-shot agent runs, SupaCloud composes multi-step workflows on a visual canvas — typed nodes (agent, gate, human approval, code, database, HTTP, notify, connector, and more) wired into a DAG.

Where to go deeper

The full design history is captured as Architecture Decision Records — the canonical Explanation corpus.