# alexanderminko/ssp-ming-exchange architecture

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

- Interactive diagram: https://gitdiagram.com/alexanderminko/ssp-ming-exchange
- Repository: https://github.com/alexanderminko/ssp-ming-exchange

## Overview

This is an OpenRTB supply-side ad exchange. An incoming bid request is admitted using supply configuration and request validation, fanned out concurrently to demand bidders, evaluated in an auction, and returned as a bid or no-bid response. The orchestrator also records metrics and auction events. The graph preserves the documented serving stages and major model, cache, and telemetry areas; links for unsampled components are limited to relationships shown by the source index or orchestrator excerpt.

Main entry points: [`src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java) (RTB Orchestrator), [`src/main/java/com/ming/sspexchange/service/demand/BidderService.java`](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/demand/BidderService.java) (Bidder Fan-out), [`src/main/java/com/ming/sspexchange/service/auction/AuctionService.java`](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/AuctionService.java) (Auction), [`src/main/java/com/ming/sspexchange/api/BidController.java`](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/api/BidController.java) (Bid API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["Request Serving"]
  node_bid_api["Bid API<br/>[BidController.java]"]
  node_orchestrator["RTB Orchestrator"]
  node_context["Request Context"]
  node_response_mapper["Response Mapper"]
end

subgraph group_supply["Supply Configuration"]
  node_supply_resolver["Supply Resolver"]
  node_request_validation["Request Validation"]
  node_supply_cache["Supply Partner Cache"]
  node_supply_repository["Supply Repository"]
end

subgraph group_demand["Demand And Auction"]
  node_bidder_cache["Bidder Cache<br/>[BidderCache.java]"]
  node_bidder_repository["Bidder Repository"]
  node_bidder_service["Bidder Fan-out<br/>[BidderService.java]"]
  node_bid_results["Bidder Results"]
  node_auction["Auction"]
  node_bid_validation["Bid Validation"]
  node_winning_bid["Winning Bid<br/>[WinningBid.java]"]
end

subgraph group_models["Exchange Models"]
  node_supply_models["Supply Models"]
  node_bidder_model["Bidder Model<br/>[Bidder.java]"]
  node_openrtb["OpenRTB Models"]
end

subgraph group_telemetry["Metrics And Events"]
  node_metrics["Exchange Metrics"]
  node_event_mapper["Auction Event Mapper"]
  node_event_logger["Auction Event Logger"]
end

node_ssp(("Supply Partner"))
node_dsp(("Demand Bidders"))

node_ssp -->|"submits request"| node_bid_api
node_bid_api -->|"invokes"| node_orchestrator
node_orchestrator -->|"resolves supply"| node_supply_resolver
node_orchestrator -->|"validates request"| node_request_validation
node_orchestrator -->|"loads bidders"| node_bidder_cache
node_orchestrator -->|"fans out"| node_bidder_service
node_bidder_service -->|"sends bid request"| node_dsp
node_bidder_service -->|"returns outcomes"| node_bid_results
node_orchestrator -->|"selects winner"| node_auction
node_auction -->|"filters bids"| node_bid_validation
node_auction -->|"produces winner"| node_winning_bid
node_orchestrator -->|"builds response"| node_response_mapper
node_response_mapper -->|"maps response"| node_openrtb
node_orchestrator -->|"tracks request state"| node_context
node_orchestrator -->|"records outcomes"| node_metrics
node_orchestrator -->|"maps auction event"| node_event_mapper
node_orchestrator -->|"logs event"| node_event_logger
node_event_mapper -->|"reads auction state"| node_context
node_bidder_cache -->|"loads bidders"| node_bidder_repository
node_supply_cache -->|"loads supply config"| node_supply_repository

click node_bid_api "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/api/BidController.java"
click node_orchestrator "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java"
click node_context "https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model"
click node_supply_resolver "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/supply/SupplyResolver.java"
click node_request_validation "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/supply/RequestValidationService.java"
click node_supply_cache "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/cache/SupplyPartnerCache.java"
click node_supply_repository "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/repository/SupplyPartnerRepository.java"
click node_supply_models "https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model/entity"
click node_bidder_cache "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/cache/BidderCache.java"
click node_bidder_repository "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/repository/BidderRepository.java"
click node_bidder_model "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/model/entity/Bidder.java"
click node_bidder_service "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/demand/BidderService.java"
click node_bid_results "https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/service/demand"
click node_auction "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/AuctionService.java"
click node_bid_validation "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/BidResponseValidationService.java"
click node_winning_bid "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/WinningBid.java"
click node_openrtb "https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model/openrtb"
click node_response_mapper "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/mapper/BidResponseMapper.java"
click node_metrics "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/metrics/ExchangeMetrics.java"
click node_event_mapper "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/mapper/AuctionEventMapper.java"
click node_event_logger "https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/event/AuctionEventLogger.java"

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_bid_api,node_orchestrator,node_context,node_response_mapper toneBlue
class node_supply_resolver,node_request_validation,node_supply_cache,node_supply_repository toneAmber
class node_bidder_cache,node_bidder_repository,node_bidder_service,node_bid_results,node_auction,node_bid_validation,node_winning_bid toneMint
class node_supply_models,node_bidder_model,node_openrtb toneRose
class node_metrics,node_event_mapper,node_event_logger,node_ssp,node_dsp toneIndigo
```

## Components

### Request Serving

- [Bid API](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/api/BidController.java): `src/main/java/com/ming/sspexchange/api/BidController.java`
- [RTB Orchestrator](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java): `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`
- [Request Context](https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model): `src/main/java/com/ming/sspexchange/model`
- [Response Mapper](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/mapper/BidResponseMapper.java): `src/main/java/com/ming/sspexchange/service/mapper/BidResponseMapper.java`

### Supply Configuration

- [Supply Resolver](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/supply/SupplyResolver.java): `src/main/java/com/ming/sspexchange/service/supply/SupplyResolver.java`
- [Request Validation](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/supply/RequestValidationService.java): `src/main/java/com/ming/sspexchange/service/supply/RequestValidationService.java`
- [Supply Partner Cache](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/cache/SupplyPartnerCache.java): `src/main/java/com/ming/sspexchange/cache/SupplyPartnerCache.java`
- [Supply Repository](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/repository/SupplyPartnerRepository.java): `src/main/java/com/ming/sspexchange/repository/SupplyPartnerRepository.java`

### Demand And Auction

- [Bidder Cache](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/cache/BidderCache.java): `src/main/java/com/ming/sspexchange/cache/BidderCache.java`
- [Bidder Repository](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/repository/BidderRepository.java): `src/main/java/com/ming/sspexchange/repository/BidderRepository.java`
- [Bidder Fan-out](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/demand/BidderService.java): `src/main/java/com/ming/sspexchange/service/demand/BidderService.java`
- [Bidder Results](https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/service/demand): `src/main/java/com/ming/sspexchange/service/demand`
- [Auction](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/AuctionService.java): `src/main/java/com/ming/sspexchange/service/auction/AuctionService.java`
- [Bid Validation](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/BidResponseValidationService.java): `src/main/java/com/ming/sspexchange/service/auction/BidResponseValidationService.java`
- [Winning Bid](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/auction/WinningBid.java): `src/main/java/com/ming/sspexchange/service/auction/WinningBid.java`

### Exchange Models

- [Supply Models](https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model/entity): `src/main/java/com/ming/sspexchange/model/entity`
- [Bidder Model](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/model/entity/Bidder.java): `src/main/java/com/ming/sspexchange/model/entity/Bidder.java`
- [OpenRTB Models](https://github.com/alexanderminko/ssp-ming-exchange/tree/main/src/main/java/com/ming/sspexchange/model/openrtb): `src/main/java/com/ming/sspexchange/model/openrtb`

### Metrics And Events

- [Exchange Metrics](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/metrics/ExchangeMetrics.java): `src/main/java/com/ming/sspexchange/service/metrics/ExchangeMetrics.java`
- [Auction Event Mapper](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/mapper/AuctionEventMapper.java): `src/main/java/com/ming/sspexchange/service/mapper/AuctionEventMapper.java`
- [Auction Event Logger](https://github.com/alexanderminko/ssp-ming-exchange/blob/main/src/main/java/com/ming/sspexchange/service/event/AuctionEventLogger.java): `src/main/java/com/ming/sspexchange/service/event/AuctionEventLogger.java`

### Other components

- **Supply Partner**
- **Demand Bidders**

## Connections

- Supply Partner → Bid API: submits request (evidence: `src/main/java/com/ming/sspexchange/api/BidController.java`)
- Bid API → RTB Orchestrator: invokes (evidence: `src/main/java/com/ming/sspexchange/api/BidController.java`)
- RTB Orchestrator → Supply Resolver: resolves supply (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Request Validation: validates request (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Bidder Cache: loads bidders (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Bidder Fan-out: fans out (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- Bidder Fan-out → Demand Bidders: sends bid request (evidence: `src/main/java/com/ming/sspexchange/service/demand/BidderService.java`)
- Bidder Fan-out → Bidder Results: returns outcomes (evidence: `src/main/java/com/ming/sspexchange/service/demand/BidderService.java`)
- RTB Orchestrator → Auction: selects winner (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- Auction → Bid Validation: filters bids (evidence: `src/main/java/com/ming/sspexchange/service/auction/AuctionService.java`)
- Auction → Winning Bid: produces winner (evidence: `src/main/java/com/ming/sspexchange/service/auction/AuctionService.java`)
- RTB Orchestrator → Response Mapper: builds response (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- Response Mapper → OpenRTB Models: maps response (evidence: `src/main/java/com/ming/sspexchange/service/mapper/BidResponseMapper.java`)
- RTB Orchestrator → Request Context: tracks request state (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Exchange Metrics: records outcomes (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Auction Event Mapper: maps auction event (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- RTB Orchestrator → Auction Event Logger: logs event (evidence: `src/main/java/com/ming/sspexchange/service/RtbOrchestrator.java`)
- Auction Event Mapper → Request Context: reads auction state (evidence: `src/main/java/com/ming/sspexchange/service/mapper/AuctionEventMapper.java`)
- Bidder Cache → Bidder Repository: loads bidders (evidence: `src/main/java/com/ming/sspexchange/cache/BidderCache.java`)
- Supply Partner Cache → Supply Repository: loads supply config (evidence: `src/main/java/com/ming/sspexchange/cache/SupplyPartnerCache.java`)
