System Architecture

Overview

Understand where Agent Barn responsibilities live, how data crosses system boundaries, and which contracts must move together when you make a change.

Agent Barn manages Organization-owned Agents that run through Hermes or OpenClaw. An Agent may be headless, or it may own zero or many Communication Connections to Slack, Microsoft Teams, Telegram, or Discord, which are delivered through the Communications Gateway and its Platform Plugins.

At a high level:

The system separates:

• Human product requests
• Communication delivery
• Runtime Tool Call telemetry
• Internal business events
• Background delivery
• Provider cost reporting
• Dynamic Agent execution
• Platform deployment

These paths interact, but they do not share one event model, authentication mechanism, or source of truth. For the non-implementation summary of the same boundaries, see How Agent Barn fits together.

Four operational areas

Agent Barn is a monorepo with four major operational areas.

These are operational boundaries, not four independently owned domain services. API domains are modules inside one codebase, they share the Agent Barn application database, and they are composed into three separate HTTP applications.

System topology

Browser
  ↓
Next.js route or feature component
  ↓
Shared UI API client
  ↓
Product API /api/v1
  ↓
Route
  ↓
Service
  ↓
Repository
  ↓
Agent Barn PostgreSQL

Claimed Communication Delivery
  ↓
Hermes or OpenClaw
  ├── generated Template and policy
  ├── mounted Skills
  ├── decrypted Agent Secrets for tool Integrations
  ├── Agent workspace PVC
  └── model request → LiteLLM → OpenRouter

Platform provider
    ↓
Platform Plugin admission and normalization
    ↓
Communications Gateway
    ↓
Durable inbound Communication Delivery
    ├── canonical Conversation Message
    └── Runtime protocol claim
            ↓
       Hermes or OpenClaw

Hermes or OpenClaw
    ↓
Reply submitted against source Delivery
    ↓
Durable outbound Communication Delivery
    ↓
Source Communication Connection
    ↓
Platform Plugin
    ↓
Platform provider

Business mutation
  ↓ one PostgreSQL transaction
Business state + Outbox Message + Event Deliveries
  ↓ post-commit enqueue
Redis / Dramatiq
  ↓
Worker
  ↓
Event Handler
  ├── Security Audit projection
  └── Agent lifecycle email

Domain model

Organization is the ownership and tenancy root for user-facing resources.

Communication Connections are Agent subordinate resources for authorization, but they are not fields within the Agent aggregate. An Agent may have zero or many Connections, including several Connections for the same Platform.

Platform-owned resources

Some resources belong to Agent Barn itself rather than an Organization:

• Platform Privileges
• Predefined Platform Templates
• Platform Skills
• The Platform Plugin registry
• Platform-level Domain Events
• Platform oversight views
• Platform configuration and catalogue data

A new installation has no default Organization.

Application startup ensures:

• The bootstrap Platform Administrator
• RBAC seed data
• Bundled Platform Skills
• The predefined Platform Template catalogue

Platform Templates live in their own global table. Platform Skills use global ownership rather than being copied into every Organization.

Tenancy and authorization

Organization is the tenancy axis

Organization-owned routes normally include:

/api/v1/organizations/{organization_id}/...

Authentication produces a current user context. Organization-scoped services resolve a real persisted Membership for the requested Organization.

Platform Administrators do not receive implicit Organization Membership, an implicit Organization Role, or Agent access through their platform authority.

Authentication seams

Several distinct trust boundaries write to or read from the system:

Organization View and Platform View

Platform View has no Active Organization.

Platform oversight is explicitly allowlisted. It does not mean unrestricted access to Organization-owned credentials, configuration payloads, conversations, or raw telemetry.

Two role families

Organization Roles govern Organization-level capabilities:

• Organization Owner
• Organization Admin
• Organization Member

Agent Access Roles govern one Agent aggregate:

• Agent Viewer
• Agent Editor
• Agent Owner
• Organization-defined custom Agent Access Roles

Organization Owner and Admin receive implicit Agent Owner authority over Agents in their Organization. Members can receive Agent authority through:

• Explicit Agent Access
• Agent General Access
• Both, with additive Permissions

Creator fields are provenance. They are not permanent authorization exceptions.

Authorization placement

The architecture divides authorization responsibility:

• Repositories constrain visibility before count, pagination, and return.
• Services enforce action Permissions and lifecycle rules.
• Routes authenticate, parse, delegate, and return.
• The UI uses server-reported permitted actions to render controls.
• Every backend mutation independently reauthorizes the request.

