Code Layout¶

Ballet is a monorepo. Backend services are separate Go modules joined by a Go workspace (ADR-0002: Go Services and a Svelte Web UI).

go.work            workspace: agent, core, gateway, kit, knowledge
core/              Core service module
gateway/           LLM gateway module
knowledge/         Knowledge service module
agent/             agent module (runs coding-agent sessions)
kit/               shared library module (no business logic)
web/               Svelte UI
docs/              this documentation (uv project)

Modules¶

agent, core, gateway, knowledge: One deployable service each, module path github.com/denyszorinets/ballet/<name>. A service module never imports another service module; services talk over their APIs.
kit: Operational plumbing shared by all services: configuration loading (kit/config), JSON logging (kit/logging), health and readiness (kit/health), graceful HTTP serving (kit/server), and the kit/service wiring that combines them with Prometheus metrics. kit contains no Ballet domain concepts.

Each service module declares replace github.com/denyszorinets/ballet/kit => ../kit so that it is also a valid standalone module. Verify standalone builds with:

cd core && GOWORK=off go build ./...

Inside a service¶

Packages follow Clean Architecture boundaries; dependencies point inward.

<service>/
  cmd/<service>/        entry point: configuration and wiring only
  internal/domain/      entities, value objects, invariants
  internal/app/         use cases; interfaces (ports) for what they need
  internal/infra/       adapters: SQLite, forge and LLM clients
  internal/transport/   REST, WebSocket and MCP handlers

domain imports nothing from app, infra or transport.
app depends on domain and on interfaces it defines itself.
infra and transport depend on app and domain.
Packages are created when there is code for them — no empty placeholders.

Services and ports¶

Service	Default address	Endpoints
core	`:8080`	`/healthz` `/readyz` `/metrics`
knowledge	`:8081`	`/healthz` `/readyz` `/metrics`
gateway	`:8082`	`/healthz` `/readyz` `/metrics`
agent	`:8083`	`/healthz` `/readyz` `/metrics`

Run a service locally:

go run ./core/cmd/core
curl localhost:8080/healthz

Each main.go defines a serviceConfig struct embedding service.Config and adds service-specific sections to it; see Configuration.