# iabtechlab/buyer-agent architecture

> Architecture diagram of the GitHub repository iabtechlab/buyer-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iabtechlab/buyer-agent
- Repository: https://github.com/iabtechlab/buyer-agent

## Overview

The repository implements an AI-assisted programmatic media buyer: users provide a campaign brief through an API, chat, or CLI, and the system discovers seller inventory, obtains quotes, negotiates and books deals. Its major capabilities also include media-kit browsing, buyer-identity pricing, optional SGP vendor gating, audience planning, reporting, pacing, and deal-library management. The graph reflects documented workflow and sampled imports/calls; several feature branches are represented at subsystem-directory level because their implementation was not sampled.

Main entry points: [`src/ad_buyer/orchestration/multi_seller.py`](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/orchestration/multi_seller.py) (Multi-seller buying), [`src/ad_buyer/flows/deal_booking_flow.py`](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/flows/deal_booking_flow.py) (Booking flow), [`src/ad_buyer/interfaces/api/main.py`](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/api/main.py) (REST API), [`src/ad_buyer/clients/deals_client.py`](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/deals_client.py) (Quotes and deals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_api["REST API<br/>[main.py]"]
  node_chat["Chat interface<br/>[main.py]"]
  node_cli["CLI<br/>[main.py]"]
end

subgraph group_workflow["Buying workflow"]
  node_flow["Booking flow"]
  node_orchestrator["Multi-seller buying<br/>[multi_seller.py]"]
  node_booking_service["Booking service<br/>[booking_service.py]"]
end

subgraph group_seller["Seller capabilities"]
  node_deals_client["Quotes and deals<br/>[deals_client.py]"]
  node_negotiation["Negotiation<br/>[client.py]"]
  node_opendirect["OpenDirect orders"]
  node_mediakit["Media-kit browsing<br/>[client.py]"]
  node_discovery["Inventory discovery"]
end

subgraph group_support["Planning and insights"]
  node_audience["Audience planning"]
  node_agents["Buying agents"]
  node_reporting["Campaign reporting"]
  node_pacing["Campaign pacing<br/>[engine.py]"]
  node_deal_library["Deal library"]
  node_sgp["Vendor approval gate<br/>[sgp_client.py]"]
end

subgraph group_platform["Shared platform"]
  node_identity["Buyer identity"]
  node_storage[("Deal state<br/>[deal_store.py]")]
  node_events["Event bus<br/>[bus.py]"]
  node_contracts["Wire-contract mapping"]
end

node_buyer(("Buyer"))
node_seller{{"Seller agents"}}

node_buyer -->|"submits brief"| node_api
node_buyer -->|"requests buying"| node_chat
node_buyer -->|"runs workflow"| node_cli
node_api -->|"starts booking"| node_booking_service
node_chat -->|"requests quotes"| node_orchestrator
node_cli -->|"starts flow"| node_flow
node_booking_service -->|"delegates booking"| node_flow
node_flow -->|"executes buying"| node_orchestrator
node_flow -->|"books orders"| node_opendirect
node_orchestrator -->|"requests quotes"| node_deals_client
node_orchestrator -->|"negotiates deals"| node_negotiation
node_orchestrator -->|"books orders"| node_opendirect
node_deals_client -->|"calls deal API"| node_seller
node_negotiation -->|"negotiates prices"| node_seller
node_opendirect -->|"sends orders"| node_seller
node_discovery -->|"browses kits"| node_mediakit
node_mediakit -->|"fetches packages"| node_seller
node_orchestrator -->|"checks approval"| node_sgp
node_orchestrator -->|"persists deal state"| node_storage
node_deals_client -->|"updates deal state"| node_storage
node_deals_client -->|"maps quote payloads"| node_contracts
node_opendirect -->|"maps wire data"| node_contracts
node_flow -->|"emits lifecycle events"| node_events
node_api -->|"serves reports"| node_reporting
node_flow -->|"coordinates specialists"| node_agents
node_agents -.->|"plans audiences"| node_audience
node_api -->|"checks operator access"| node_identity
node_pacing -->|"publishes lifecycle events"| node_events

click node_api "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/api/main.py"
click node_chat "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/chat/main.py"
click node_cli "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/cli/main.py"
click node_flow "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/flows/deal_booking_flow.py"
click node_orchestrator "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/orchestration/multi_seller.py"
click node_booking_service "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/services/booking_service.py"
click node_deals_client "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/deals_client.py"
click node_negotiation "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/negotiation/client.py"
click node_opendirect "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/opendirect_client.py"
click node_mediakit "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/media_kit/client.py"
click node_discovery "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/services/discovery_service.py"
click node_audience "https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/pipelines"
click node_agents "https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/agents"
click node_reporting "https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/reporting"
click node_pacing "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/pacing/engine.py"
click node_deal_library "https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/tools/deal_library"
click node_sgp "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/sgp_client.py"
click node_identity "https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/auth"
click node_storage "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/storage/deal_store.py"
click node_events "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/events/bus.py"
click node_contracts "https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/contract_mappers.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_chat,node_cli toneBlue
class node_flow,node_orchestrator,node_booking_service toneAmber
class node_deals_client,node_negotiation,node_opendirect,node_mediakit,node_discovery toneMint
class node_audience,node_agents,node_reporting,node_pacing,node_deal_library,node_sgp toneRose
class node_identity,node_storage,node_events,node_contracts,node_buyer,node_seller toneIndigo
```

## Components

### User interfaces

- [REST API](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/api/main.py): `src/ad_buyer/interfaces/api/main.py`
- [Chat interface](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/chat/main.py): `src/ad_buyer/interfaces/chat/main.py`
- [CLI](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/interfaces/cli/main.py): `src/ad_buyer/interfaces/cli/main.py`

### Buying workflow

- [Booking flow](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/flows/deal_booking_flow.py): `src/ad_buyer/flows/deal_booking_flow.py`
- [Multi-seller buying](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/orchestration/multi_seller.py): `src/ad_buyer/orchestration/multi_seller.py`
- [Booking service](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/services/booking_service.py): `src/ad_buyer/services/booking_service.py`

### Seller capabilities

- [Quotes and deals](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/deals_client.py): `src/ad_buyer/clients/deals_client.py`
- [Negotiation](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/negotiation/client.py): `src/ad_buyer/negotiation/client.py`
- [OpenDirect orders](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/opendirect_client.py): `src/ad_buyer/clients/opendirect_client.py`
- [Media-kit browsing](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/media_kit/client.py): `src/ad_buyer/media_kit/client.py`
- [Inventory discovery](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/services/discovery_service.py): `src/ad_buyer/services/discovery_service.py`

### Planning and insights

- [Audience planning](https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/pipelines): `src/ad_buyer/pipelines`
- [Buying agents](https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/agents): `src/ad_buyer/agents`
- [Campaign reporting](https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/reporting): `src/ad_buyer/reporting`
- [Campaign pacing](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/pacing/engine.py): `src/ad_buyer/pacing/engine.py`
- [Deal library](https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/tools/deal_library): `src/ad_buyer/tools/deal_library`
- [Vendor approval gate](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/sgp_client.py): `src/ad_buyer/clients/sgp_client.py`

### Shared platform

- [Buyer identity](https://github.com/iabtechlab/buyer-agent/tree/main/src/ad_buyer/auth): `src/ad_buyer/auth`
- [Deal state](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/storage/deal_store.py): `src/ad_buyer/storage/deal_store.py`
- [Event bus](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/events/bus.py): `src/ad_buyer/events/bus.py`
- [Wire-contract mapping](https://github.com/iabtechlab/buyer-agent/blob/main/src/ad_buyer/clients/contract_mappers.py): `src/ad_buyer/clients/contract_mappers.py`

### Other components

- **Buyer**
- **Seller agents**

## Connections

- Buyer → REST API: submits brief (evidence: `README.md`)
- Buyer → Chat interface: requests buying (evidence: `README.md`)
- Buyer → CLI: runs workflow (evidence: `README.md`)
- REST API → Booking service: starts booking (evidence: `src/ad_buyer/interfaces/api/main.py`)
- Chat interface → Multi-seller buying: requests quotes (evidence: `src/ad_buyer/interfaces/chat/main.py`)
- CLI → Booking flow: starts flow (evidence: `src/ad_buyer/interfaces/cli/main.py`)
- Booking service → Booking flow: delegates booking (evidence: `src/ad_buyer/services/booking_service.py`)
- Booking flow → Multi-seller buying: executes buying (evidence: `src/ad_buyer/flows/deal_booking_flow.py`)
- Booking flow → OpenDirect orders: books orders (evidence: `src/ad_buyer/flows/deal_booking_flow.py`)
- Multi-seller buying → Quotes and deals: requests quotes (evidence: `src/ad_buyer/orchestration/multi_seller.py`)
- Multi-seller buying → Negotiation: negotiates deals (evidence: `src/ad_buyer/orchestration/multi_seller.py`)
- Multi-seller buying → OpenDirect orders: books orders (evidence: `src/ad_buyer/orchestration/multi_seller.py`)
- Quotes and deals → Seller agents: calls deal API (evidence: `README.md`)
- Negotiation → Seller agents: negotiates prices (evidence: `README.md`)
- OpenDirect orders → Seller agents: sends orders (evidence: `README.md`)
- Inventory discovery → Media-kit browsing: browses kits (evidence: `src/ad_buyer/services/discovery_service.py`)
- Media-kit browsing → Seller agents: fetches packages (evidence: `src/ad_buyer/media_kit/client.py`)
- Multi-seller buying → Vendor approval gate: checks approval (evidence: `src/ad_buyer/orchestration/multi_seller.py`)
- Multi-seller buying → Deal state: persists deal state (evidence: `src/ad_buyer/flows/deal_booking_flow.py`)
- Quotes and deals → Deal state: updates deal state (evidence: `src/ad_buyer/clients/deals_client.py`)
- Quotes and deals → Wire-contract mapping: maps quote payloads (evidence: `src/ad_buyer/clients/deals_client.py`)
- OpenDirect orders → Wire-contract mapping: maps wire data (evidence: `src/ad_buyer/clients/opendirect_client.py`)
- Booking flow → Event bus: emits lifecycle events (evidence: `src/ad_buyer/flows/deal_booking_flow.py`)
- REST API → Campaign reporting: serves reports (evidence: `src/ad_buyer/interfaces/api/main.py`)
- Booking flow → Buying agents: coordinates specialists (evidence: `src/ad_buyer/flows/deal_booking_flow.py`)
- Buying agents → Audience planning: plans audiences
- REST API → Buyer identity: checks operator access (evidence: `src/ad_buyer/interfaces/api/main.py`)
- Campaign pacing → Event bus: publishes lifecycle events (evidence: `src/ad_buyer/pacing/engine.py`)