Subordinate resources (Communication Connections, conversations, Tool Calls, activity, costs, logs, Secrets, Skills, and configuration) must be accessed through the same accessible-Agent boundary.

API architecture

The API has three separately composed FastAPI applications.

Product runs on port 8000, Ingest on 8001, and Communications on 8002. They use separate Prometheus registries and expose separate /metrics endpoints.

Provider webhooks belong to the Communications application and are Connection-scoped. There is no provider-specific webhook route on the Product API. For route registration and request contracts, see API architecture and request boundaries and Develop against the API.

Layering

The normal dependency direction is:

routes.py
   ↓
service.py
   ↓
repository.py
   ↓
PostgresRepositoryDelegate

Services may also call:

Kubernetes
LiteLLM
OpenRouter
Platform Plugin provider clients
Google OAuth
Cloudflare email
Cryptography
Other provider adapters

Routes

Routes should:

• Authenticate
• Parse path, query, and body data
• Resolve dependencies
• Delegate to a service
• Return the response

Routes should not own business workflows, SQL, or database transactions.

Services

Services own:

• Business rules
• Permission-sensitive behavior
• Lifecycle validation
• Error translation
• Cross-domain orchestration
• Calls to infrastructure adapters
• Post-commit Event Delivery enqueue

The Agent Service is intentionally broader than a CRUD service because starting an Agent crosses Templates, Skills, credentials, LiteLLM, Kubernetes, Ingest, and the Communications protocol.

Repositories

Repositories own:

• SQLModel and SQLAlchemy queries
• Tenant and visibility predicates
• Persistence
• Ordering and pagination
• Explicit transaction boundaries where required
• Atomic business mutation plus event staging

Infrastructure adapters

Infrastructure code isolates external concerns such as:

• PostgreSQL
• Kubernetes
• Redis transport
• LiteLLM
• OpenRouter
• Email
• Platform Plugin provider clients
• OAuth
• Encryption
• Time

Dependency injection is assembled through the API’s Injector modules.

Persistence and transactions

Application database

Agent Barn’s PostgreSQL database stores:

• Users and authentication state
• Organizations and Memberships
• Organization Agent Settings
• Roles and Agent Access
• Agents and lifecycle state
• Templates and versions
• Skills and Skill Versions
• Encrypted credentials
• Communication Connections and Communication Deliveries
• Conversation Messages
• Tool Calls
• Connection Journal entries
• Domain Events, Outbox Messages, and Event Deliveries
• Security Audit Records
• Persisted model-call cost records

Schema changes use Alembic migrations under:

api/migrations/versions/

Integration tests migrate a real PostgreSQL test database.

Separate databases

The deployment includes distinct databases:

Agent Barn Alembic migrations do not manage the LiteLLM or Firecrawl schemas.

Ordinary repository operations

Most repositories use a shared delegate that opens and commits a session per operation.

Therefore:

service call
  ├── repository operation A → commit
  └── repository operation B → commit

is not automatically one transaction.

If operation B fails, operation A may already be committed.

Explicit transactions

A workflow requiring all-or-nothing persistence needs a domain-specific repository transaction:

one SQLModel session
  ├── business mutation
  ├── Outbox Message
  ├── intended Event Deliveries
  └── one commit

The outbox stages rows inside the repository-owned session. It does not open or commit its own session.

Event and data flows

Several similarly named records have deliberately different roles.

Activity has two writers

The Communications Gateway writes canonical inbound and outbound Conversation Messages. Ingest writes Tool Call telemetry. Ingest does not write Conversation Messages.

Platform Provider
    ↓
Communications Gateway
    ↓
Conversation Message repository
    ↓
Product read API
    ↓
Activity UI

Agent Runtime
    ↓
Ingest API
    ↓
Tool Call repository
    ↓
Product read API
    ↓
Activity UI

• Product API provides authorized read routes for both.
• Conversation read paths preserve Connection identity.
• Tool Call correlation uses Runtime invocation identity.
• Neither Activity path writes Domain Events.
• Costs are not derived from Conversation or Tool Call rows.

Tool Call telemetry is authenticated with a per-start Ingest key rather than a human Membership, and it is not copied into the Domain Event outbox. See Activity, conversations, and runtime telemetry.

Domain Events

Domain Events are immutable typed business facts.

They include:

• Event ID
• Event name and schema version
• Event Scope
• Optional Organization ID
• Actor and Subject identities
• Correlation and optional causation identity
• Bounded, secret-safe payload

