ADR-0002: Go Services and a Svelte Web UI

Status:

Accepted

Date:

2026-10-01

Context

Ballet consists of several backend services (Core, Knowledge, Runner, LLM Gateway) that do network I/O, manage containers and processes, and stream logs, plus a rich supervision UI (board, Gantt, live runs, chat).

Decision

  • Backend services are written in Go (1.27), organized as a monorepo with one Go module per deployable service, joined by a go.work workspace.

  • The web UI is a Svelte single-page application (SvelteKit in static / SPA mode), built with Bun, served by Core or a static host.

Alternatives Considered

Single Go module

Advantages:

  • Simplest dependency management.

Disadvantages:

  • Services share one dependency graph; Knowledge would transitively see container and Docker dependencies; module boundaries do not enforce service boundaries.

React for the UI

Advantages:

  • Larger ecosystem (e.g. Gantt components).

Disadvantages:

  • More boilerplate; project owner prefers Svelte.

Decision Criteria

Fit for concurrent I/O and container control, operational simplicity (static binaries), boundary enforcement, team preference.

Rationale

Go’s standard library, concurrency model and container ecosystem fit the Runner and gateway well and produce single static binaries. Per-service modules make the Knowledge/Core separation physical.

Consequences

Positive

  • Simple deployment; strong service boundaries.

Negative

  • Shared types between services need a deliberate home (API contracts), not ad-hoc cross-module imports.

Risks

  • A Gantt component may need to be built rather than adopted in Svelte.

Follow-up

References