From 8e518c7d4700810d3b6ff949e58e91d7580b8549 Mon Sep 17 00:00:00 2001 From: Christian Date: Wed, 21 Jan 2026 09:41:36 -0600 Subject: [PATCH 1/5] update trusted-server.toml --- AUCTION_ORCHESTRATION_FLOW.md | 242 ++++++++++++++++++++++++++++++++++ trusted-server.toml | 10 +- 2 files changed, 248 insertions(+), 4 deletions(-) create mode 100644 AUCTION_ORCHESTRATION_FLOW.md diff --git a/AUCTION_ORCHESTRATION_FLOW.md b/AUCTION_ORCHESTRATION_FLOW.md new file mode 100644 index 0000000..4e7dda6 --- /dev/null +++ b/AUCTION_ORCHESTRATION_FLOW.md @@ -0,0 +1,242 @@ +# 🎯 Auction Orchestration Flow + +## 🔄 System Flow Diagram + +```mermaid +%%{init: { + "theme": "base", + "themeVariables": { + "background": "#ffffff", + "primaryColor": "#dbeafe", + "primaryTextColor": "#1e3a8a", + "primaryBorderColor": "#2563eb", + "lineColor": "#334155", + "secondaryColor": "#fef3c7", + "tertiaryColor": "#d1fae5", + "actorBkg": "#eff6ff", + "actorBorderColor": "#3b82f6", + "actorTextColor": "#1e40af", + "actorLineColor": "#64748b", + "signalColor": "#1e293b", + "signalTextColor": "#0f172a", + "labelBoxBkgColor": "#f1f5f9", + "labelBoxBorderColor": "#cbd5e1", + "labelTextColor": "#1e293b", + "loopTextColor": "#1e293b", + "noteBkgColor": "#fef3c7", + "noteBorderColor": "#d97706", + "noteTextColor": "#78350f", + "activationBorderColor": "#059669", + "activationBkgColor": "#d1fae5", + "sequenceNumberColor": "#0f172a" + }, + "themeCSS": ".sequenceNumber{font-size:26px!important;font-weight:900!important;fill:#ffffff!important;paint-order:stroke fill;stroke:#1e293b;stroke-width:1px;} .sequenceNumber circle{r:32px!important;stroke-width:3px!important;stroke:#1e293b!important;fill:#2563eb!important;} .mermaid svg{background:#ffffff!important;border-radius:8px;box-shadow:0 2px 4px rgba(0,0,0,0.06);} .actor{font-weight:600!important;} .messageText{font-weight:600!important;font-size:16px!important;} .activation0{stroke-width:3px!important;} .messageLine0,.messageLine1{stroke-width:3px!important;} .messageText tspan{font-size:16px!important;} path.messageLine0,path.messageLine1{stroke-width:3px!important;} marker#arrowhead path,marker#crosshead path{stroke-width:2px!important;}" +}}%% +sequenceDiagram + autonumber + + participant Client as 🌐 Browser/TSJS + participant TS as 🛡️ Trusted Server + participant Orch as 🎯 Orchestrator + participant APS as 📦 APS Provider + participant Prebid as 🎰 Prebid Provider + participant Med as ⚖️ AdServer Mediator + participant Mock as 🎭 Mocktioneer + + %% === Auction Request Initiation === + rect rgb(243,244,246) + Note over Client,Mock: 🚀 Auction Request Initiation + activate Client + activate TS + Client->>TS: POST /auction
AdRequest with adUnits[] + Note right of Client: { "adUnits": [{ "code": "header-banner",
"mediaTypes": { "banner": { "sizes": [[728,90]] } } }] } + + TS->>TS: 🔧 Parse AdRequest
🔄 Transform to AuctionRequest
🆔 Generate user IDs
📊 Build context + deactivate Client + deactivate TS + end + + %% === Orchestrator Strategy Detection === + rect rgb(239,246,255) + Note over Client,Mock: 🧠 Auction Strategy Detection + activate TS + activate Orch + TS->>Orch: orchestrator.run_auction() + Orch->>Orch: 🔍 Detect strategy
mediator? parallel_mediation : parallel_only + deactivate TS + + Note over Orch: Strategy determined by config:
[auction]
mediator = "adserver_mock" → parallel_mediation
No mediator → parallel_only + end + + %% === Parallel Provider Execution === + rect rgb(243,232,255) + Note over Client,Mock: 🔄 Parallel Provider Execution + activate APS + activate Prebid + activate Mock + + par Parallel Provider Calls + Orch->>APS: POST /e/dtb/bid
APS TAM format + Note right of Orch: { "pubId": "5128",
"slots": [{ "slotID": "header-banner",
"sizes": [[728,90]] }] } + + APS->>Mock: APS TAM request + Mock-->>APS: APS bid response
(encoded prices, no creative) + Note right of Mock: { "contextual": { "slots": [{
"slotID": "header-banner",
"amznbid": "Mi41MA==", // "2.50"
"fif": "1" }] } } + + APS-->>Orch: AuctionResponse
(APS bids) + and + Orch->>Prebid: POST /openrtb2/auction
OpenRTB 2.x format + Note right of Orch: { "id": "request",
"imp": [{ "id": "header-banner",
"banner": { "w": 728, "h": 90 } }] } + + Prebid->>Mock: OpenRTB request + Mock-->>Prebid: OpenRTB response
(clear prices, with creative) + Note right of Mock: { "seatbid": [{ "seat": "prebid",
"bid": [{ "price": 2.00, "adm": "..." }] }] } + + Prebid-->>Orch: AuctionResponse
(Prebid bids) + end + + Note over Orch: 📊 Collected bids from all providers
APS: encoded prices, no creative
Prebid: clear prices, with creative + deactivate Mock + deactivate APS + deactivate Prebid + end + + %% === Winner Selection Strategy === + alt Mediator Configured (parallel_mediation) + rect rgb(236,253,245) + Note over Client,Mock: ⚖️ Mediation Flow + activate Med + Orch->>Med: POST /adserver/mediate
All bids for final selection + Note right of Orch: { "id": "auction-123",
"imp": [...],
"ext": { "bidder_responses": [
{ "bidder": "amazon-aps",
"bids": [{ "encoded_price": "Mi41MA==" }] },
{ "bidder": "prebid",
"bids": [{ "price": 2.00 }] }] } } + + Med->>Med: 🔓 Decode APS encoded prices
📏 Apply floor prices
🏆 Select highest CPM per slot + Note right of Med: Base64 decode: "Mi41MA==" → "2.50"
Winner: APS at $2.50 vs Prebid at $2.00 + + Med-->>Orch: OpenRTB response with winners + Note right of Med: { "seatbid": [{ "seat": "amazon-aps",
"bid": [{ "price": 2.50, "impid": "header-banner" }] }] } + deactivate Med + end + else No Mediator (parallel_only) + rect rgb(253,243,235) + Note over Client,Mock: 🏆 Direct Winner Selection + Orch->>Orch: 📏 Compare clear prices only
⚠️ Skip APS (encoded prices)
🏆 Select highest CPM + Note right of Orch: APS bids skipped (encoded prices)
Winner: Prebid at $2.00 (only clear price) + + Note over Orch: 📝 Results: Limited winner selection
Cannot compare encoded APS prices
Prebid wins by default + end + end + + %% === Response Assembly === + rect rgb(243,244,246) + Note over Client,Mock: 📦 Response Assembly + activate TS + activate Client + Orch->>Orch: 🔄 Transform to OpenRTB response
🖼️ Generate iframe creatives
🔏 Rewrite creative URLs
📊 Add orchestrator metadata + + Orch-->>TS: OpenRTB BidResponse + Note right of Orch: { "id": "auction-response",
"seatbid": [{ "seat": "amazon-aps",
"bid": [{ "price": 2.50,
"adm": "