Architecture Overview

System context

        flowchart LR
  subgraph Humans
    ENG[Engineers]
    CUST[Organization staff]
  end
  IDP[OIDC identity provider]
  UI[Web UI<br/>Svelte]
  CORE[Core<br/>Go]
  KN[Knowledge<br/>Go]
  AG[Agents × N<br/>Go, in containers or VMs]
  GW[LLM Gateway<br/>Go]
  CDB[(Core DB<br/>SQLite)]
  KDB[(Knowledge DB<br/>SQLite)]
  CT[Sessions<br/>Claude Code, opencode]
  GIT[(Git platform<br/>GitHub, GitLab, Forgejo, …)]
  LLM[LLM providers]
  PROM[Prometheus / Grafana]

  ENG & CUST --> UI
  UI -- OIDC login --> IDP
  UI --> CORE
  UI --> KN
  CORE --- CDB
  KN --- KDB
  AG -- WebSocket: runs, events, input --> CORE
  AG -- processes --> CT
  CT -- tracker MCP --> CORE
  CT -- knowledge MCP --> KN
  CT -- LLM API --> GW --> LLM
  CT -- git push --> GIT
  CT -- clone --> GIT
  CORE -- forge API: PRs, state, merge --> GIT
  UI -. links .-> GIT
  CORE & GW & AG --> PROM

Principles

  • Orchestrate, don’t reimplement. Coding agents are external products, driven by Ballet’s agents through drivers.

  • The organization is the isolation boundary for data, credentials and knowledge — enforced server-side on every request.

  • Ballet checks, agents don’t self-report. Gates are evaluated by Ballet from observable facts (test results, knowledge entries, review decisions).

  • Humans grant autonomy. Agents may propose; only humans approve plans and raise a ticket’s autonomy.

  • Simple first. SQLite (rqlite later); Ballet manages no containers: a fleet of agents dials in — N containers on one host, a Kubernetes Deployment, or VMs (ADR-0025: Agent Fleet Runs Sessions as Processes).

Code organization

A monorepo with a Go workspace (go.work) and one module per deployable service, plus the Svelte UI:

kit/         Go module — shared operational plumbing (no domain logic)
core/        Go module — tenancy, tracker, scheduler, orchestrator,
             RBAC, skill registry, planner, tracker MCP
knowledge/   Go module — knowledge spaces, search, lineage, MCP
agent/       Go module — the agent: sessions as processes, runtime drivers
gateway/     Go module — LLM proxy and usage metering
web/         Svelte UI
docs/        this site

Inside each module, Clean Architecture boundaries apply: domain and application code do not depend on HTTP, SQL or MCP libraries.

See Components for responsibilities and Architecture Decisions for the decisions behind this shape.