Domain Event payloads must reject credentials, secrets, unsupported values, sensitive key names, and unbounded content. Current events include Organization Agent Settings changes and Communications operational facts; this guide does not reproduce the complete event catalogue.

Event delivery

The business mutation, its Outbox Message, and its intended Event Deliveries commit in one domain-owned transaction. PostgreSQL is authoritative for:

• The event
• Publication intent
• Intended handlers
• Delivery status
• Attempts
• Current bounded error
• Dead-letter reason

Redis and Dramatiq provide low-latency transport, and reconciliation republishes eligible Event Deliveries.

The delivery guarantee is at least once. A worker can fail after a handler commits its side effect but before the delivery becomes SUCCEEDED, so handlers must be idempotent.

The system does not promise:

• Exactly-once side effects
• Strict global ordering
• A distributed transaction with external providers
• Automatic replay of dead-lettered deliveries

See Domain Events, outbox, and delivery.

Costs

Cost reports query persisted model-call records populated by synchronization and recovery. Organization cost reporting requires Organization membership authority; Platform Administrator privilege does not bypass that requirement. Separate Platform cost routes provide explicitly authorized cross-Organization oversight without granting Organization content access.

Costs are not calculated from:

• Conversation Messages
• Tool Calls
• Domain Events
• Kubernetes resource usage

Agent runtime architecture

The Agent domain orchestrates execution. It does not own communication delivery.

Runtime and Platform are separate

Hermes and OpenClaw consume one versioned, runtime-neutral Communications protocol, and Runtimes receive protocol credentials rather than provider credentials. Platform support is supplied by trusted, release-shipped Platform Plugins.

Generic Connection persistence, CRUD, schema-driven UI, durable delivery, and Runtime adapters do not branch by Platform. A new shipped Platform normally adds one Platform Plugin, its provider client, and focused tests rather than changes to every Runtime. For current per-Platform behavior, see Compare platform compatibility; for Runtime selection, see Choose an Agent runtime.

The Platform Plugin seam

Each plugin under api/domains/communications/plugins/ owns:

• Typed settings schema
• Typed credential schema
• Credential validation
• Credential identity and uniqueness rules
• Provider admission
• Payload normalization
• Optional inbound enrichment
• Supervised ingress or webhook verification
• Outbound sending
• Optional processing feedback
• Platform capabilities and setup guidance

The registry is code-owned and currently ships Slack, Microsoft Teams, Telegram, and Discord. Platform Plugins are not dynamically installed packages.

Ingress differs by Platform: Slack uses supervised Socket Mode, Telegram supervised polling, Discord a supervised Gateway session, and Microsoft Teams an authenticated provider webhook.

Agent start flow

Starting an Agent performs:

1. 1

   Load the Organization-owned Agent.

2. 2

   Authorize the lifecycle operation.

3. 3

   Resolve the pinned Template or Agent Template Override Version.

4. 4

   Render Template Markdown with Agent identity.

5. 5

   Resolve assigned Skill Version pins and eligible Platform Skills.

6. 6

   Decrypt Agent Secrets used by tool Integrations.

7. 7

   Select the Hermes or OpenClaw Runtime builder.

8. 8

   Materialize supported tool Integration configuration.

9. 9

   Append tool pointers and unconditional runtime behavior policies.

10. 10

    Generate fresh Ingest and Communications protocol credentials.

11. 11

    Build and apply the Kubernetes resources, including the runtime-neutral Communications adapter.

12. 12

    Mark the Agent RUNNING.

The generated resources include:

• ConfigMap
• Secret
• PVC
• Service
• Deployment

A failed credential check or Kubernetes start can place the Agent in ERROR, and a successful start clears the previous error. A provider-session or Connection failure changes Connection health instead of Agent lifecycle.

Desired and realized runtime state

Runtime configuration is generated at start. A running Agent does not automatically receive a new runtime image, Template selection, Skill assignment, tool Integration policy, or builder change.

Applying a runtime-relevant change requires a deliberate stop and start or Apply & Restart workflow. Connection settings and credentials are different: updating a Connection increments its revision and the Communications Gateway reconciles the provider session without restarting the Agent. See Runtime assembly and deployment.

Configuration and versioning

Templates

Templates are versioned Markdown configuration lineages.

An active Agent selects exactly one immutable Template source: a Platform Template Version, an Organization Template Version, or an Agent Template Override Version. The persistence constraint includes all three pin fields. Soft-deleted Agents can retain historical pins or be detached when an old shared lineage is purged; do not describe the active constraint as an unconditional two-foreign-key model.

