---
title: "API Architecture and Request Boundaries | Agent Barn"
canonical: "https://agentbarn.dev/guides/api-architecture"
pubDate: "2026-08-25T00:00:00.000Z"
updatedDate: "2026-08-29T16:41:32.000Z"
author: Agent Barn
description: "Follow the route, service, repository, tenancy, transaction, migration, and dependency-injection conventions."
tags: [Engineering guide, Backend developers, Agent Barn]
categories: [Guides]
---

# API Architecture and Request Boundaries

The Product API and Ingest API have separate composition roots. Routes stay thin, services own policy and orchestration, repositories own persistence and visibility queries, and infrastructure adapters isolate external systems.

## Guide details

- Reference: GD-10
- Type: Engineering guide
- Audience: Backend developers

## Layering

The default dependency direction is routes to services to repositories to the shared PostgreSQL delegate, with services also calling external adapters. Routes authenticate, parse, delegate, and return. Services own business rules and error translation. Repositories own SQL and tenant-aware query composition.

## Tenancy and authorization

Organization routes include the Organization ID and require a real Membership. Platform routes use the Platform Administrator seam and resolve no active Organization. Agent visibility belongs in repository queries, while services check effective action Permissions. Runtime Ingest and Teams webhooks are separate non-user boundaries.

## Transactions and Domain Events

The shared delegate commits per operation, so several repository calls are not automatically atomic. Workflows requiring all-or-nothing behavior need an explicit transaction. Event-producing repositories commit business state, one Outbox Message, and intended Event Deliveries in one session.

## Startup, schema, and tests

Startup ensures the bootstrap Platform Administrator, built-in `aai-cli` Skills, and global Platform Template catalogue. Schema changes require `Alembic` migrations. Integration tests use the real `FastAPI` app and migrated PostgreSQL with additive dependency overrides.