Develop and extend
Concept Available

How Agent Barn Fits Together

Start here to understand where work belongs. Agent Barn separates product requests, runtime telemetry, domain events, and deployment concerns while keeping the Agent as the central operational aggregate.

For
New contributors
On this page
  1. Four operational areas
  2. The Agent is the orchestration boundary
  3. Keep event types separate
  4. Choose the right source before editing
01

Four operational areas

The repository is organized around the API, authenticated web app, agent runtimes, and deployment system. Product routes live under /api/v1, while runtime telemetry enters through a separately served /ingest/v1 application.

  1. 01.1

    API: authorization, orchestration, persistence, and runtime control.

  2. 01.2

    Web app: organization-scoped product experiences and Platform View.

  3. 01.3

    Runtimes: Hermes and OpenClaw execute rendered agent configuration.

  4. 01.4

    Deployment: Helm, Helmfile, workflows, databases, LiteLLM, and monitoring.

02

The Agent is the orchestration boundary

An Agent ties together one Organization, an exact Template version, explicit Skills, encrypted credentials, a chat Platform, a Runtime, Kubernetes resources, Telemetry, and LiteLLM cost identity. Cross-domain workflows belong in services rather than routes or repositories.

03

Keep event types separate

Runtime Telemetry Events become Conversation Messages and Tool Calls. Internal Domain Events record typed business facts through the transactional outbox. Costs come from LiteLLM reports. These streams have different authentication, persistence, and retention rules and must not be conflated.

04

Choose the right source before editing

Use feature guides for current product behavior, architecture guides for system boundaries, ADRs for consequential rationale, and changelogs for multi-ticket delivery history. The issue tracker and the platform-management plan describe work that is not necessarily shipped.

Documentation