• Predefined Templates are Platform Resources.
• Custom Templates belong to one Organization.
• Organization forks preserve source lineage.
• Published versions are immutable snapshots.
• Agents pin a specific version.
• Existing Agent pins do not automatically move to the latest version.

Agent Template Overrides

An Agent can have its own private Override lineage:

• One mutable draft
• Immutable published versions
• Explicit version selection
• Source-version provenance
• Apply & Restart for a running Agent

Publishing an Override does not automatically activate it.

Skills

Skills are packaged instructions or references that can be assigned to Agents and required by Templates. They exist at three ownership levels with additive visibility:

• Platform Skills
• Organization Skills
• Agent-private Skills

Published Skill Versions are immutable, each custom lineage keeps at most one mutable draft, and Agents and Template versions pin exact versions. Bundled Platform Skills are mounted under isolated aai-<integration>/SKILL.md roots.

Agent startup combines explicitly assigned Skill Version pins, Template-required Skill Versions, and eligible Platform Skills. Provider requirements are validated when configuring the Agent; changing a Skill’s provider metadata later does not retroactively revalidate every existing Agent. See Templates, versions, overrides, and Skills.

Organization Agent Settings

Model configuration resolves across two layers:

• Organization allowed_models bounds what the Organization may use.
• The Organization Agent Settings default model is nullable: when it is unset, Agents follow the platform default; when it is set, it becomes the Organization-owned default.
• An Agent inherits that default unless it carries an explicit override.

The effective model is resolved at start, so it can differ from the model a currently running Agent was started with.

Runtime snapshots

Agent startup materializes a snapshot of current configuration into Kubernetes.

This creates an intentional boundary:

Versioned source configuration
  ↓ explicit selection
Agent persisted configuration
  ↓ start or restart
Generated runtime resources

It prevents a new Template, Skill, tool Integration policy, or runtime-image release from silently changing a running Agent.

Web app architecture

The web app uses Next.js App Router with feature-oriented organization.

Provider hierarchy

The root application composes shared providers including:

• URL query-state adapter
• TanStack Query provider
• Tooltip provider
• Application provider
• User context
• Organization context

Public authentication routes bypass the protected user and Organization context.

Route ownership

App Router pages under ui/src/app/ are composition points.

Feature behavior belongs under:

ui/src/features/

Authentication behavior belongs under:

ui/src/auth/

Shared transport and query infrastructure belongs under:

ui/src/shared/

API client

Feature hooks use the shared API transport and centralized query-key infrastructure.

It owns:

• Authentication token attachment and refresh
• Cookie-bearing requests
• Request keys converted to snake_case
• Response keys converted to camelCase
• Structured ApiError
• Optional feature-local Zod response validation

UI components should not create unrelated transport clients for ordinary product requests.

Organization switching

The Active Organization comes from:

/dashboard/[orgId]

Platform View uses:

/dashboard/platform

The Organization provider removes known Organization-scoped query families during a genuine Organization switch so data from the previous Organization does not remain visible under the new URL.

Adding a new Organization-scoped query requires either:

• Including Organization identity in its query key, or
• Adding it to the Organization-switch eviction boundary

Agent log streaming

Agent logs are an exception to the ordinary API flow.

A dedicated Next.js route proxies backend server-sent events through a streaming response. The client log hook owns browser reconnection. This prevents ordinary proxy buffering and keeps the internal API hostname on the server.

Integrations and credentials

Agent Barn separates several credential classes.

Encryption boundary

Provider payloads are:

1. Validated against typed schemas.
2. Encrypted before persistence.
3. Validated again after decryption.
4. Returned through read APIs only as safe metadata.
5. Decrypted by the domain that owns them.

Credential plaintext is never returned by normal read APIs.

Runtime materialization

At start, Agent Barn can produce:

• aai-cli profiles and secret-store setup
• Google Workspace gog configuration
• Tool Integration environment variables
• Eligible Platform Skills
• Tool Integration policy appended to Agent configuration
• Firecrawl platform defaults or per-Agent overrides
• Ingest and Communications protocol credentials

Storage validation is only half of a tool Integration: Runtime support must also exist in the Runtime builders and their generated artifacts.

Deployment architecture

Helmfile deploys the platform into one Kubernetes namespace.

The general dependency order is:

PostgreSQL services and Redis
        ↓
LiteLLM and Firecrawl
        ↓
Agent Barn API hooks
        ↓
API, Communications, and worker workloads
        ↓
