# iabtechlab/seller-agent architecture

> Architecture diagram of the GitHub repository iabtechlab/seller-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/seller-agent
- Repository: https://github.com/iabtechlab/seller-agent

## Overview

Seller Agent is a publisher/SSP platform for inventory discovery, tiered pricing, AI-assisted negotiation, deal booking and distribution. Buyers and operators enter through MCP, REST, A2A or chat; the platform exposes a tiered media kit, prices and negotiates proposals, then manages deal and order lifecycles and connects to ad servers, SSPs and buyer deal APIs. The README documents the overall architecture and integrations; sampled source confirms several service, engine and storage responsibilities, but not every runtime connection.

Main entry points: [`src/ad_seller/services/deal_service.py`](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/deal_service.py) (Deal lifecycle), [`src/ad_seller/services/catalog_service.py`](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/catalog_service.py) (Inventory catalog), [`src/ad_seller/interfaces/api/main.py`](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/api/main.py) (REST API), [`src/ad_seller/interfaces/mcp_server.py`](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/mcp_server.py) (MCP tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Access interfaces"]
  node_mcp["MCP tools<br/>[mcp_server.py]"]
  node_rest["REST API<br/>[main.py]"]
  node_chat["Buyer chat<br/>[main.py]"]
  node_a2a["A2A interface<br/>[a2a_client.py]"]
end

subgraph group_commercial["Inventory and commerce"]
  node_catalog["Inventory catalog<br/>[catalog_service.py]"]
  node_media["Tiered media kit"]
  node_pricing["Tiered pricing"]
  node_negotiation["Negotiation engine"]
  node_agents["Agent hierarchy"]
  node_identity["Buyer identity tiers<br/>[buyer_identity.py]"]
end

subgraph group_lifecycle["Deal operations"]
  node_deals["Deal lifecycle<br/>[deal_service.py]"]
  node_orders["Order management<br/>[order_service.py]"]
  node_approvals["Approval gates<br/>[approval.py]"]
  node_events["Event bus<br/>[bus.py]"]
end

subgraph group_connectors["Persistence and integrations"]
  node_storage[("Storage backend<br/>[base.py]")]
  node_adserver["Ad server adapters<br/>[ad_server_base.py]"]
  node_ssp["SSP connectors<br/>[ssp_base.py]"]
  node_sync["Buyer deal sync<br/>[deal_sync_base.py]"]
end

node_buyers(("Buyers and operators"))

node_buyers -->|"use tools"| node_mcp
node_buyers -->|"call endpoints"| node_rest
node_buyers -->|"start conversations"| node_chat
node_buyers -->|"send queries"| node_a2a
node_rest -->|"mounts protocol"| node_mcp
node_mcp -->|"manage inventory"| node_catalog
node_rest -->|"serves catalog"| node_catalog
node_chat -->|"reads products"| node_catalog
node_catalog -->|"exposes inventory"| node_media
node_media -->|"applies tier access"| node_pricing
node_identity -->|"sets buyer tier"| node_pricing
node_agents -->|"evaluates offers"| node_pricing
node_agents -->|"negotiate proposals"| node_negotiation
node_chat -->|"evaluates offers"| node_negotiation
node_negotiation -->|"gets tier price"| node_pricing
node_rest -->|"routes deal actions"| node_deals
node_mcp -->|"manages deals"| node_deals
node_deals -->|"books orders"| node_orders
node_deals -->|"requests approval"| node_approvals
node_approvals -->|"emits decisions"| node_events
node_deals -->|"publishes lifecycle"| node_events
node_catalog -->|"reads and writes"| node_storage
node_deals -->|"persists deals"| node_storage
node_deals -->|"activates deals"| node_adserver
node_deals -->|"distributes deals"| node_ssp
node_deals -->|"pushes to buyers"| node_sync

click node_mcp "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/mcp_server.py"
click node_rest "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/api/main.py"
click node_chat "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/chat/main.py"
click node_a2a "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/a2a_client.py"
click node_catalog "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/catalog_service.py"
click node_media "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/media_kit_service.py"
click node_pricing "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/pricing_rules_engine.py"
click node_negotiation "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/negotiation_engine.py"
click node_agents "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/agents/level1/inventory_manager.py"
click node_deals "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/deal_service.py"
click node_orders "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/order_service.py"
click node_approvals "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/events/approval.py"
click node_events "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/events/bus.py"
click node_storage "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/storage/base.py"
click node_adserver "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/ad_server_base.py"
click node_ssp "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/ssp_base.py"
click node_sync "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/deal_sync_base.py"
click node_identity "https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/models/buyer_identity.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_mcp,node_rest,node_chat,node_a2a toneBlue
class node_catalog,node_media,node_pricing,node_negotiation,node_agents,node_identity toneAmber
class node_deals,node_orders,node_approvals,node_events toneMint
class node_storage,node_adserver,node_ssp,node_sync toneRose
class node_buyers toneIndigo
```

## Components

### Access interfaces

- [MCP tools](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/mcp_server.py): `src/ad_seller/interfaces/mcp_server.py`
- [REST API](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/api/main.py): `src/ad_seller/interfaces/api/main.py`
- [Buyer chat](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/interfaces/chat/main.py): `src/ad_seller/interfaces/chat/main.py`
- [A2A interface](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/a2a_client.py): `src/ad_seller/clients/a2a_client.py`

### Inventory and commerce

- [Inventory catalog](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/catalog_service.py): `src/ad_seller/services/catalog_service.py`
- [Tiered media kit](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/media_kit_service.py): `src/ad_seller/engines/media_kit_service.py`
- [Tiered pricing](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/pricing_rules_engine.py): `src/ad_seller/engines/pricing_rules_engine.py`
- [Negotiation engine](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/engines/negotiation_engine.py): `src/ad_seller/engines/negotiation_engine.py`
- [Agent hierarchy](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/agents/level1/inventory_manager.py): `src/ad_seller/agents/level1/inventory_manager.py`
- [Buyer identity tiers](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/models/buyer_identity.py): `src/ad_seller/models/buyer_identity.py`

### Deal operations

- [Deal lifecycle](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/deal_service.py): `src/ad_seller/services/deal_service.py`
- [Order management](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/services/order_service.py): `src/ad_seller/services/order_service.py`
- [Approval gates](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/events/approval.py): `src/ad_seller/events/approval.py`
- [Event bus](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/events/bus.py): `src/ad_seller/events/bus.py`

### Persistence and integrations

- [Storage backend](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/storage/base.py): `src/ad_seller/storage/base.py`
- [Ad server adapters](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/ad_server_base.py): `src/ad_seller/clients/ad_server_base.py`
- [SSP connectors](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/ssp_base.py): `src/ad_seller/clients/ssp_base.py`
- [Buyer deal sync](https://github.com/iabtechlab/seller-agent/blob/main/src/ad_seller/clients/deal_sync_base.py): `src/ad_seller/clients/deal_sync_base.py`

### Other components

- **Buyers and operators**

## Connections

- Buyers and operators → MCP tools: use tools (evidence: `README.md`)
- Buyers and operators → REST API: call endpoints (evidence: `README.md`)
- Buyers and operators → Buyer chat: start conversations (evidence: `README.md`)
- Buyers and operators → A2A interface: send queries (evidence: `README.md`)
- REST API → MCP tools: mounts protocol (evidence: `src/ad_seller/interfaces/api/main.py`)
- MCP tools → Inventory catalog: manage inventory (evidence: `src/ad_seller/interfaces/mcp_server.py`)
- REST API → Inventory catalog: serves catalog (evidence: `src/ad_seller/interfaces/api/main.py`)
- Buyer chat → Inventory catalog: reads products (evidence: `src/ad_seller/interfaces/chat/main.py`)
- Inventory catalog → Tiered media kit: exposes inventory (evidence: `README.md`)
- Tiered media kit → Tiered pricing: applies tier access (evidence: `src/ad_seller/engines/media_kit_service.py`)
- Buyer identity tiers → Tiered pricing: sets buyer tier (evidence: `src/ad_seller/engines/pricing_rules_engine.py`)
- Agent hierarchy → Tiered pricing: evaluates offers (evidence: `README.md`)
- Agent hierarchy → Negotiation engine: negotiate proposals (evidence: `README.md`)
- Buyer chat → Negotiation engine: evaluates offers (evidence: `src/ad_seller/interfaces/chat/main.py`)
- Negotiation engine → Tiered pricing: gets tier price (evidence: `src/ad_seller/engines/negotiation_engine.py`)
- REST API → Deal lifecycle: routes deal actions (evidence: `src/ad_seller/interfaces/api/main.py`)
- MCP tools → Deal lifecycle: manages deals (evidence: `src/ad_seller/interfaces/mcp_server.py`)
- Deal lifecycle → Order management: books orders (evidence: `README.md`)
- Deal lifecycle → Approval gates: requests approval (evidence: `README.md`)
- Approval gates → Event bus: emits decisions (evidence: `src/ad_seller/events/approval.py`)
- Deal lifecycle → Event bus: publishes lifecycle (evidence: `src/ad_seller/services/deal_service.py`)
- Inventory catalog → Storage backend: reads and writes (evidence: `src/ad_seller/services/catalog_service.py`)
- Deal lifecycle → Storage backend: persists deals (evidence: `src/ad_seller/services/deal_service.py`)
- Deal lifecycle → Ad server adapters: activates deals (evidence: `README.md`)
- Deal lifecycle → SSP connectors: distributes deals (evidence: `README.md`)
- Deal lifecycle → Buyer deal sync: pushes to buyers (evidence: `README.md`)
