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": "