Agent Barn UI
        ↓
Monitoring

Service workloads

The API image is reused for:

• Product, Ingest, and Communications processes
• Worker deployment
• Reconciliation CronJob
• Alembic migration Job

These workloads run different commands but share application code and configuration contracts.

Provider webhook ingress reaches the Communications service, not the Product API. Runtime protocol traffic stays internal. Operational procedures belong to the deployment guides; see Runtime assembly and deployment.

Data and infrastructure responsibilities divide as follows.

Dynamic Agent workloads

Agent Deployments are not static entries in Helmfile. The API dynamically creates and removes them through the Kubernetes client.

Each running Agent owns its runtime resources while remaining part of the same agent-farm or agent-farm-staging namespace.

Environment isolation

The k3s testing deployments use:

agent-farm

and:

agent-farm-staging

Every release and Helmfile dependency uses the selected namespace. The API also receives that namespace so it creates Agent resources in the correct environment.

Observability

The Product API, Ingest, Communications, LiteLLM, and Agent runtimes expose Prometheus metrics.

The namespace-scoped monitoring stack contains:

• Prometheus
• Grafana
• Alertmanager
• kube-state-metrics

It observes:

• Product, Ingest, and Communications availability
• HTTP requests and errors
• Application database connectivity
• Connection status and delivery outcomes
• Agent health and ERROR state
• Agent restarts
• Tool Call outcomes
• LiteLLM availability and usage
• OpenRouter credit state

The Product API health endpoint proves application PostgreSQL connectivity. It does not prove Redis, Communications, workers, Event Deliveries, provider Connections, LiteLLM, Firecrawl, email, or external providers are healthy.

Application logs, Agent logs, the Connection Journal, Event Delivery state, Activity, Tool Calls, costs, and Prometheus metrics are complementary operational sources.

Where changes belong

Code map

Source map

Choose the authoritative document

Do not treat an implementation plan as proof that a feature is delivered.

Change-impact questions

Before changing a boundary, ask:

• Does it affect Organization tenancy?
• Does it expose an Agent or subordinate resource?
• Does it require a new Permission?
• Does it change the Agent start snapshot?
• Does it affect both Hermes and OpenClaw?
• Does it belong in a Platform Plugin rather than a Runtime?
• Does it change the Communications protocol version?
• Does it change encrypted credential compatibility?
• Does it change a persisted schema?
• Does it require an Alembic migration?
• Does it produce a Domain Event?
• Does the business mutation need one explicit transaction?
• Does it change Tool Call telemetry?
• Does it affect cost attribution?
• Does the UI need a Zod schema or query-cache update?
• Does the deployment or monitoring contract change?
• Do authoritative docs need to move with the code?

Architecture invariants

Keep these invariants intact unless the change deliberately revises the documented contract:

• Organization is the user-visible tenant boundary.
• Platform authority and Organization authority remain separate.
• Agent authorization covers the complete Agent aggregate, including subordinate Communication Connections.
• Routes remain thin.
• Services own orchestration.
• Repositories own persistence and tenant visibility.
• Infrastructure adapters own external systems.
• Runtime and Platform remain separate.
• Runtimes receive protocol credentials, not provider credentials.
• Communication Connections are Agent subordinate resources, not fields inside the Agent aggregate.
• The Communications Gateway owns canonical Conversation Message writes.
• Generated Runtime configuration changes only through deliberate lifecycle action, while Connection settings and credentials reconcile without restarting the Agent.
• Runtime telemetry remains separate from Domain Events.
• PostgreSQL remains authoritative for Domain Event delivery state.
• Event Handlers remain idempotent under at-least-once delivery.
• Cost reports read persisted model calls populated by synchronization and recovery.
• Secret plaintext is never returned through read APIs.
• Schema changes include Alembic migrations.
• API, UI, runtime, tests, deployment, and documentation move together when a contract crosses those boundaries.

Next steps

Continue with the API guide to understand route registration, request contracts, service orchestration, repository visibility, dependency injection, and integration patterns.

Web Chat ownership

The api/domains/web_chat/ domain owns dashboard chat requests, user-scoped thread history, and the authenticated SSE surface. It uses the Communications delivery pipeline and built-in Web Chat Connection. Reads require Agent activity permission; mutations require Agent update permission. This is distinct from external provider webhook authentication and runtime protocol credentials.

Dashboard Chat → Product API Web Chat domain → Communications delivery pipeline → built-in Web Chat Connection. See Dashboard Web Chat for the user workflow.