Develop and extend
Concept Available

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.

For
Backend developers
On this page
  1. Layering
  2. Tenancy and authorization
  3. Transactions and Domain Events
  4. Startup, schema, and tests
01

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.

02

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.

03

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.

04

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.

Documentation