adserver-dashboard 1.0.0

package/PRD.md

@@ -0,0 +1,3373 @@
+# Influence - DOOH Adserver Platform
+## Product Requirements Document
+
+**Version**: 2.1  
+**Last Updated**: February 2026  
+**Created by**: Product Team
+
+---
+
+## Table of Contents
+
+1. [Glossary](#1-glossary)
+2. [The Advertising Hierarchy](#2-the-advertising-hierarchy)
+3. [Dashboard](#3-dashboard)
+   - 3.1 [Time Period Selector](#31-time-period-selector)
+   - 3.2 [Active Deals Card](#32-active-deals-card)
+   - 3.3 [Total Impressions Card](#33-total-impressions-card)
+   - 3.4 [Revenue Card](#34-revenue-card)
+   - 3.5 [Fill Rate Card](#35-fill-rate-card)
+   - 3.6 [Active Line Items Card](#36-active-line-items-card)
+   - 3.7 [Total Creatives Card](#37-total-creatives-card)
+   - 3.8 [Pending Approvals Card](#38-pending-approvals-card)
+   - 3.9 [Impression Delivery Card](#39-impression-delivery-card)
+   - 3.10 [Inventory Availability Card](#310-inventory-availability-card)
+   - 3.11 [Recent Deals Card](#311-recent-deals-card)
+   - 3.12 [Line Item Delivery Status Card](#312-line-item-delivery-status-card)
+   - 3.13 [Creative Status Card](#313-creative-status-card)
+4. [Deals](#4-deals)
+   - 4.1 [Deal Types](#41-deal-types)
+   - 4.2 [Deals Page Layout](#42-deals-page-layout)
+   - 4.3 [Creating a Deal](#43-creating-a-deal)
+   - 4.4 [Deal Form Fields](#44-deal-form-fields)
+   - 4.5 [Deal Status Lifecycle](#45-deal-status-lifecycle)
+   - 4.6 [Editing and Deleting Deals](#46-editing-and-deleting-deals)
+   - 4.7 [Deal Detail Page](#47-deal-detail-page)
+   - 4.8 [Mandatory Fields](#48-mandatory-fields)
+   - 4.9 [Deal Form Insights and Quick Tips](#49-deal-form-insights-and-quick-tips)
+   - 4.10 [VAST Tag Distribution](#410-vast-tag-distribution)
+      - 4.10.1 [Overview](#4101-overview)
+      - 4.10.2 [VAST Endpoint URL Structure](#4102-vast-endpoint-url-structure)
+      - 4.10.3 [Distribution Tab on Deal Detail Page](#4103-distribution-tab-on-deal-detail-page)
+      - 4.10.4 [CMS Compatibility Options](#4104-cms-compatibility-options)
+      - 4.10.5 [HTML File Generation](#4105-html-file-generation)
+      - 4.10.6 [ZIP Package Generation](#4106-zip-package-generation)
+      - 4.10.7 [Distribution Workflow by Deal Type](#4107-distribution-workflow-by-deal-type)
+      - 4.10.8 [API Endpoints](#4108-api-endpoints)
+5. [Line Items](#5-line-items)
+   - 5.1 [What Line Items Control](#51-what-line-items-control)
+   - 5.2 [Creating a Line Item](#52-creating-a-line-item)
+   - 5.3 [Line Item Forecasting Panel](#53-line-item-forecasting-panel)
+   - 5.4 [Delivery Tracking](#54-delivery-tracking)
+   - 5.5 [Pausing and Resuming](#55-pausing-and-resuming)
+   - 5.6 [Form Insights and Quick Tips](#56-form-insights-and-quick-tips)
+6. [Traffic Allocation](#6-traffic-allocation)
+   - 6.1 [Basic Concept](#61-basic-concept)
+   - 6.2 [Normalization Logic](#62-normalization-logic)
+   - 6.3 [Priority as Tiebreaker](#63-priority-as-tiebreaker)
+   - 6.4 [Worked Examples](#64-worked-examples)
+7. [Content Hub](#7-content-hub)
+   - 7.1 [Overview](#71-content-hub-overview)
+   - 7.2 [Creative Types](#72-creative-types)
+   - 7.3 [Status Workflow](#73-status-workflow)
+   - 7.4 [Folder Organization](#74-folder-organization)
+   - 7.5 [Preview and Approval](#75-preview-and-approval)
+   - 7.6 [Creative Assignment](#76-creative-assignment)
+      - 7.6.1 [Line Item Creatives Page](#761-line-item-creatives-page)
+      - 7.6.2 [Edit Creative Assignment Page](#762-edit-creative-assignment-page)
+      - 7.6.3 [Assign Creative Page](#763-assign-creative-page)
+   - 7.7 [Tier 2 Approval Workflow](#77-tier-2-approval-workflow)
+8. [Signals](#8-signals-conditional-automation)
+   - 8.1 [Overview](#81-signals-overview)
+   - 8.2 [Signal Types](#82-signal-types)
+   - 8.3 [Signal Rules](#83-signal-rules)
+   - 8.4 [Forecasting Visualizations](#84-forecasting-visualizations)
+   - 8.5 [Signal-Line Item Integration](#85-signal-line-item-integration)
+   - 8.6 [UI/UX](#86-signals-ui-ux)
+   - 8.7 [Quick Tips Panel](#87-quick-tips-panel)
+9. [Ad Serving Process](#9-ad-serving-process)
+    - 9.1 [The Two Delivery Channels](#91-the-two-delivery-channels)
+    - 9.2 [Channel A — Decision Engine](#92-channel-a--decision-engine)
+      - 9.2.1 [Why the Decision Engine Exists](#921-why-the-decision-engine-exists)
+      - 9.2.2 [How the Decision Engine Works](#922-how-the-decision-engine-works)
+      - 9.2.3 [The Hybrid Manifest Approach](#923-the-hybrid-manifest-approach)
+      - 9.2.4 [Decision Engine Scenarios](#924-decision-engine-scenarios)
+      - 9.2.5 [Decision Engine API](#925-decision-engine-api)
+      - 9.2.6 [Decision Engine Example](#926-decision-engine-example-a-day-in-the-life-of-screen-scr-4421)
+    - 9.3 [Channel B — VAST Tag Distribution](#93-channel-b--vast-tag-distribution)
+      - 9.3.1 [VAST Distribution Example](#931-vast-distribution-example-campaign-on-a-partner-network)
+    - 9.4 [Channel Comparison](#94-channel-comparison-when-ads-reach-screens)
+    - 9.5 [Legacy Ad Serving Decision Flow](#95-legacy-ad-serving-decision-flow)
+10. [External System Integrations](#10-external-system-integrations)
+    - 10.1 [Integration Overview](#101-integration-overview)
+    - 10.2 [Planner Integration](#102-planner-integration)
+    - 10.3 [Activate Integration](#103-activate-integration)
+    - 10.4 [Booking Engine Integration](#104-booking-engine-integration)
+    - 10.5 [Admin Console Integration](#105-admin-console-integration)
+    - 10.6 [Decision Engine Integration](#106-decision-engine-integration)
+11. [Inventory Integration](#11-inventory-integration)
+    - 11.1 [External Product Overview](#111-external-product-overview)
+    - 11.2 [Accessing Inventory Management](#112-accessing-inventory-management)
+12. [Integrations](#12-integrations)
+    - 12.1 [Built-in SSP](#121-built-in-ssp)
+    - 12.2 [External SSP Partners](#122-external-ssp-partners)
+    - 12.3 [DSP Partners](#123-dsp-partners)
+13. [User Interface Navigation](#13-user-interface-navigation)
+    - 13.1 [Application Layout](#131-application-layout)
+    - 13.2 [Sidebar Navigation](#132-sidebar-navigation)
+    - 13.3 [Navigation Flow](#133-navigation-flow)
+    - 13.4 [Header Controls](#134-header-controls)
+    - 13.5 [User Menu](#135-user-menu)
+    - 13.6 [Theme Settings](#136-theme-settings)
+    - 13.7 [Form Pages](#137-form-pages)
+    - 13.8 [Filter Drawer](#138-filter-drawer)
+    - 13.9 [Inline Filtering and Sorting](#139-inline-filtering-and-sorting)
+    - 13.10 [Dialog Usage](#1310-dialog-usage)
+14. [History Logs and Audit Trail](#14-history-logs-and-audit-trail)
+    - 14.1 [Overview](#141-overview)
+    - 14.2 [What Gets Tracked](#142-what-gets-tracked)
+    - 14.3 [Created By Attribution](#143-created-by-attribution)
+    - 14.4 [View History Button](#144-view-history-button)
+    - 14.5 [API Endpoints](#145-api-endpoints)
+15. [Recommendation Engine Integration](#15-recommendation-engine-integration)
+    - 15.1 [Overview](#151-overview)
+    - 15.2 [Campaign Goals](#152-campaign-goals)
+    - 15.3 [Scoring System (8 Factors)](#153-scoring-system-8-factors)
+    - 15.4 [Recommendation Panel](#154-recommendation-panel-line-item-form)
+    - 15.5 [Score Breakdown Tooltip](#155-score-breakdown-tooltip)
+    - 15.6 [Auto-Optimize Feature](#156-auto-optimize-feature)
+    - 15.7 [API Endpoints](#157-api-endpoints)
+16. [Proof of Play (PoP) System](#16-proof-of-play-pop-system)
+    - 16.1 [Overview](#161-overview)
+    - 16.2 [PoP Record Sources](#162-pop-record-sources)
+    - 16.3 [PoP Record Display](#163-pop-record-display)
+    - 16.4 [Status Workflow](#164-status-workflow)
+17. [Playlog Upload System](#17-playlog-upload-system)
+    - 17.1 [Upload Interface](#171-upload-interface)
+    - 17.2 [CSV Template](#172-csv-template)
+    - 17.3 [File Processing](#173-file-processing)
+18. [Configuration Menu](#18-configuration-menu)
+    - 18.1 [Menu Items](#181-menu-items)
+    - 18.2 [Signals](#182-signals)
+    - 18.3 [Custom POIs](#183-custom-pois)
+    - 18.4 [Tags](#184-tags)
+19. [Settings Module](#19-settings-module)
+    - 19.1 [General Settings](#191-general-settings)
+    - 19.2 [Notifications](#192-notifications)
+    - 19.3 [Traffic Control](#193-traffic-control)
+    - 19.4 [Forecasting Defaults](#194-forecasting-defaults)
+    - 19.5 [Optimization Preferences](#195-optimization-preferences)
+    - 19.6 [Recommendation Weights](#196-recommendation-weights)
+    - 19.7 [Workflow Settings](#197-workflow-settings)
+    - 19.8 [Terminology](#198-terminology)
+    - 19.9 [Themes & Branding](#199-themes--branding)
+    - 19.10 [Inventory Whitelisting](#1910-inventory-whitelisting)
+    - 19.11 [API Settings](#1911-api-settings)
+
+---
+
+## 1. Glossary
+
+| Term | Definition |
+|------|------------|
+| CPM | Cost Per Mille. The price an advertiser pays for one thousand impressions. If CPM is $10, the advertiser pays $10 for every 1,000 times their ad is shown. |
+| CPS | Cost Per Second. The price based on ad duration. Used for video creatives where pricing is calculated per second of airtime. |
+| DOOH | Digital Out-of-Home. Advertising displayed on digital screens in public locations like malls, airports, bus stops, and billboards. |
+| DSP | Demand-Side Platform. A system that advertisers use to buy advertising inventory through automated auctions. |
+| Fill Rate | The percentage of available advertising slots that were actually sold. If a screen could show 1000 ads but only 800 were sold, the fill rate is 80%. |
+| Impression | One instance of an advertisement being displayed on a screen. If an ad plays 500 times across all screens, that is 500 impressions. |
+| Line Item | The execution unit that specifies which ad to show, where to show it, how much to pay, and tracks delivery progress. |
+| SSP | Supply-Side Platform. A system that screen owners use to sell their advertising inventory to advertisers. |
+| Traffic Allocation | A percentage that controls how much of the available advertising opportunity a particular line item should receive. |
+| Booking Engine | A separate service that manages inventory reservations and campaign scheduling across the Influence ecosystem. |
+| Planner | An external platform for campaign planning that sends Traditional deals to Influence for execution. |
+| Activate | An external platform for programmatic RFP workflows that sends Programmatic deals to Influence for execution. |
+| Decision Engine (DE) | A real-time microservice that sits between the player and the ad server. It decides which ad should play on a given screen at a given moment, based on pacing, priority, CPM, and other factors. Replaces static round-robin rotation with intelligent ad selection. |
+| Manifest | A pre-computed sequence of ads that the Decision Engine sends to a player for a specific time window (typically 15-30 minutes). The player follows the manifest order and fires tracking heartbeats after each play. |
+| Heartbeat | A lightweight tracking signal sent by the player to the Decision Engine after each ad plays. Updates real-time counters (impressions, spend) in Redis so the next manifest is based on accurate delivery data. |
+| Pacing | The rate at which a campaign delivers impressions relative to its goal and remaining flight time. A campaign "behind on pacing" has delivered fewer impressions than expected at this point in its schedule. |
+| SOV | Share of Voice. The percentage of total ad slots on a screen (or set of screens) allocated to a specific deal. A 20% SOV guarantee means the deal must occupy at least 20% of all available slots. |
+| VAST | Video Ad Serving Template. An industry-standard XML-based protocol that enables ad servers to communicate with video players. A VAST endpoint is a URL that players call to receive ad instructions (which creative to show, tracking pixels, etc.). |
+| VAST Tag | A URL pointing to a VAST endpoint. Media owners schedule VAST tags on their CMS/players so the player can request and display ads from the ad server. |
+
+---
+
+## 2. The Advertising Hierarchy
+
+Understanding the data hierarchy is essential before using any feature in Influence. The system organizes advertising into four levels, where each level contains one or more items from the level below it.
+
+### Hierarchy Diagram
+
+The diagram below shows the four-level hierarchy from Advertiser down to Creative Assignment.
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198310)**
+
+<p align="center"><em>Figure 1: Advertising Hierarchy</em></p>
+
+**Color Legend:**
+
+| Level | Color | Entity |
+|:-----:|:-----:|:-------|
+| 1 | Gray | Advertiser |
+| 2 | Light Blue | Deal |
+| 3 | Orange | Line Item |
+| 4 | Purple | Creative Assignment |
+
+**Level 1: Advertiser**
+
+An advertiser is the company or brand paying for the advertising. For example, "Coca-Cola" or "Nike" would be advertisers. One advertiser can have multiple deals running at the same time. The advertiser record stores contact information and is used for billing and reporting purposes.
+
+**Level 2: Deal**
+
+A deal represents one advertising initiative with a specific goal, containing all the commercial and operational configuration needed for execution. For example, Coca-Cola might run a "Summer Refresh" deal and a "Holiday Season" deal simultaneously.
+
+The deal is where you define:
+- The type of buying: Traditional (guaranteed delivery at fixed prices) or Programmatic (real-time bidding through auctions)
+- SSP and Media Owner configurations
+- Budget, goals, and flight dates
+- DSP configuration for programmatic deals
+- Geographic targeting (countries)
+
+**Level 3: Line Item**
+
+The line item is where advertising execution configuration happens. While the deal level provides commercial and operational structure, the line item specifies targeting criteria, pricing, delivery goals, and tracks how many impressions have been delivered.
+
+A single deal might have multiple line items for different targeting requirements. For example:
+- Line Item 1: "15-second brand video" targeting mall entrance screens
+- Line Item 2: "10-second product promo" targeting food court screens
+
+Line items inherit geographic constraints from their parent deal (they can only target locations within the deal's selected countries).
+
+**Level 4: Creative Assignment**
+
+The creative assignment is the junction between line items and creatives. This level exists because the same creative may be used across multiple line items with different scheduling, rules, and approval status. Creative assignments control when and how each creative is delivered within a line item.
+
+Each creative assignment record contains:
+- The linked creative from the Content Hub
+- Start and end times for the assignment
+- A schedule matrix defining which hours and days the creative should play
+- A rule defining the rotation behavior (default, exclusive, etc.)
+- Ad play count tracking
+- Tier 2 approval status (pending, approved, rejected, changes requested)
+
+This separation allows fine-grained control over creative delivery. For example, a line item might have:
+- Creative Assignment 1: "Hero Video" playing all day on weekdays
+- Creative Assignment 2: "Promo Video" playing mornings only on weekends
+
+---
+
+## 3. Dashboard
+
+The Dashboard is the first screen users see when they log in. Its purpose is to answer the question: "How is my advertising business doing right now?" The page is organized into distinct rows that present information at progressively deeper levels of detail, with a time period selector in the page header for controlling the date range of displayed metrics.
+
+The page header contains the title and description on the left, with a time period selector on the right side allowing users to customize the date range for metrics. The first row contains four metric cards that provide high-level key performance indicators related to deals, impressions, revenue, and fill rate. The second row contains four additional metric cards focused on operational metrics: total screens, active line items, total creatives, and pending approvals. The third row displays two cards side by side: an Impression Delivery card occupying four-sevenths of the width, and an Inventory Availability card occupying the remaining three-sevenths. The fourth row contains three equal-width cards showing Recent Deals, Line Item Delivery Status, and Creative Status.
+
+### 3.1 Time Period Selector
+
+The time period selector appears in the page header, positioned on the right side opposite the page title. This control determines the date range used for calculating time-dependent metrics such as impressions, revenue, and trend comparisons. The selector affects the subtitle text displayed on metric cards, dynamically updating to reflect the chosen period.
+
+**The selector provides four options via a dropdown menu:**
+
+**Last 30 days:** The default selection. Metrics are calculated from the current date going back 30 calendar days. The metric card subtitles display "Last 30 days" to indicate this range.
+
+**Last 60 days:** Extends the calculation window to 60 calendar days prior to the current date. The metric card subtitles update to display "Last 60 days".
+
+**Last 90 days:** Provides a quarterly view by calculating metrics over the previous 90 calendar days. The metric card subtitles display "Last 90 days".
+
+**Custom dates:** When selected, a secondary control appears—a date range picker button showing the currently selected date range (for example, "Jan 01 - Jan 25"). Clicking this button opens a calendar popup.
+
+**Custom Date Range Picker Behavior:**
+
+When the user selects "Custom dates" from the dropdown, a popover button appears to the right of the dropdown. This button displays a calendar icon followed by the selected date range in abbreviated format (for example, "Jan 01 - Jan 25"). If no dates have been selected yet, the button displays "Pick dates".
+
+Clicking the date range button opens a calendar popup anchored to the right side of the button. The calendar displays two months side by side, allowing users to view and select dates spanning adjacent months without navigation. Users select a date range by clicking the start date, then clicking the end date. Selected dates are highlighted, and the range between them is indicated with a visual connection. Once both a start and end date are selected, the calendar popup automatically closes, and the metrics recalculate based on the custom range.
+
+**Implementation details:** The dropdown uses the data-testid attribute `select-time-period` for automated testing. The custom date range button uses `button-custom-dates`. The calendar component supports keyboard navigation and follows accessibility best practices for date selection.
+
+### 3.2 Active Deals Card
+
+This card displays two numbers arranged vertically. The large, prominent number shows the count of deals that are currently running. A deal is counted as active if today's date falls between its start and end dates, and the deal has not been paused or cancelled.
+
+The smaller subtitle text below reads "of X total" where X represents the total count of all deals in the system, regardless of status. This provides essential context for interpretation. Seeing "8" with "of 12 total" tells the operator that they have 4 deals that are either scheduled for the future, completed, or paused.
+
+**Visual elements:** The card displays a megaphone icon in the top right corner to visually represent deals. A trend arrow appears next to the main value, indicating whether the active deal count has increased or decreased compared to the previous period. The arrow points upward with a positive percentage when deals have increased, or downward with a negative percentage when deals have decreased.
+
+**Where the data comes from:** The system counts all deals where status equals "active" and today's date is within the start and end dates. The total deals count includes all deals regardless of status.
+
+### 3.3 Total Impressions Card
+
+This card displays the total count of advertisement plays across all screens during the selected time period. The number is formatted for readability using abbreviations: values over one million appear with an "M" suffix (for example, "5.2M"), values over one thousand appear with a "K" suffix (for example, "245K"), and smaller values appear as regular numbers.
+
+The subtitle text reads "Last 30 days" to indicate the time period being measured. Every time a screen finishes showing an advertisement and logs that play back to the system, the impression count increases by one.
+
+**Visual elements:** The card displays an eye icon in the top right corner to visually represent impressions (the act of viewing). A trend arrow indicates whether impressions have increased or decreased compared to the previous 30-day period.
+
+**Where the data comes from:** The system sums the "delivered impressions" field from the dashboard metrics API. Each line item tracks its own delivery count, and this card presents the aggregate total.
+
+**Why it matters:** Impressions are the fundamental currency of advertising. Advertisers buy impressions, and this card shows how many were delivered. Comparing impressions across time periods reveals whether the advertising business is growing or shrinking.
+
+### 3.4 Revenue Card
+
+This card shows the total money earned from advertising during the selected time period. The figure is displayed in formatted currency (for example, "$45,230" or "$195,000"). The subtitle text reads "Last 30 days" to indicate the measurement period.
+
+**Visual elements:** The card displays a dollar sign icon in the top right corner. A trend arrow indicates whether revenue has increased or decreased compared to the previous period.
+
+**Where the data comes from:** Revenue comes from two sources, which the system adds together.
+
+For traditional deals, revenue is calculated as:
+> (Delivered Impressions ÷ 1,000) × CPM
+
+For example, if a line item delivered 50,000 impressions at a CPM of $12, the revenue is (50,000 ÷ 1,000) × $12 = $600.
+
+For programmatic deals, revenue comes from the actual clearing prices of won auctions. Each time the platform wins a bid, the bid amount is added to revenue. These amounts vary based on real-time demand.
+
+### 3.5 Fill Rate Card
+
+Fill rate answers the question: "Of all the advertising opportunities we had available, what percentage did we actually sell?" The main value is displayed as a percentage (for example, "87%").
+
+The subtitle shows the average CPM in currency format (for example, "Avg CPM: $8.50"). This provides additional context about the quality of demand.
+
+**Visual elements:** The card displays an upward trending line icon in the top right corner. A trend arrow indicates whether fill rate has improved or declined compared to the previous period.
+
+**The calculation works like this:**
+
+First, the system calculates available impressions. This is based on how many screens are active, how many hours each screen operates per day, and how long each advertising slot lasts. For example, if a screen operates 12 hours per day with 15-second ad slots, the screen can show approximately 2,880 ads per day (12 × 60 × 60 ÷ 15).
+
+Second, filled impressions are the sum of all delivered impressions.
+
+Third, the fill rate is:
+> (Filled Impressions ÷ Available Impressions) × 100
+
+**Average CPM calculation:**
+> (Total Revenue ÷ Total Impressions) × 1,000
+
+Average CPM indicates the quality of demand. Higher average CPM means advertisers are paying more per impression, suggesting premium inventory or strong demand.
+
+### 3.6 Active Line Items Card
+
+This card monitors the operational pulse of the advertising delivery engine by tracking active line items. Line items are the execution units that directly control which advertisements are shown, making their count a critical operational metric.
+
+The main value displays the count of line items currently in active delivery. A line item is counted as active when its status is set to active, the current date falls within its flight dates, and it has remaining budget or impression goals to deliver.
+
+The subtitle text reads "of X total" where X represents the complete count of all line items across all deals. This ratio reveals the proportion of configured line items that are actually in delivery at any given moment.
+
+**Visual elements:** The card displays a layers icon in the top right corner, representing the stacked nature of line items within the deal hierarchy. A trend arrow indicates the direction of change compared to the previous measurement period.
+
+**Where the data comes from:** The `activeLineItems` field contains line items meeting the active criteria. The `totalLineItems` field provides the complete count. Both values are retrieved from the dashboard metrics API.
+
+**Why it matters:** Active line items represent the current delivery capacity of the platform. A low ratio of active to total line items might indicate underutilized inventory or deals that have completed. A high ratio indicates strong utilization of configured advertising.
+
+### 3.7 Total Creatives Card
+
+This card provides a comprehensive view of creative assets in the Content Hub. Creatives are the actual advertisement content—videos, images, and HTML5 assets—that are ultimately displayed on screens.
+
+The main value shows the total count of creative assets that have been uploaded to the Content Hub. This includes all creatives regardless of their approval status, assignment status, or active use.
+
+The subtitle displays "X approved" where X is the count of creatives that have passed the approval workflow and are eligible for assignment to line items. Only approved creatives can be assigned to line items and delivered to screens.
+
+**Visual elements:** The card displays an image icon in the top right corner to represent creative content. A trend arrow indicates whether the total creative count has grown or decreased compared to the previous period.
+
+**Where the data comes from:** The `totalCreatives` field provides the complete count of all creative assets. The `acceptedCreatives` field (displayed as "approved" in the subtitle) counts creatives with an approved status. Both values come from the dashboard metrics API.
+
+**Operational significance:** The ratio of approved to total creatives indicates workflow efficiency. If many creatives remain unapproved, there may be a bottleneck in the approval process that could impact deal launch schedules.
+
+### 3.8 Pending Approvals Card
+
+This card highlights creatives that are waiting for review. The main value shows the count of creatives in the Content Hub with a status of "Pending" or "In Review".
+
+The subtitle provides context by showing how many approvals were completed in the current period, enabling users to gauge approval throughput.
+
+**Visual elements:** The card displays a clock icon to represent waiting status. A badge may indicate urgency if many approvals are pending.
+
+**Where the data comes from:** The system counts creatives where the approval status is not yet finalized.
+
+### 3.9 Impression Delivery Card
+
+This card provides a visual representation of impression delivery over time. It displays a line or area chart showing daily impression counts for the selected time period.
+
+**Chart Features:**
+- X-axis: Days within the selected time period
+- Y-axis: Impression count
+- Hover tooltips showing exact values for each day
+- Trend line indicating overall delivery trajectory
+
+**Time Period Options:**
+- **Today:** Shows hourly breakdown of impressions delivered today
+- **This Week:** Shows daily breakdown for the current week
+- **This Month:** Shows daily breakdown for the current month
+- **Custom:** Shows daily breakdown for the selected custom range
+
+The chart helps identify delivery patterns, peak days, and potential issues if delivery drops unexpectedly.
+
+### 3.10 Inventory Availability Card
+
+This card provides visibility into inventory booking status across the screen network. It displays the distribution of screens by their availability for new bookings.
+
+**Availability Categories:**
+- **Available:** Screens with open inventory that can accept new bookings
+- **Partially Available:** Screens with some booked time slots but remaining availability
+- **Sold Out:** Screens that are fully booked with no available inventory
+
+Each category is displayed with a colored indicator (green for available, amber for partially available, red for sold out) and a count of screens in that state.
+
+A summary footer shows the total screen count and an availability percentage bar indicating what proportion of inventory is available for booking. This helps operators quickly assess inventory capacity and identify when more screens may be needed to meet demand.
+
+### 3.11 Recent Deals Card
+
+This card shows the most recently created or modified deals, allowing users to quickly access their current work.
+
+The card displays up to 5 deals in a compact list format, showing:
+- Deal name (clickable, navigates to Deal Detail)
+- Deal type (Traditional/Programmatic badge)
+- Status badge (Active/Paused)
+- Last modified date
+
+Deals are sorted by last modified date, with the most recent at the top.
+
+### 3.12 Line Item Delivery Status Card
+
+This card provides visibility into the delivery pacing of active line items, helping users identify campaigns that need attention.
+
+**Pacing Status Categories:**
+- **On Track:** Line items delivering within 10% of expected pace (green indicator)
+- **Ahead:** Line items delivering more than 10% above expected pace (blue indicator)
+- **Behind:** Line items delivering 10-25% below expected pace (amber indicator)
+- **At Risk:** Line items delivering more than 25% below expected pace (red indicator)
+
+Each category displays a count of line items in that pacing state. A summary footer shows the total count of active line items being tracked.
+
+This helps operators quickly identify campaigns that may need optimization or budget adjustments to meet their delivery goals.
+
+### 3.13 Creative Status Card
+
+This card provides a breakdown of creatives by their approval status, visualized as a donut chart or stacked bar.
+
+**Status Categories:**
+- **Accepted:** Creatives that have passed Tier 1 approval
+- **Pending:** Creatives awaiting review
+- **Inadequate:** Creatives that failed review
+- **In Review:** Creatives currently being reviewed
+
+The visualization helps identify bottlenecks in the creative approval process.
+
+---
+
+## 4. Deals
+
+Deals are the commercial containers that define advertising initiatives. Each deal represents an agreement with an advertiser and contains all the configuration needed for execution, including SSP/DSP settings, media owner selection, budget, goals, and flight dates.
+
+### 4.1 Deal Types
+
+The Deal Type field is set directly on the deal and determines the commercial arrangement:
+
+**Traditional**
+
+Traditional deals represent direct sales with media owners where pricing is negotiated upfront before deal execution. These deals are best suited for brand campaigns requiring guaranteed placements with fixed pricing certainty. Inventory is reserved directly with the media owner without programmatic intermediaries.
+
+**Programmatic**
+
+When Programmatic is selected, the user must choose a specific programmatic deal type:
+
+| Deal Type | Description |
+|-----------|-------------|
+| Programmatic Guaranteed (PG) | Combines automation benefits of programmatic technology with security of reserved inventory. Fixed pricing through DSP ensures predictable costs while leveraging programmatic infrastructure. |
+| Preferred Deal | Enables automated bidding through DSP platforms with real-time pricing dynamics. Provides first-look access to inventory at negotiated floor prices before open auction. |
+| Private Marketplace (PMP) | Provides access to curated inventory through invitation-only auctions. Multiple buyer seats can participate, enabling controlled competition among selected demand partners. |
+| Always On | Supports continuous deals with flexible delivery targets and sophisticated budget pacing controls. Designed for ongoing advertising presence rather than fixed-flight campaigns. |
+| Open Auction | Real-time bidding environment where any qualified buyer can compete for impressions at market-determined prices. |
+
+### 4.2 Deals Page Layout
+
+The Deals page presents a comprehensive list of all deals in the system. Understanding the page layout helps users navigate efficiently.
+
+**Search Functionality**: At the top of the page, a search input allows users to quickly find deals by typing the deal name or ID. The list filters in real-time as the user types, showing only deals matching the search term.
+
+**Listing Order**: Deals are sorted by last edited date, with the most recently edited deals appearing first. This ensures that active work is always visible at the top.
+
+**Filter Drawer**: Clicking the "Filters" button in the page header opens a drawer panel from the right side of the screen. This drawer contains filtering options using searchable dropdown selectors:
+- **Status**: Multi-select dropdown to filter by Active or Paused status
+- **Deal Type**: Multi-select dropdown to filter by Traditional or Programmatic types (PG, Preferred Deal, PMP, Always On)
+- **Goal Type**: Multi-select dropdown to filter by goal type (Impressions, Reach, Share of Voice, Carbon Emission, Ad Plays)
+- **SSP Partner**: Multi-select dropdown to filter by SSP partner (defaults to Influence built-in SSP)
+- **Media Owner**: Searchable dropdown to filter by media owner company
+- **Client Type**: Multi-select dropdown to filter by client type (Agency, Direct Advertiser). Both options are unselected by default (showing all deals). When "Agency" is selected, the Agency filter becomes visible
+- **Agency**: Searchable dropdown to filter by agency name (only visible when "Agency" is selected in Client Type filter)
+- **Brand**: Searchable dropdown to filter by specific brand
+- **Source**: Multi-select dropdown to filter by deal source (Influence, Planner, Activate)
+- **Country**: Multi-select dropdown to filter by deal countries
+- **Flight Date Range**: Date picker to filter deals by their flight dates
+- **Budget Range**: Number range to filter by deal budget (min/max)
+
+Each dropdown displays a count of selected items (e.g., "2 selected") and shows removable badges below the dropdown for each selected value. The Apply button applies the filters, and the Clear All button resets all selections.
+
+**Data Formatting**: All dates are displayed in MMM DD, YYYY format (e.g., "Jan 22, 2026"). Currency values display with ISO 3-letter codes (e.g., "USD 50,000" instead of "$50,000").
+
+**Deals Table Columns**: The deals list displays the following columns:
+- **Deal Name**: The name of the deal
+- **Type**: The deal type (Traditional, PG, PMP, etc.)
+- **Source**: Identifies where the deal originated from (Influence, Planner, Activate)
+- **Status**: Current status indicated by a badge (Active or Paused)
+- **Budget**: Total deal budget
+- **Spent**: Amount spent to date
+- **Duration**: Deal start and end dates
+
+**Source Field**: The Source column helps identify where a deal was created:
+- **Influence**: Deals created directly in the Influence UI
+- **Planner**: Traditional deals sent from the Planner platform (pre-approved)
+- **Activate**: Programmatic deals sent from the Activate platform (RFP workflow completed)
+
+This tracking is essential for auditing deal origins, troubleshooting, and understanding integration usage.
+
+### 4.3 Creating a Deal
+
+When the user clicks "New Deal" at the top of the Deals page, the application navigates to a dedicated form page at `/deals/new`. The deal form consolidates all commercial and operational configuration in one place.
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198316)**
+
+<p align="center"><em>Figure 2: Deal Creation Flow</em></p>
+
+**Color Legend:**
+
+| Color | Shape | Meaning |
+|:-----:|:-----:|:--------|
+| Yellow | Circle | Start/End points |
+| Light Blue | Rectangle | Basic Info fields |
+| Green | Rectangle | Inventory Source fields |
+| Orange | Diamond/Rectangle | Deal Type configuration |
+| Purple | Rectangle | Client configuration |
+| Blue | Rectangle | Budget & Goals fields |
+
+### 4.4 Deal Form Fields
+
+The deal form is organized into logical sections, each grouping related fields together.
+
+#### Section 1: Basic Info
+
+**Name** *(Required)*
+
+A descriptive name that identifies this deal throughout the platform. The name is auto-generated based on brand, agency, and date but can be customized. The name should be clear enough that anyone looking at a list of deals can understand what it is. Good examples: "Holiday Season 2024 - RetailMax" or "New Car Launch - AutoDrive Q1". Poor examples: "Deal 1" or "Test".
+
+The name is required and must be unique across all deals. If the user enters a name that already exists, an error message appears: "A deal with this name already exists. Please choose a different name."
+
+**Status**
+
+A dropdown with two options: Active or Paused. The default value is Active. Active deals are eligible for ad serving when their line items are properly configured. Paused deals will not serve any advertisements.
+
+**External Deal ID** *(Optional)*
+
+An optional text field for entering a reference ID from external systems. This field allows users to link the deal to records in other platforms such as CRM systems, planning tools, or third-party order management systems.
+
+Example values: "DEAL-12345", "PO-2026-001", "MW-IO-789"
+
+**Billable**
+
+A toggle switch that indicates whether this deal generates revenue. Default is ON.
+
+When enabled, impressions delivered under this deal are counted toward revenue reporting and will appear in financial reports. Non-billable deals are typically used for house ads, testing, or promotional content that does not generate advertiser revenue.
+
+**Media Type** *(Required)*
+
+A dropdown that determines the advertising channel for this deal. Currently available options:
+
+| Option | Status | Description |
+|--------|--------|-------------|
+| DOOH | Enabled | Digital Out-of-Home advertising on screens |
+| Mobile | Disabled | Reserved for future release |
+| YouTube | Disabled | Reserved for future release |
+| Connected TV | Disabled | Reserved for future release |
+
+Currently, only DOOH is available for selection. The other media types are visible in the dropdown but disabled, indicating planned future capabilities.
+
+#### Section 2: Inventory Source
+
+**SSP Partner** *(Required)*
+
+A dropdown to select the Supply-Side Platform partner for this deal. **Defaults to "Influence"** (the platform's built-in SSP). 
+
+**SSP List Source:** The SSP list is sourced from Admin Console based on the logged-in user's company. Each company has configured SSP access in Admin Console, so the dropdown will only show SSP partners that the user's company has access to.
+
+Available SSP options include:
+- Influence (default - built-in SSP)
+- Hivestack
+- Vistar
+- Place Exchange
+- VIOOH
+- Broadsign
+- Magnite
+
+The SSP determines which demand sources can bid on this inventory and how the programmatic connection is established.
+
+**Note on Media Owner:** Media Owner is configured at the Line Item level, not the Deal level. This allows for more granular control and supports scenarios where a single deal spans multiple media owners (such as campaigns from Planner). See [Line Item Form Fields](#53-line-item-form-fields) for Media Owner configuration details.
+
+#### Section 3: Deal Type Configuration
+
+**Type** *(Required)*
+
+A dropdown that determines the commercial arrangement for this deal:
+
+| Option | Description |
+|--------|-------------|
+| Traditional | Fixed-price guaranteed delivery with reserved inventory, negotiated directly with media owner |
+| Programmatic | Automated buying through DSP platforms with various auction/guaranteed mechanisms |
+
+**Programmatic Sub-type** *(Conditional - shown when Programmatic is selected)*
+
+When Programmatic is selected, a secondary dropdown appears to specify the exact programmatic mechanism:
+
+| Sub-type | Description |
+|----------|-------------|
+| Programmatic Guaranteed (PG) | Guaranteed delivery executed programmatically with fixed pricing |
+| Preferred Deal | First-look access at a fixed CPM before open auction |
+| Private Marketplace (PMP) | Invitation-only auction with selected buyers (supports multi-seat) |
+| Always On | Continuous deal with flexible delivery targets (supports multi-seat) |
+| Open Auction | Real-time bidding where any qualified buyer can compete |
+
+#### Section 4: Client Configuration
+
+**Brand** *(Optional)*
+
+A searchable dropdown to select the brand being advertised. When a brand is selected, the insights panel displays brand-specific information including:
+- Brand Name with initial avatar
+- Category (e.g., Food & Drink, Technology)
+- IAB ID for programmatic targeting
+- Contextual recommendation
+
+**Brand Dropdown Features:**
+- An "Add Brand" button appears at the bottom of the dropdown
+- Clicking "Add Brand" opens a drawer with fields for Brand Name (required), IAB Category (required), Website (optional), and Logo Upload (optional)
+- After creating a brand, it is automatically selected in the dropdown
+
+**Client Type** *(Required)*
+
+A dropdown that determines who the primary client is for this deal:
+- **Direct Advertiser**: The deal is created directly for an advertiser without agency involvement. This is the default option.
+- **Agency**: The deal is managed through an advertising agency.
+
+**Agency** *(Conditional - shown when Client Type is Agency)*
+
+A searchable dropdown to select the specific agency from the list of registered agencies. The dropdown displays each agency name with its country shown below in smaller text.
+
+**Agency Dropdown Features:**
+- An "Add Agency" button appears at the bottom of the dropdown
+- Clicking "Add Agency" opens a drawer with fields for Agency Name (required), Contact Email (required), and Country (required)
+- After creating an agency, it is automatically selected in the dropdown
+
+**DSP Configuration** *(Conditional - shown when Programmatic AND Brand or Agency is selected)*
+
+When the deal is Programmatic and either a Brand or Agency has been selected, DSP configuration fields appear in a highlighted configuration panel:
+
+**DSP Partner**
+
+A dropdown to select the Demand-Side Platform partner. The DSP list is sourced from the Admin Console platform based on the company's DSP Access configuration. Each company (Agency or Brand) has a list of DSP partners they are authorized to use.
+
+**Seat Name**
+
+A dropdown to select the buyer seat for this deal. The available seats are filtered based on the selected DSP Partner. Seat names are configured in Admin Console for each DSP-Company combination.
+
+**Seat ID** *(View-Only)*
+
+A read-only field that displays the unique identifier for the selected seat. The Seat ID is automatically fetched from Admin Console based on the seat name selection. The system verifies the Seat ID exists in Admin Console before allowing the deal to be saved successfully.
+
+**DSP/Seat Management Workflow:**
+
+1. **DSP Access Configuration**: In Admin Console, each company (Agency or Brand) has a list of DSP partners they can access. This controls which DSPs appear in the dropdown.
+
+2. **Seat Creation**: While creating or editing an agency in Influence, users can select a DSP and create seats. This action creates the seat record in Admin Console.
+
+3. **Seat ID Verification**: When saving a deal, the system verifies the Seat ID exists in Admin Console. If the Seat ID is invalid or has been removed, the save will fail with an error message.
+
+4. **Seat ID Display**: Seat IDs are fetched from Admin Console and displayed as read-only in Influence. Users cannot manually enter Seat IDs.
+
+See [Admin Console Integration](#105-admin-console-integration) for more details on the integration architecture.
+
+#### Section 5: Budget & Goals
+
+**Countries** *(Required - at least one)*
+
+A multi-select dropdown to select the countries for this deal. **At least one country must be selected. By default, the country of the logged-in user's company is pre-selected.**
+
+**Country List Source:** The available countries are sourced from Admin Console based on the logged-in user's country access permissions. Each user account has configured country access in Admin Console, so the dropdown will only show countries that the user has permission to create deals for.
+
+The selected countries:
+- Filter available inventory to screens in those countries
+- Determine which cities/areas can be targeted in line items (line item geography targeting is constrained to cities, areas, and towns within the deal's selected countries)
+- Affect currency options
+
+When countries are selected, the insights panel updates to show market-specific information including population, available inventories, and estimated impression capacity.
+
+**Currency** *(Required)*
+
+A dropdown that shows available currencies. **The currency is automatically set based on the first selected country** (e.g., Malaysia → MYR, Singapore → SGD, United States → USD). Users can manually change the currency if needed. If multiple countries are selected, the currency defaults to the first country's currency but can be changed to any supported currency.
+
+**Exchange Rate Margin for Cross-Currency Deals**
+
+When the selected deal currency differs from a country's local currency, a margin is automatically applied to account for exchange rate fluctuations:
+
+| Scenario | Example | Margin Applied |
+|----------|---------|----------------|
+| Currency matches country | Malaysia + MYR | No margin |
+| Currency differs from country | Malaysia + USD | 3% margin added |
+| Mixed currencies in multi-country | Malaysia + Singapore with USD | 3% margin for both |
+
+**Important Exchange Rate Considerations:**
+
+1. **Exchange Rate Source**: Exchange rates are fetched from Admin Console, where rates are updated daily by the finance team.
+
+2. **Floor Rate Calculation Timing**: When a line item is created, the floor rate is calculated using the exchange rates available at that moment. This calculated floor rate is then saved on the line item record.
+
+3. **Floor Rate Lock-In (Critical)**: Once a line item is created and its floor rate is calculated, **the floor rate remains fixed regardless of subsequent exchange rate changes**. This means:
+   - If you create a line item on January 15th with a floor rate of $5.00 (converted from MYR 22.00 at 1 USD = 4.40 MYR)
+   - And the campaign goes live on January 20th when the exchange rate has changed to 1 USD = 4.50 MYR
+   - The line item will still use the original floor rate of $5.00, NOT recalculate based on the new rate
+
+4. **User Responsibility**: Users should be aware of this behavior and plan accordingly:
+   - Create line items close to the campaign launch date when possible
+   - Monitor exchange rate trends when dealing with volatile currencies
+   - Consider the margin buffer when setting floor rates for cross-currency deals
+
+The system displays a warning in the insights panel when a currency mismatch is detected, reminding users about the margin and the floor rate lock-in behavior.
+
+**Budget** *(Optional)*
+
+A numeric input for entering the budget amount. When provided, the budget caps total spending for this deal regardless of impressions delivered.
+
+While the budget field is not required, providing a budget enables the platform to return better inventory recommendations when configuring targeting in line items.
+
+**Goal** *(Optional)*
+
+The goal consists of two components displayed inline:
+
+1. **Goal Type Dropdown**: A dropdown to select the type of goal:
+
+| Goal Type | Description |
+|-----------|-------------|
+| Impressions | Total number of ad views/exposures to your target audience |
+| Reach | Unique individuals exposed to your deal |
+| Share of Voice | Your brand's presence as a percentage of total market activity |
+| Carbon Emission | Minimize or cap your deal's environmental footprint |
+| Ad Plays | Total number of times your ad content is played on screens |
+
+2. **Goal Value Field**: A numeric input for entering the target value for the selected goal type.
+
+**Minimum Target Threshold** *(Mandatory for PG)*
+
+The minimum target threshold defines the delivery floor for this deal:
+
+1. **Target Type Dropdown**: Select whether the threshold is measured in Impressions or Ad Plays
+2. **Target Value Field**: A numeric input for entering the minimum delivery target
+
+**Hard Stop** *(Conditional - shown only for Programmatic Guaranteed deals)*
+
+A toggle switch that is ONLY visible when the Deal Type is Programmatic Guaranteed (PG). For all other deal types, this field is hidden.
+
+- **Enabled**: Delivery stops immediately when the deal's budget is exhausted, preventing overspend
+- **Disabled**: The deal may continue running and attempt to deliver beyond the budget constraint
+
+**Start Date** *(Required)*
+
+A date picker for selecting when the deal should begin delivering impressions.
+
+**End Date** *(Required)*
+
+A date picker for selecting when the deal should stop. No impressions will be delivered after this date. The end date must be after the start date.
+
+#### Section 6: Verification
+
+**AdPay Verification Report**
+
+A checkbox that enables third-party verification tracking for this deal. When enabled, the system will generate verification reports that can be shared with advertisers to prove that advertisements were actually displayed.
+
+**Service Provider** *(Conditional - shown when AdPay Verification is enabled)*
+
+A dropdown specifying which third-party verification service will be used:
+
+| Provider | Description |
+|----------|-------------|
+| MAV | Media Audit Verification services |
+| IAS | Integral Ad Science verification |
+| OIS | Out-of-Home Intelligence Services |
+| Veridooh | DOOH-specific verification platform |
+
+### 4.5 Deal Status Lifecycle
+
+Deals have two possible statuses: **Active** and **Paused**. This simplified status model provides clear operational control.
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198312)**
+
+<p align="center"><em>Figure 3: Deal Status Lifecycle</em></p>
+
+**Color Legend:**
+
+| Color | Status | Meaning |
+|:-----:|:------:|:--------|
+| Green | Active | Deal is running and delivering impressions |
+| Orange | Paused | Deal is temporarily stopped |
+
+**New Deal Creation**
+
+When a deal is created, its default status is Active. All fields can be edited at any time regardless of status.
+
+**Active → Paused**
+
+While a deal is Active, the user can click "Pause Deal" to temporarily stop delivery. This is useful when the advertiser needs to halt the deal for business reasons. Pausing immediately stops all impressions.
+
+**Paused → Active**
+
+The user can click "Resume Deal" to restart a paused deal. Delivery continues from where it stopped.
+
+**Note on External Sources:** Deals that arrive from Planner are pre-approved Traditional deals. Deals from Activate are Programmatic deals with completed RFP workflows. These deals do not go through statuses like "Generated", "Reserved", or "Negotiation" as those are part of the source platform's workflow, not Influence.
+
+#### Deal Acceptance and Reopening
+
+When a deal is ready for execution, the user can send it for acceptance:
+
+**For Programmatic Deals:** The "Request Acceptance" button sends the deal configuration to DSP partners for approval.
+
+**For Traditional Deals:** The "Activate Deal" button sends the deal to the CMS for activation.
+
+Once a deal has been sent for acceptance:
+
+1. **Deal Becomes Locked:** The deal enters a locked state where no edits are permitted. A warning banner is displayed: "This deal has been sent to stakeholders for approval. Click 'Reopen' to make changes."
+
+2. **Reopen Functionality:** If changes are needed after the deal has been sent, the user can click the "Reopen" button to unlock editing.
+
+3. **Editing Restrictions After Reopening:**
+   - **Deal Type Cannot Be Changed:** Traditional deals cannot become Programmatic, and vice versa. The deal type is locked and displayed as read-only with a "From Deal" badge.
+   - **Limited Editable Fields:** After reopening, only the deal name and ad-play verification settings can be modified at the deal level.
+   - **Stakeholder Notification:** Any changes made after reopening require re-approval from stakeholders.
+
+4. **Reopened State Display:** Once reopened, the "Reopen" button shows as "Reopened" (disabled) to indicate the deal has been reopened for editing.
+
+### 4.6 Editing and Deleting Deals
+
+**Editing**
+
+The user can edit a deal by clicking the three-dot menu icon on the deal row and selecting "Edit". What can be edited depends on the deal status and acceptance state:
+
+| Status | Acceptance State | What can be edited |
+|--------|------------------|-------------------|
+| Active | Not Sent | All fields including name, dates, budget, type |
+| Paused | Not Sent | All fields including name, dates, budget, type |
+| Active | Sent (Locked) | No edits allowed until Reopen is clicked |
+| Active | Reopened | Name and Ad-Play Verification only (Deal Type is locked) |
+
+**Deleting**
+
+Deals can be deleted via the three-dot menu. A confirmation dialog appears: "Are you sure you want to delete this deal? This action cannot be undone."
+
+### 4.7 Deal Detail Page
+
+The Deal Detail page provides a comprehensive view of a single deal and all its associated line items. This page is accessed by clicking on any deal row in the Deals list, and serves as the primary interface for managing line items within a deal context.
+
+**Accessing the Deal Detail Page**
+
+From the Deals list, clicking any deal row navigates to `/deals/:id`, where `:id` is the unique identifier for that deal. The page displays the deal name prominently at the top, along with a breadcrumb trail showing `Deals > Deal Name`.
+
+**Summary Statistics**
+
+Above the line items table, the page displays a row of metric cards that provide at-a-glance performance information for the deal:
+
+| Metric | Description |
+|--------|-------------|
+| Total Line Items | Count of line items within this deal, regardless of status |
+| Ad Plays | Total number of times advertisements were played across all line items |
+| Impressions | Sum of delivered impressions across all line items |
+| Revenue vs Budget | Comparison showing actual revenue earned versus the deal budget |
+| Delivery Progress | Percentage of overall deal delivery completed, displayed as a progress bar |
+
+**Line Items Table**
+
+The main content area displays a table of all line items belonging to this deal. The table includes the following columns:
+
+| Column | Description |
+|--------|-------------|
+| Name | The descriptive name of the line item |
+| Status | Current status (Active, Paused, Draft) |
+| Priority | Number 1-10 indicating serving priority (1 = highest) |
+| Target Impressions | Goal number of impressions to deliver |
+| Delivered | Count of impressions actually delivered |
+| CPM | Cost per thousand impressions |
+| Traffic Allocation | Percentage of deal traffic this item should receive |
+| Pacing | Delivery status indicator (On Track, Behind, Ahead, At Risk) |
+
+Clicking any row in this table navigates to the Line Item edit form.
+
+**Search and Filter Functionality**
+
+A search input at the top of the table allows users to filter line items by name. The list updates in real-time as the user types.
+
+A "Filters" button opens the filter drawer with options specific to line items within the current deal:
+- **Status**: Filter by line item status (Active or Paused)
+- **Media Owner**: Filter by media owner assigned to line items
+- **Flight Date Range**: Date picker to filter by line item flight dates
+- **Budget Range**: Number range to filter by line item budget (min/max)
+
+**Creating New Line Items**
+
+A "New Line Item" button appears in the page header. Clicking this button navigates to the line item creation form at `/deals/:dealId/line-items/new`, with the deal pre-selected.
+
+**Deal Activation Workflow**
+
+After at least one line item has been created for the deal, an activation button appears in the Deal Detail page header. The button type and behavior depend on the deal type:
+
+**For Programmatic Deals**
+
+A **Request Acceptance** button appears. Clicking this button:
+
+1. Validates that at least one line item exists
+2. Generates deal packages with all targeting, pricing, and scheduling parameters
+3. Sends the deal proposal to the DSP partner specified in the deal
+4. Transitions the deal to a "pending acceptance" state
+
+DSP partners review the deal proposals and respond with either acceptance or rejection. Once accepted, ad serving can begin.
+
+**For Traditional Deals**
+
+An **Activate Deal** button appears. Clicking this button:
+
+1. Validates that at least one line item exists
+2. Packages all deal and line item information
+3. Sends the configuration to the Booking Engine for publication
+4. Transitions the deal to an "active" state
+
+**Button Visibility and Enablement**
+
+- **Button is hidden**: Until at least one line item has been created
+- **Button is disabled**: If the deal has no line items
+- **Button is enabled**: When at least one line item exists and is properly configured
+
+### 4.8 Mandatory Fields
+
+Certain fields throughout the platform are marked as mandatory, indicated by an asterisk (*) next to the field label. The system prevents saving records when mandatory fields are not completed.
+
+**Deal Mandatory Fields**
+
+| Field | Description |
+|-------|-------------|
+| Deal Name * | A unique, descriptive name identifying the deal |
+| Media Type * | The advertising channel (currently DOOH only) |
+| Client Type * | Whether the deal is for a Direct Advertiser or Agency |
+| SSP Partner * | The supply-side platform partner for this deal |
+| Countries * | At least one country must be selected |
+| Start Date * | When the deal begins serving |
+| End Date * | When the deal stops serving |
+| Deal Type * | Traditional or Programmatic (with sub-type if Programmatic) |
+| DSP Partner * | Required only for programmatic deal types |
+
+**Line Item Mandatory Fields**
+
+| Field | Description |
+|-------|-------------|
+| Line Item Name * | A descriptive name for the line item |
+| Media Owner * | The media owner whose screens will be used |
+| Creative Type * | The format of the advertisement (Display, Video, or Audio) |
+| Start Date * | When the line item begins serving |
+| End Date * | When the line item stops serving |
+| Floor Rate * | The minimum price for this line item |
+| Floor Rate Type * | How pricing is calculated (CPM or CPS) |
+
+**Validation Indicators**
+
+- **Form-level validation**: Inline error messages appear next to incomplete fields
+- **List view warnings**: Warning icons appear next to items with missing required fields
+- **Tooltip details**: Hovering over warnings shows which fields are missing
+
+### 4.9 Deal Form Quick Tips and Brand Information
+
+The right side of the deal form displays a dynamic contextual panel that updates as users scroll through the form and interact with fields. This panel provides section-specific guidance and, when applicable, displays brand information.
+
+#### 4.9.1 Dynamic Quick Tips (Scroll-Based)
+
+The Quick Tips panel intelligently updates its content based on which section of the form is currently visible as the user scrolls. This provides contextually relevant guidance exactly when needed.
+
+**Section: Deal Basics** (Visible when viewing Deal Name, Status, External ID, Billable, Media Type)
+
+| Tip | Description |
+|-----|-------------|
+| Deal Name | Should be descriptive and unique to easily identify it in lists |
+| Status | Controls whether the deal is Active (running) or Paused (stopped) |
+| Media Type | Defines the channel - DOOH (Digital Out-of-Home) is for digital screens |
+| External Deal ID | Helps sync with external systems like your CRM |
+| Billable | Flag determines if this deal is included in invoicing |
+
+**Section: Supply Configuration** (Visible when viewing SSP Partner, Deal Type)
+
+| Tip | Description |
+|-----|-------------|
+| SSP Partner | Supply-Side Platform provides access to inventory networks |
+| Deal Type | Determines pricing model - Traditional or Programmatic |
+| Programmatic | Enables automated real-time bidding with DSP partners |
+| Media Owner | Selected at Line Item level for more granular control |
+| Client Type | Indicates if this is a direct client or through an agency |
+
+**Section: Brand & Verification** (Visible when viewing Brand, Client, DSP Config, AdPlay Verification, Countries)
+
+| Tip | Description |
+|-----|-------------|
+| Brand Selection | Enables brand-specific insights and recommendations |
+| AdPlay Verification | Ensures ads are actually played on screens |
+| Countries | Selected here limit geography targeting in line items |
+| Line Item Geography | Can only target cities/areas within the deal's countries |
+
+**Section: Budget & Goals** (Visible when viewing Currency, Budget, Goal Type, Goal Value, PG Settings)
+
+| Tip | Description |
+|-----|-------------|
+| Currency | Determines the monetary unit for all budget and pricing |
+| Currency Margin | 3% margin applies when inventory uses different currencies |
+| Goal Type | Sets what you're optimizing for - Impressions, Reach, etc. |
+| Budget & Goals | Help with better inventory recommendations in Line Items |
+| Budget Tracking | Setting budget enables spend tracking and pacing recommendations |
+
+#### 4.9.2 Brand Information Card
+
+When a brand is selected AND the user is viewing the Brand section of the form, the Quick Tips panel is replaced with a Brand Information card that displays:
+
+| Element | Description |
+|---------|-------------|
+| Brand Logo | Large initial letter avatar (placeholder until logo URL is provided) |
+| Brand Name | Full brand name prominently displayed |
+| Status | Active Brand or Inactive Brand indicator |
+| IAB Category | The brand's business category as a badge (e.g., "Food & Drink", "Technology & Computing") |
+| IAB Code | Abbreviated code derived from the category (e.g., "F&D" for Food & Drink) |
+| Recommendation | "Brand selection enables personalized inventory recommendations in line items" |
+
+The Brand Information card provides immediate visual confirmation of the selected brand and its categorization, helping users verify they've selected the correct brand before proceeding.
+
+#### 4.9.3 Panel Display Logic
+
+The right panel follows these display rules in priority order:
+
+1. **Brand Info Card**: Displayed when a brand is selected AND the visible section is "brand"
+2. **Quick Tips**: Displayed in all other cases, with content matching the currently visible form section
+3. **Market Insights**: When countries are selected, the Market Insights panel is shown below the Quick Tips/Brand Info card as an additional panel
+
+This ensures users always have relevant contextual information visible without having to scroll or navigate away from their current position in the form.
+
+#### 4.9.4 Market Insights Panel
+
+When users select one or more countries, an additional Market Insights panel appears below the Quick Tips or Brand Info card:
+
+| Element | Description |
+|---------|-------------|
+| Country Flags | Visual representation of selected markets |
+| World Map | Regional visualization highlighting selected countries |
+| Population | Combined population across selected markets |
+| Inventories | Total available screen inventory in selected countries |
+| Impressions | Estimated impression capacity across markets |
+
+### 4.10 VAST Tag Distribution
+
+#### 4.10.1 Overview
+
+Once a deal is created and line items are configured, the ad serving system needs a way to connect with the media owner's CMS and players. This connection happens through VAST (Video Ad Serving Template) endpoints. A VAST endpoint is a URL that the player calls whenever it needs to show an ad. The player sends a request to the endpoint, receives back an XML response containing the creative media file URL and tracking instructions, and then renders the advertisement.
+
+The challenge is that not all media owners' CMS platforms support VAST endpoints natively. Some older or simpler CMS systems can only schedule static content files like HTML pages or ZIP packages. Influence addresses both scenarios by providing three distribution formats:
+
+1. **VAST Endpoint URL** - For CMS platforms that natively support VAST tags (e.g., Broadsign, Scala, Signagelive)
+2. **HTML File** - A self-contained HTML page with an embedded VAST player, for CMS platforms that support web content scheduling
+3. **ZIP Package** - A bundled package containing the HTML player and all required assets, for CMS platforms that only accept offline file uploads
+
+#### 4.10.2 VAST Endpoint URL Structure
+
+Each line item generates its own VAST endpoint URL. The endpoint is generated at the line item level (not the deal level) because each line item has its own targeting, creatives, and delivery configuration.
+
+**URL Format:**
+
+```
+https://{platform-domain}/vast/v1/{deal-id}/{line-item-id}?screen_id={screen_id}&player_id={player_id}
+```
+
+**URL Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `{platform-domain}` | Path | The Influence platform domain (e.g., `adserver.influence.io`) |
+| `{deal-id}` | Path | The unique identifier of the parent deal |
+| `{line-item-id}` | Path | The unique identifier of the line item |
+| `screen_id` | Query | The ID of the screen making the ad request (provided by the player) |
+| `player_id` | Query | The ID of the media player making the request (provided by the player) |
+
+**Example:**
+```
+https://adserver.influence.io/vast/v1/deal_abc123/li_xyz789?screen_id=SCR001&player_id=PL001
+```
+
+**VAST Response:**
+
+When a player calls the endpoint, Influence evaluates the line item's targeting rules, traffic allocation, priority, and frequency caps. If an ad is eligible to serve, the response is a standard VAST XML document containing:
+
+- The creative media file URL (video, image, or HTML5)
+- Impression tracking pixel URLs
+- Start, complete, and quartile tracking events
+- Click-through URL (if applicable)
+- Ad duration and creative dimensions
+
+If no ad is eligible (e.g., frequency cap reached, budget exhausted, outside flight dates), the response is an empty VAST document with no ad elements, signaling the player to move on to its next scheduled content.
+
+#### 4.10.3 Distribution Tab on Deal Detail Page
+
+The Distribution interface is accessed via a **"Distribution"** tab on the Deal Detail page (`/deals/:id`). This tab appears alongside the existing Line Items tab once the deal has been activated (i.e., after "Request Acceptance" for programmatic deals or "Activate Deal" for traditional deals).
+
+**Tab Visibility Rules:**
+
+| Deal State | Distribution Tab |
+|------------|-----------------|
+| Deal created, no line items | Hidden |
+| Deal with line items, not yet activated | Hidden |
+| Deal activated (acceptance requested or deal activated) | Visible |
+| Deal paused | Visible (with warning banner) |
+
+**Distribution Tab Layout:**
+
+The tab displays a table listing each line item in the deal, with distribution information:
+
+| Column | Description |
+|--------|-------------|
+| Line Item Name | The name of the line item (clickable, navigates to line item form) |
+| Status | Current line item status (Active, Paused) |
+| VAST Endpoint | The full VAST endpoint URL with a copy-to-clipboard button |
+| Actions | Download dropdown with options: "Copy URL", "Download HTML", "Download ZIP" |
+
+**Copy-to-Clipboard Behavior:**
+
+Clicking the copy button next to the VAST endpoint URL copies the full URL to the clipboard and displays a brief toast notification: "VAST endpoint copied to clipboard". The copy button uses a clipboard icon that briefly changes to a checkmark icon upon successful copy.
+
+**Bulk Actions:**
+
+A "Download All" button in the table header allows downloading all line item tags at once:
+- **Download All as ZIP**: Creates a single ZIP file containing individual HTML files for each line item, organized in folders named by line item
+- **Copy All URLs**: Copies all VAST endpoint URLs to the clipboard, one per line, with line item names as labels
+
+#### 4.10.4 CMS Compatibility Options
+
+The Actions column for each line item provides a dropdown menu with three distribution options:
+
+**Option 1: Copy VAST URL**
+
+For media owners whose CMS natively supports VAST tags. The user copies the endpoint URL and pastes it into their CMS scheduling interface. This is the preferred method when supported, as the player communicates directly with Influence's ad server in real-time.
+
+**Compatible CMS platforms include:**
+- Broadsign
+- Scala (Stratacache)
+- Signagelive
+- BrightSign
+- Navori
+- Any CMS with VAST 3.0+ or VAST 4.0+ support
+
+**Option 2: Download HTML**
+
+For CMS platforms that can schedule web content (HTML pages) but do not support VAST tags directly. The downloaded HTML file is a self-contained web page with an embedded lightweight VAST player.
+
+**Option 3: Download ZIP**
+
+For CMS platforms that only accept file uploads (no URL scheduling, no web content). The ZIP package contains the HTML player file plus all required JavaScript and CSS assets bundled for offline use.
+
+#### 4.10.5 HTML File Generation
+
+When the user clicks "Download HTML", the backend generates a self-contained HTML file that wraps the VAST endpoint in a lightweight ad player.
+
+**HTML File Contents:**
+
+The generated HTML file includes:
+
+1. **VAST Player Library**: A lightweight JavaScript VAST client (based on the IAB VAST standard) that handles:
+   - Calling the VAST endpoint URL
+   - Parsing the VAST XML response
+   - Rendering the creative (video, image, or HTML5)
+   - Firing tracking pixels (impression, quartile, complete events)
+   - Handling error cases (empty VAST, network failures)
+
+2. **Configuration Block**: A JSON configuration embedded in the HTML that includes:
+   - The VAST endpoint URL for this specific line item
+   - Refresh interval (how often to request a new ad, in seconds)
+   - Fallback behavior (what to display if no ad is available)
+   - Creative dimensions (width and height matching the line item's inventory format)
+
+3. **Responsive Layout**: The HTML page auto-sizes to fill the player's display area, ensuring the creative renders at the correct dimensions regardless of screen resolution.
+
+4. **Error Handling**: If the VAST endpoint returns no ad or is unreachable, the player:
+   - Displays a transparent/blank frame (allowing the CMS's default content to show through)
+   - Retries after the configured refresh interval
+   - Logs errors locally for diagnostic purposes
+
+**File Naming Convention:**
+
+```
+{deal-name}_{line-item-name}_vast.html
+```
+
+Example: `Summer_Refresh_Mall_Entrance_Screens_vast.html`
+
+Special characters in names are replaced with underscores, and the filename is truncated to 100 characters maximum.
+
+#### 4.10.6 ZIP Package Generation
+
+When the user clicks "Download ZIP", the backend generates a ZIP archive containing everything needed for fully offline VAST playback.
+
+**ZIP Package Contents:**
+
+```
+/{deal-name}_{line-item-name}/
+├── index.html              # Main HTML file (same as the HTML download)
+├── assets/
+│   ├── vast-player.min.js  # Minified VAST player library
+│   ├── vast-player.min.css # Player styles
+│   └── fallback.png        # Optional fallback image (transparent 1x1 pixel)
+├── config.json             # Player configuration
+└── README.txt              # Instructions for the media owner
+```
+
+**README.txt Contents:**
+
+The README file provides plain-language instructions for the media owner:
+
+```
+VAST Ad Tag Package - {Deal Name} / {Line Item Name}
+Generated: {date}
+Generated by: Influence Adserver
+
+SETUP INSTRUCTIONS:
+1. Upload this folder to your CMS
+2. Schedule "index.html" as a web content item on the target screens
+3. Set the duration to match your ad slot length
+4. Ensure the player has internet connectivity for ad requests
+
+REQUIREMENTS:
+- Internet connection (for real-time ad requests)
+- HTML5-capable media player
+- Minimum screen resolution: {width}x{height}
+
+VAST ENDPOINT:
+{full VAST endpoint URL}
+
+SUPPORT:
+Contact your Influence account manager for technical assistance.
+```
+
+**File Naming Convention:**
+
+```
+{deal-name}_{line-item-name}_vast_package.zip
+```
+
+#### 4.10.7 Distribution Workflow by Deal Type
+
+The distribution workflow differs slightly based on deal type:
+
+**Traditional Deals:**
+
+1. Deal is created with traditional line items
+2. Line items are configured with targeting, creatives, and flight dates
+3. User clicks "Activate Deal" on the Deal Detail page
+4. The "Distribution" tab becomes visible
+5. User shares VAST tags (URL, HTML, or ZIP) with the media owner
+6. Media owner schedules the tags on their CMS/players
+7. Players begin calling the VAST endpoint when the flight dates start
+8. Influence serves creatives and tracks impressions
+
+**Programmatic Deals:**
+
+1. Deal is created with programmatic line items
+2. Line items are configured with targeting, creatives, bid strategy, and flight dates
+3. User clicks "Request Acceptance" on the Deal Detail page
+4. DSP partners review and accept the deal
+5. The "Distribution" tab becomes visible
+6. User shares VAST tags with the media owner
+7. Players begin calling the VAST endpoint
+8. When a request comes in, Influence initiates a programmatic auction via the SSP
+9. DSP bids are evaluated, winning creative is served
+10. Impressions and bid data are tracked
+
+**Key Difference:** For programmatic deals, the VAST endpoint triggers an auction process rather than directly serving a pre-assigned creative. The endpoint URL structure is the same, but the backend logic differs.
+
+#### 4.10.8 API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/deals/:dealId/distribution` | Returns distribution information for all line items in the deal, including VAST endpoint URLs |
+| `GET` | `/api/deals/:dealId/line-items/:lineItemId/vast-tag` | Returns the VAST endpoint URL for a specific line item |
+| `GET` | `/api/deals/:dealId/line-items/:lineItemId/vast-tag/html` | Generates and downloads the HTML file for a specific line item |
+| `GET` | `/api/deals/:dealId/line-items/:lineItemId/vast-tag/zip` | Generates and downloads the ZIP package for a specific line item |
+| `GET` | `/api/deals/:dealId/distribution/download-all` | Downloads a single ZIP containing HTML files for all line items in the deal |
+| `GET` | `/vast/v1/:dealId/:lineItemId` | The actual VAST endpoint called by players (returns VAST XML) |
+
+---
+
+## 5. Line Items
+
+Line items are where actual advertising execution happens. While deals provide commercial and operational structure, line items specify targeting criteria, pricing, delivery goals, and track how many impressions have been delivered.
+
+### 5.1 What Line Items Control
+
+Each line item specifies the following:
+
+**Target Impressions**
+
+The goal number of impressions this line item should deliver. This is the commitment to the advertiser. For example, a target of 100,000 means the line item should show the ad 100,000 times.
+
+**CPM (Cost Per Mille)**
+
+The price for 1,000 impressions. For traditional line items, this is the agreed rate with the advertiser. For programmatic line items, this is the floor price - bids below this amount are rejected.
+
+Example: At $15 CPM, delivering 100,000 impressions generates revenue of (100,000 ÷ 1,000) × $15 = $1,500.
+
+**Priority**
+
+A number from 1 to 10, where 1 is highest priority and 10 is lowest. When multiple line items are eligible to show on the same screen at the same moment, priority determines consideration order.
+
+Priority 1 line items are considered first. Only if they are unavailable (paused, capped, or allocated elsewhere) are priority 2 line items considered, and so on.
+
+Typical priority assignments:
+- Priority 1: Sponsorships and premium takeovers
+- Priority 2-3: High-value guaranteed deals
+- Priority 4-5: Standard deals (default)
+- Priority 6-7: Lower-value or remnant inventory
+- Priority 8-10: House ads and default content
+
+**Traffic Allocation**
+
+Controls what share of the parent deal's traffic this line item should receive. See Section 6 for details.
+
+**Creative Duration**
+
+The length of the advertisement in seconds. Common values are 5, 10, 15, 20, 30, or 60 seconds. This must match the actual creative file's duration.
+
+**Assigned Creatives**
+
+Each line item must have at least one creative assigned to it before it can deliver impressions. Assigned creatives are selected from the Content Hub and must have **Tier 1 Accepted** status.
+
+When creatives are assigned to a line item, they enter the **Tier 2 Approval workflow** where the Media Owner validates their compatibility with the target screens. A line item requires at least one creative with **Tier 2 Approved** status before any impressions can be delivered.
+
+Multiple creatives can be assigned to a single line item with individual weights controlling their rotation frequency (e.g., 50%, 30%, 20%). This enables A/B testing, creative rotation, and fatigue prevention.
+
+### 5.2 Creating a Line Item
+
+When the user clicks "New Line Item" from the Deal Detail page, the application navigates to a dedicated form page at `/deals/:dealId/line-items/new`. 
+
+#### Line Item Form Structure
+
+The Line Item form is a single-page form with card-based sections. Each section is organized vertically with a forecasting panel on the right side that updates in real-time based on form selections.
+
+The form contains the following card-based sections:
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198320)**
+
+<p align="center"><em>Figure 4: Line Item Creation Flow</em></p>
+
+**Color Legend:**
+
+| Color | Meaning |
+|:-----:|:--------|
+| Light Blue | Form sections |
+| Green | Targeting criteria fields |
+| Yellow | Inventory source fields |
+| Indigo | Inventory selection fields |
+| Orange | Advanced options |
+| Purple | Success outcome |
+| Gray | End point |
+
+#### Section 1: Basic Info
+
+**Name** *(Required)*
+
+A descriptive name that identifies this line item. The name should indicate the creative and targeting approach. Examples: "15s Brand Anthem - Mall Entrances", "10s Product Promo - Transit", or "30s Video - Premium Locations".
+
+**Status**
+
+A dropdown with three options:
+- **Active**: The line item is running and eligible for ad serving
+- **Paused**: The line item is temporarily stopped
+- **Draft**: The line item is being configured and is not yet ready to serve
+
+Default value is Draft for new line items.
+
+**Copy Existing Line Item**
+
+A searchable dropdown that allows selecting an existing line item to use as a template. When selected, all configuration from the source line item is copied.
+
+This option is not available for PG (Programmatic Guaranteed) deals.
+
+#### Section 2: Creative
+
+**Creative Type** *(Required)*
+
+A dropdown that specifies the format of the advertisement:
+
+| Type | Description |
+|------|-------------|
+| Display | Static image advertisements (JPEG, PNG) |
+| Video | Moving picture advertisements (MP4, WebM) |
+| Audio | Audio-only advertisements for screens with speakers |
+
+**Priority**
+
+A slider control ranging from 1 to 10, where:
+- **1** = Highest priority (premium placements, sponsorships)
+- **10** = Lowest priority (house ads, default content)
+
+Default value is 5 (standard priority).
+
+**Auction Type** *(View-Only, Auto-Calculated)*
+
+This field displays the auction mechanism based on the parent deal's type:
+
+| Parent Deal Type | Auction Type |
+|------------------|--------------|
+| Programmatic Guaranteed (PG) | Fixed Price |
+| Preferred Deal | Fixed Price |
+| Traditional | Not Applicable |
+| Always On | First Price Auction |
+| Private Marketplace (PMP) | First Price Auction |
+| Open Auction | First Price Auction |
+
+#### Section 3: Targeting
+
+**Section Title:** "Targeting"  
+**Section Description:** "Define audience targeting criteria"
+
+All targeting fields are multi-select, allowing users to include multiple values for broader reach or narrow targeting.
+
+**Inherited Geographic Constraints**
+
+Line items inherit country settings from their parent Deal. Geography targeting (cities, areas, towns, POIs) can only select locations within the deal's selected countries.
+
+**Demographics**
+
+Demographics targeting is organized into two separate collapsible sections within the Targeting card. Each section uses a summary row pattern that displays the current selection and expands to reveal options when clicked. Clicking outside an expanded section automatically closes it.
+
+**Age Groups**
+
+A collapsible section showing "X age groups selected" in the summary row. When expanded, displays a grid of checkboxes:
+- 18-24
+- 25-34
+- 35-44
+- 45-54
+- 55-64
+- 65+
+
+**Gender**
+
+A separate collapsible section showing "X genders selected" in the summary row. When expanded, displays checkboxes:
+- Male
+- Female
+
+**Geography (Advanced Map)**
+
+Select target geographic areas within the deal's countries using an interactive map-based interface. Clicking the Geography row opens the Advanced Map Drawer containing:
+
+**Advanced Map Drawer**
+
+The drawer provides a comprehensive geotargeting interface with advanced Mapbox tooling:
+
+**Map Toolbar**
+
+A vertical toolbar on the map provides drawing and visualization tools:
+- **Circle Draw Tool**: Draw circular targeting areas with radius labels displayed on the map
+- **Polygon Draw Tool**: Draw custom polygon shapes for precise geographic targeting
+- **Line Draw Tool**: Draw line segments for corridor-based targeting
+- **3D View Toggle**: Switch between 2D and 3D map perspectives
+- **Heatmap Toggle**: Display audience density visualization with hourly slider control
+
+**Audience Density Heatmap**
+
+When enabled, the heatmap overlay visualizes audience concentration across the map. An hourly slider (0-23) allows viewing density patterns at different times of day, helping advertisers understand when audiences are most concentrated in specific areas.
+
+**CSV Upload for Bulk Targeting**
+
+A CSV upload feature enables bulk coordinate targeting:
+- **Download Template**: Button to download a CSV template with columns: Name (optional), Latitude, Longitude, Radius (optional, defaults to 250m)
+- **Upload CSV**: Drag-and-drop or file picker for uploading coordinate files
+- **Validation**: System validates coordinates and displays errors for invalid entries
+- **Bulk Add**: All valid locations are added to the map as targeting circles
+
+**Include/Exclude Selection**
+
+Each selected location can be marked as:
+- **Include** (green check icon): Screens within this area are targeted
+- **Exclude** (red ban icon): Screens within this area are excluded from targeting
+
+This enables precision targeting by including broad areas and excluding specific zones.
+
+**Additional Features**
+- **Interactive Mapbox Map**: Full-width map view with searchable location autocomplete filtered to the deal's selected countries
+- **Search bar**: Find locations by name with autocomplete
+- **Radius selection**: Adjustable radius for point-based targeting (default 250m)
+- **Selected Locations List**: Below the map showing selected cities, areas, and custom shapes
+- **Location Count Badge**: The geography row displays the count of selected locations
+- **Fixed footer**: "Apply Selection" and "Cancel" buttons
+
+**Note:** Location search results are filtered to only show locations within the parent deal's selected countries.
+
+**Points of Interest (POI) Targeting**
+
+POI targeting allows advertisers to target screens near specific locations. The POI Targeting drawer provides a comprehensive interface for selecting and managing POIs.
+
+**POI Targeting Drawer**
+
+Clicking the POI Targeting row opens a side drawer with:
+- **Search bar**: Find POIs by name or address
+- **Category filter**: Dropdown to filter POIs by category
+- **Map view**: Interactive Mapbox map showing POI locations
+- **POI list**: Selectable list of POIs with distance information
+- **Selected POIs section**: Summary of currently selected POIs with remove buttons
+- **Fixed footer**: "Apply Selection" and "Cancel" buttons
+
+**POI Categories**
+
+| Category | Description |
+|----------|-------------|
+| Shopping | Shopping malls, retail centers, shopping complexes |
+| Office | Office buildings, business parks, co-working spaces |
+| Sports | Stadiums, arenas, sports venues, fitness centers |
+| Entertainment | Cinemas, theaters, amusement parks, recreation centers |
+| Restaurant | Dining establishments, cafes, food courts |
+| Hotel | Hospitality establishments, resorts |
+| Hospital | Medical facilities, healthcare centers, clinics |
+| Education | Schools, universities, colleges, training centers |
+| Transit | Bus terminals, train stations, metro stops, airports |
+| Retail | Individual retail stores, supermarkets, convenience stores |
+| Custom | User-defined POIs created in the Custom POI management section |
+
+**Custom POIs**
+
+Users can also create their own Points of Interest through the Configuration > Custom POIs section. Custom POIs appear in the POI search alongside standard POIs and include:
+- Custom name and category
+- Latitude/longitude coordinates
+- Address and radius settings
+- Enabled/disabled status
+
+**Income Bracket**
+
+Select target income levels:
+
+| Income Level | Range |
+|--------------|-------|
+| Low income | < RM 128,000 |
+| Lower-middle income | RM 128,000 - RM 213,000 |
+| Middle income | RM 213,000 - RM 426,000 |
+| Upper-middle income | RM 426,000 - RM 639,000 |
+| High income | > RM 639,000 |
+
+**Behavior**
+
+Select behavioral segments:
+
+| Behavior | Description |
+|----------|-------------|
+| Commuters | People traveling to/from work |
+| Shoppers | Active shoppers in retail environments |
+| Tourists | Visitors in key destinations |
+| Business Travelers | Professional travelers |
+| Students | University and college students |
+| Families | Family groups |
+| Health Seekers | People visiting medical facilities |
+| Fitness Enthusiasts | Active individuals near gyms |
+
+**Interest**
+
+Select interest categories:
+- Sports & Fitness
+- Technology
+- Fashion & Style
+- Food & Dining
+- Travel
+- Music
+- Automotive
+- Entertainment
+- Home & Garden
+- Health & Wellness
+
+**Signals** *(Conditional Automation)*
+
+Signals enable dynamic ad targeting based on real-time conditions:
+
+| Signal Type | Description |
+|-------------|-------------|
+| Weather | Show ads based on weather conditions |
+| Search | Target based on search keyword trends |
+| Footfall | Adjust delivery based on foot traffic |
+| Audiences | Target based on audience segments |
+
+#### Section 4: DOOH Inventory Type
+
+**Section Title:** "DOOH Inventory Type"  
+**Section Description:** "Configure inventory source and format preferences"
+
+This section uses a summary row pattern where each row displays the current selection and can be clicked to expand or open a drawer for detailed selection.
+
+**SSP / Exchange** *(View-Only)*
+
+Displays the SSP inherited from the parent deal. This is automatically set based on the deal configuration and cannot be changed at the line item level.
+
+**Media Owner Selection**
+
+Clicking the Media Owner row opens a side drawer for selecting media owners. The drawer includes:
+- **Search bar**: Filter media owners by name
+- **Country filter**: Filter by country (e.g., Malaysia, Singapore, Thailand, Indonesia)
+- **Business type filter**: Filter by business type (e.g., Media Owner, Retail Chain, Property Developer, Transit Authority)
+- **Media owner list**: Checkboxes for each available media owner
+- **Selected count**: Shows number of selected media owners
+- **Fixed footer**: "Apply Selection" and "Cancel" buttons
+
+**Inventory Type** *(Collapsible)*
+
+A collapsible section showing "X types selected" in the summary row. When expanded, displays checkboxes for inventory types:
+- OOH (Out-of-Home billboards and displays)
+- Transit (transportation-related screens)
+- Retail (in-store and shopping displays)
+- Cinema (movie theater screens and lobbies)
+
+**Venue Type Selection**
+
+Clicking the Venue Type row opens a side drawer for selecting venue types based on the OpenOOH/IAB 3.1 taxonomy. The drawer provides a hierarchical tree view of venue categories.
+
+**Venue Type Drawer**
+
+The drawer includes:
+- **Search bar**: Filter venues by name across all hierarchy levels
+- **Hierarchical tree view**: Expandable categories showing parent-child relationships
+- **Tier badges**: Visual indicators (T1, T2, T3, T4) showing taxonomy depth
+- **Select all/Deselect all per category**: Quick selection toggles for each parent category
+- **Checkbox selection**: Individual venue type selection
+- **Selected count**: Shows total number of selected venue types
+- **Fixed footer**: "Apply Selection" and "Cancel" buttons
+
+**OpenOOH Venue Taxonomy**
+
+The taxonomy organizes venues into 8 parent categories with 3-4 tier hierarchy:
+
+| Parent Category | Example Child Venues |
+|-----------------|---------------------|
+| Retail | Shopping Malls, Supermarkets, Convenience Stores, Department Stores |
+| Transit | Airports, Train Stations, Bus Terminals, Metro Stations |
+| Outdoor | Billboards, Street Furniture, Urban Panels |
+| Health & Beauty | Gyms, Salons, Spas, Pharmacies |
+| Point of Care | Hospitals, Clinics, Medical Centers |
+| Education | Universities, Schools, Libraries |
+| Office Buildings | Lobbies, Elevators, Common Areas |
+| Residential | Apartment Complexes, Condominiums |
+
+Each venue type displays its tier level, allowing users to select at any granularity from broad categories (T1) to specific venue types (T3/T4).
+
+**Inventory Format**
+
+Clicking the Inventory Format row opens a side drawer for selecting screen formats. The drawer groups formats by DOOH type:
+
+| Type | Available Formats |
+|------|-------------------|
+| OOH | Digital Large Format, Digital Billboard, Digital Bus Shelter Screen, Smart City Panel, Digital Video Walls, Digital Kiosk |
+| Transit | Taxi Top Digital, Platform Digital Screen, Airport Terminal Screens, Train Digital Display, Bus Interior Screen, Metro Station Screen |
+| Retail | Mall / Retail Screens, Cinema Pre-Show / Lobby, Elevator / Lobby Screens, Retail Window Screen, Point of Sale Screen, Shelf-edge Digital |
+| Cinema | Cinema Pre-Show, Cinema Lobby Screen, Premium Format Screen |
+
+The drawer includes:
+- **Grouped checkbox lists**: Formats organized by inventory type
+- **"Select All" per group**: Quick selection toggle for each type
+- **Selected count**: Shows number of selected formats
+- **Fixed footer**: "Apply Selection" and "Cancel" buttons
+
+**Resolution** *(Collapsible)*
+
+A collapsible section for screen resolution filtering:
+- 1920x1080 (Full HD)
+- 3840x2160 (4K)
+- 2560x1440 (QHD)
+- 1280x720 (HD)
+
+#### Section 5: AI Inventory Recommendations
+
+This section provides AI-powered inventory recommendations using the Recommendation Engine V2.
+
+**AI Recommendation Panel**
+
+Located in the right sidebar, the AI Recommendation Panel displays:
+- **Section header**: "AI Recommendations" with sparkle icon
+- **Recommendation score badge**: Overall match percentage (e.g., "87% Match")
+- **8-factor score breakdown**: Visual indicators for each scoring factor
+- **Recommended screens list**: AI-suggested inventory with justifications
+
+**8-Factor Scoring System**
+
+The recommendation engine evaluates inventory based on:
+
+| Factor | Description |
+|--------|-------------|
+| Measure Fit | Alignment with campaign measurement goals |
+| Geo Fit | Geographic proximity to target locations |
+| Availability | Screen availability during campaign period |
+| Budget Fit | Cost efficiency relative to budget constraints |
+| Audience Fit | Match with target demographic profiles |
+| Brand Fit | Suitability for brand guidelines and positioning |
+| Quality Fit | Screen quality, resolution, and placement quality |
+| Time Fit | Daypart and timing alignment with campaign goals |
+
+Each factor displays a score from 0-100% with color-coded indicators.
+
+**AI Actions**
+
+- **"Add X Screens" button**: Adds all AI-recommended screens to the selection
+- **"Auto-Optimize" button**: Applies AI optimization to the entire line item
+- **Individual screen selection**: Add/remove individual screens from recommendations
+
+**Manual Inventory Edit Drawer**
+
+Clicking "Edit Selection" opens a 75% width drawer for manual inventory management:
+
+**Left Panel (Inventory List):**
+- Search bar for filtering screens
+- Filter controls (format, resolution, status)
+- Scrollable list of available screens with:
+  - Screen name and location
+  - Format and resolution info
+  - Availability status
+  - Checkbox for selection
+
+**Right Panel (Map View):**
+- Interactive Mapbox map
+- Screen markers showing locations
+- Cluster markers for dense areas
+- Click-to-select functionality
+
+**Fixed footer:**
+- Selected screens count
+- "Apply Selection" and "Cancel" buttons
+
+**Inventory Availability**
+
+When screens are selected (either manually or via AI recommendations), an availability summary section appears showing the booking status of selected inventory.
+
+**Availability Summary Row**
+
+Displays:
+- **Availability percentage**: Overall availability across all selected screens (e.g., "85% Available")
+- **Status counts**: Number of screens in each availability state (Available, Partially Available, Sold Out)
+- **Color indicators**: Green for available, yellow for partial, red for sold out
+
+**Availability Drawer**
+
+Clicking the availability row opens a drawer with a Gantt-chart style timeline view:
+
+**Timeline Controls:**
+- **Month/Week toggle**: Switch between monthly and weekly timeline granularity
+- **Zoom controls**: Zoom in/out on the timeline
+- **Date range**: Shows the line item's flight dates
+
+**Gantt Chart View:**
+- **Screen rows**: Each selected screen displayed as a row
+- **Time axis**: Horizontal timeline matching the line item's flight dates
+- **Booking blocks**: Color-coded blocks showing existing bookings
+  - **Available** (green): No bookings during this period
+  - **Booked** (gray): Screen is booked by another campaign
+  - **Own Booking** (blue): Booked by current campaign
+- **Hover tooltips**: Show booking details on hover
+
+The timeline uses seeded random data (based on screen ID) to ensure consistent visualization across page refreshes.
+
+#### Section 6: Flight Dates
+
+This section configures the campaign flight dates with quick selection options for common durations.
+
+**Quick Date Selection**
+
+A row of quick-select buttons enables single-click date range configuration:
+- **Next 7 days**: Sets start date to today, end date to today + 7 days
+- **Next 28 days**: Sets start date to today, end date to today + 28 days
+- **Next 30 days**: Sets start date to today, end date to today + 30 days
+- **Next 45 days**: Sets start date to today, end date to today + 45 days
+- **Next 60 days**: Sets start date to today, end date to today + 60 days
+
+These buttons automatically populate both Start Date and End Date fields for common campaign durations.
+
+**Start Date** *(Required)*
+
+Must fall within the parent deal's flight dates.
+
+**End Date** *(Required)*
+
+Must be after the start date and not exceed the parent deal's end date.
+
+#### Section 7: Budget Options
+
+This section contains all budget-related configuration options, including the total budget which only appears when unlimited budget is disabled.
+
+**Unlimited Budget**
+
+Toggle switch that when enabled, removes the budget cap for the line item. This is the first option in the section, allowing users to decide if budget constraints apply before entering budget values.
+
+**Budget** *(Conditional - Required when Unlimited Budget is OFF)*
+
+Only displayed when the Unlimited Budget toggle is OFF. Maximum spend allocated to this line item. The budget field displays with an inline currency badge showing the currency inherited from the parent deal. The currency is read-only with a lock icon indicating it cannot be changed at the line item level.
+
+**Budget Consumption**
+
+Controls how the budget is consumed over time:
+
+| Consumption Type | Description |
+|------------------|-------------|
+| Daily | Budget is allocated and consumed on a daily basis |
+| Weekly | Budget is allocated and consumed on a weekly basis |
+| Monthly | Budget is allocated and consumed on a monthly basis |
+| Lifetime | Budget is consumed over the entire flight period |
+
+**Daily Budget**
+
+Optional daily budget cap to control daily spend. The field label displays the inherited currency code.
+
+#### Section 8: Pacing & Traffic Allocation *(Programmatic Deals Only)*
+
+This section is only visible for programmatic deal types and controls delivery distribution.
+
+**Pacing**
+
+Controls delivery distribution:
+
+| Pacing Type | Description |
+|-------------|-------------|
+| ASAP | Deliver as fast as possible |
+| Even | Spread delivery evenly (default) |
+| Front Loaded | Deliver more early in the flight |
+
+**Traffic Allocation**
+
+A slider from 0% to 100% (default: 100%) controlling share of deal traffic. The slider includes visual indicators showing the current allocation percentage.
+
+#### Section 9: Day Parting
+
+Configures hourly scheduling for ad delivery. The section contains a 24-hour grid where users can select which hours of the day ads should be delivered. This allows campaigns to target specific times when the target audience is most likely to be present.
+
+#### Section 10: Billing
+
+**Billable Status**
+
+Radio button selection:
+- **Non-Billable**: Line item is for testing or bonus delivery
+- **Billable**: Line item is included in billing reports
+
+#### Section 11: Budget & Delivery (Legacy Reference)
+
+**Hard Stop** *(View-Only, PG Deals Only)*
+
+For line items under Programmatic Guaranteed deals, displays the Hard Stop setting inherited from the parent deal with a "From Deal" badge.
+
+**Currency** *(View-Only)*
+
+Displays the currency inherited from the parent deal with a "From Deal" badge and lock icon. Currency cannot be changed at the line item level - it automatically follows the deal's currency setting.
+
+**Budget**
+
+Maximum spend allocated to this line item.
+
+**Budget Consumption**
+
+Controls how the budget is consumed over time:
+
+| Consumption Type | Description |
+|------------------|-------------|
+| Daily | Budget is allocated and consumed on a daily basis |
+| Weekly | Budget is allocated and consumed on a weekly basis |
+| Monthly | Budget is allocated and consumed on a monthly basis |
+| Lifetime | Budget is consumed over the entire flight period |
+
+**Daily Budget**
+
+Optional daily budget cap to control daily spend.
+
+**Pacing**
+
+Controls delivery distribution:
+
+| Pacing Type | Description |
+|-------------|-------------|
+| ASAP | Deliver as fast as possible |
+| Even | Spread delivery evenly (default) |
+| Front Loaded | Deliver more early in the flight |
+
+**Traffic Allocation**
+
+A slider from 0% to 100% (default: 100%) controlling share of deal traffic.
+
+#### Section 8: Bid Strategy
+
+**Automated Bidding**
+
+Toggle to let the system automatically optimize bid amounts.
+
+**Max Bid ($)**
+
+Maximum bid amount for this line item. The system suggests a max bid based on the average CPM of selected screens or inventory filters. Users can apply the suggestion or enter a custom value.
+
+**Auto-Calculated Max Bid**
+
+When screens are selected or inventory filters are configured, the system calculates a suggested max bid:
+- **CPM**: Average CPM of selected screens
+- **CPS**: Derived from average CPM (CPM / 1000 / creative duration)
+
+**Bid Type**
+
+| Type | Description |
+|------|-------------|
+| CPM | Cost Per Mille - price per 1,000 impressions |
+| CPS | Cost Per Second - price based on ad duration |
+
+#### Section 9: Advanced Options
+
+**Custom Fees**
+
+Repeatable section for adding fees:
+- Name
+- Amount
+- Type (Fixed or Percentage)
+- Hidden toggle
+
+**Frequency Cap**
+
+Controls ad exposure frequency:
+- Impressions (max per period)
+- Period (Hour, Day, Week, Month, Lifetime)
+
+### 5.3 Line Item Forecasting Panel
+
+The right side of the line item form displays a contextual forecasting panel that updates in real-time.
+
+**Budget vs Cost Comparison**
+
+| Metric | Description |
+|--------|-------------|
+| Deal Budget | The total budget from the parent deal |
+| Line Item Budget | The budget allocated to this line item |
+| Estimated Cost | Calculated based on max bid and target impressions |
+
+**Cost Calculation Formulas**
+
+- **CPM**: `Cost = (Target Impressions ÷ 1000) × Max Bid`
+- **CPS**: `Cost = Target Impressions × Creative Duration × Max Bid`
+
+**Budget Status Indicator**
+
+- **Green**: Estimated cost is within budget
+- **Red (pulsing)**: Estimated cost exceeds budget
+
+### 5.4 Delivery Tracking
+
+Each line item shows delivery progress prominently.
+
+**Delivered Impressions**
+
+Counter that increases with each screen playback.
+
+**Delivery Percentage**
+
+Calculated as: (Delivered Impressions ÷ Target Impressions) × 100
+
+**Pacing Status**
+
+- **On Track** (green): Within 10% of expected
+- **Behind** (yellow): 10-25% below expected
+- **At Risk** (red): More than 25% below expected
+- **Ahead** (blue): More than 10% above expected
+
+### 5.5 Pausing and Resuming
+
+Line items can be paused independently of their parent deal.
+
+**To pause:** Click the three-dot menu and select "Pause Line Item"
+
+**What happens when paused:**
+- Line item stops participating in ad selection
+- Delivery metrics freeze
+- Other line items may receive more traffic
+
+**To resume:** Click the three-dot menu and select "Resume Line Item"
+
+### 5.6 Form Insights and Quick Tips
+
+The line item form includes a dynamic Form Insights Panel that provides contextual guidance based on the current scroll position. The panel appears in the right sidebar alongside the AI Recommendation Panel and automatically updates its content as the user scrolls through different sections of the form.
+
+**Scroll-Based Section Detection**
+
+The form tracks five main sections:
+1. **Basic Details** - Line item name, status, and general configuration
+2. **Targeting** - Demographics, geography, POI, venue type, and audience targeting
+3. **Inventory** - DOOH inventory type, media owners, and screen selection
+4. **Schedule** - Flight dates and daypart settings
+5. **Budget** - Budget allocation, pacing, and pricing
+
+As the user scrolls, the Form Insights Panel header updates to show the current section name and displays section-specific insights.
+
+**Section-Specific Insights**
+
+| Section | Sample Insights |
+|---------|-----------------|
+| Basic Details | "A clear, descriptive name helps identify line items in reports" |
+| Targeting | "Targeting determines audience reach - broader targeting increases potential impressions but may reduce relevance" |
+| Inventory | "Select inventory that aligns with your target audience locations" |
+| Schedule | "Flight dates should fall within the parent deal's date range" |
+| Budget | "Budget pacing affects delivery distribution - Even pacing provides consistent exposure" |
+
+**Quick Tips**
+
+Each section includes practical recommendations:
+- **Basic Details**: "Use naming conventions that include creative type and targeting approach"
+- **Targeting**: "Start with broader targeting and narrow based on performance"
+- **Inventory**: "AI recommendations consider 8 factors including audience fit and availability"
+- **Schedule**: "Consider dayparting to reach audiences at optimal times"
+- **Budget**: "Higher priority ensures delivery for premium campaigns"
+
+**Visibility Behavior**
+
+The Form Insights Panel is hidden after a forecast is generated to maximize space for the forecasting results. This ensures users can focus on reviewing forecast data without distraction.
+
+---
+
+## 6. Traffic Allocation
+
+Traffic allocation controls how available advertising opportunities are divided among competing line items within a deal.
+
+### 6.1 Basic Concept
+
+Imagine a screen that can show 1,000 ads per day. Two line items want to advertise on that screen at the same time. Line Item A has 70% allocation and Line Item B has 30%.
+
+Each time the screen is ready to show an ad, the system uses traffic allocation percentages to make a weighted random decision. Over the day, Line Item A will receive approximately 700 impressions and Line Item B approximately 300.
+
+This approach is flexible because it handles situations where one line item's creative is unavailable by automatically giving more opportunities to others.
+
+### 6.2 Normalization Logic
+
+Traffic allocation percentages are relative weights, not absolute guarantees.
+
+**Example 1: Equal Weights**
+
+Two line items both set their traffic allocation to 100%.
+
+The system normalizes:
+- Line Item A: 100 ÷ (100 + 100) = 50%
+- Line Item B: 100 ÷ (100 + 100) = 50%
+
+**Example 2: Weighted Split**
+
+Line Item A is set to 80% and Line Item B is set to 40%.
+
+The system normalizes:
+- Line Item A: 80 ÷ (80 + 40) = 66.67%
+- Line Item B: 40 ÷ (80 + 40) = 33.33%
+
+**Why normalization?**
+
+Normalization allows users to think in terms of relative importance. If a new line item is added or an existing one is paused, the remaining line items automatically adjust.
+
+**Default Allocation for Auto-Created Line Items**
+
+When line items are automatically created from external systems such as Planner (see Section 10.2), each line item is assigned a traffic allocation of 100% by default. Because normalization is applied at delivery time, multiple line items each set to 100% will share traffic equally. For example, if Planner creates five line items (one per media owner), each set to 100%, the normalized effective allocation becomes 20% per line item. This default can be adjusted within Influence after the deal is created if different weighting is desired.
+
+### 6.3 Priority as Tiebreaker
+
+When two line items have similar allocations and both are eligible for the same impression, priority breaks the tie.
+
+The line item with the lower priority number (higher priority) is considered first. Priority 1 always takes precedence over Priority 5.
+
+However, priority does not override allocation entirely. A Priority 1 line item with 10% allocation will not take 100% of impressions—it receives its allocated 10%, but within that 10%, it gets first consideration.
+
+**Priority Behavior by Deal Type**
+
+| Deal Type | Priority Behavior |
+|-----------|-------------------|
+| Traditional | Priority strictly enforced for guaranteed delivery |
+| PG | Priority determines allocation order for guaranteed impressions |
+| Preferred Deal | Priority influences first-look order |
+| PMP | Priority affects auction sequence |
+| Always On | Priority less critical but still applies when inventory is limited |
+
+### 6.4 Worked Examples
+
+**Example: Three Line Items in a Deal**
+
+Deal has three line items:
+- Line Item A: 60% allocation, Priority 2
+- Line Item B: 30% allocation, Priority 1
+- Line Item C: 10% allocation, Priority 3
+
+Effective allocations after normalization:
+- A: 60%, B: 30%, C: 10%
+
+When competing for an impression:
+1. B is considered first (Priority 1)
+2. If B is unavailable, A is considered (Priority 2)
+3. If A is unavailable, C is considered (Priority 3)
+
+Over time, impressions distribute approximately 60/30/10.
+
+---
+
+## 7. Content Hub
+
+The Content Hub is the central repository for all creative assets used in advertising campaigns.
+
+### 7.1 Overview
+
+Content Hub allows users to:
+- Upload creative assets (images, videos, HTML5)
+- Organize creatives into folders
+- Submit creatives for Tier 1 approval
+- Assign approved creatives to line items
+
+### 7.2 Creative Types
+
+| Type | Formats | Description |
+|------|---------|-------------|
+| Display | JPEG, PNG | Static image advertisements |
+| Video | MP4, WebM | Moving picture advertisements |
+| HTML5 | ZIP package | Interactive rich media |
+
+#### Creative Source
+
+Creatives can originate from different sources, which is tracked for reporting and workflow purposes:
+
+| Source | Description |
+|--------|-------------|
+| Uploaded | Manually uploaded through the Content Hub interface |
+| Bid Stream (VAST) | Received via VAST tags from DSP bid responses |
+| API | Programmatically uploaded via API integration |
+| Media Owner | Uploaded by the media owner for their inventory |
+
+**Source Platform Tracking:**
+
+In addition to the creative source type, the system tracks which platform originated the creative:
+
+| Platform | Description |
+|----------|-------------|
+| Influence | Created directly in the Influence platform |
+| Planner | Sent from the Planner platform via API |
+| Activate | Received from the Activate platform via bid stream |
+| Media Owner | Uploaded by the media owner |
+
+**Display Format:**
+
+The creative source is displayed in a combined format showing "Platform - Source Type":
+- **Influence creatives**: Display source type only (e.g., "Uploaded", "API")
+- **External platform creatives**: Display "Platform - Source Type" (e.g., "Planner - API", "Activate - Bid Stream")
+
+This source information is visible in:
+- The Content Hub preview panel
+- The Line Item Creatives listing (Source column)
+- The Edit Creative Assignment page (Metadata panel)
+
+#### Transcoding
+
+Video creatives may require transcoding to meet different screen specifications:
+
+**Transcoding Status Values:**
+| Status | Description |
+|--------|-------------|
+| Pending | Transcoding has been requested but not yet started |
+| Processing | Transcoding is currently in progress |
+| Completed | Transcoding completed successfully, transcoded file available |
+| Failed | Transcoding failed, requires manual intervention |
+
+When transcoding is enabled for a creative:
+- The system automatically processes the video to meet various screen format requirements
+- The transcoding status is displayed in the creative preview panel
+- Once completed, the transcoded URL is available for playback on compatible screens
+
+### 7.3 Status Workflow
+
+Creatives progress through these statuses:
+
+| Status | Description |
+|--------|-------------|
+| Pending | Newly uploaded, awaiting review |
+| In Review | Currently being reviewed |
+| Accepted | Passed Tier 1 approval, ready for assignment |
+| Inadequate | Failed review, needs revision |
+
+### 7.4 Folder Organization
+
+Creatives can be organized into folders for easy management. Folders support:
+- Hierarchical nesting
+- Drag-and-drop reorganization
+- Bulk operations
+
+**Content Hub Filter Drawer**: The Content Hub includes a filter drawer with the following options:
+- **Status**: Filter by creative status (Pending, In Review, Accepted, Inadequate, Archived)
+- **Type**: Filter by creative type (Display, Video, HTML, Native)
+- **Folder**: Filter by folder assignment
+
+### 7.5 Preview and Approval
+
+Each creative has:
+- Full-size preview
+- Technical specifications display
+- Approval/rejection controls
+- Comment thread for feedback
+
+### 7.6 Creative Assignment
+
+#### 7.6.1 Line Item Creatives Page
+
+Accessed from line item detail, shows all assigned creatives with:
+- Preview thumbnails
+- Rotation weights
+- Tier 2 approval status
+- Schedule information
+
+**Line Item Creatives Filter Drawer**: The assigned creatives list includes a filter drawer with:
+- **Approval Status**: Filter by Tier 2 approval status (Pending, Approved, Rejected, Changes Requested)
+- **Creative Type**: Filter by creative type (Display, Video, HTML, Native)
+- **Scheduling Rule**: Filter by scheduling rule (Default, Custom)
+
+#### 7.6.2 Edit Creative Assignment Page
+
+Allows editing of:
+- Schedule matrix (hours × days)
+- Rotation rule (default, exclusive)
+- Weight percentage
+
+#### 7.6.3 Assign Creative Page
+
+Browse Content Hub to select creatives:
+- Only Tier 1 Accepted creatives are shown
+- Multiple selection supported
+- Automatic validation of format compatibility
+
+### 7.7 Tier 2 Approval Workflow
+
+When creatives are assigned to a line item, they enter Tier 2 approval where the Media Owner validates compatibility with target screens.
+
+**Tier 2 Statuses:**
+
+| Status | Description |
+|--------|-------------|
+| Pending | Awaiting media owner review |
+| Approved | Validated for delivery |
+| Rejected | Not compatible with screens |
+| Changes Requested | Needs modification |
+
+**Media Owner Approval Interface:**
+
+The Edit Creative Assignment page provides a dedicated "Media Owner Approval" section where media owners can:
+- View the current approval status
+- Preview the creative (video playback or image display)
+- Review creative metadata (resolution, duration, source platform)
+- Take approval actions via dedicated buttons:
+  - **Approve**: Marks the creative as validated for delivery
+  - **Request Changes**: Requests modifications from the creative owner
+  - **Reject**: Marks the creative as not compatible with screens
+
+When an approval action is taken:
+- The status updates immediately with visual feedback
+- A timestamp is recorded for audit purposes
+- The change is logged in the History drawer
+
+**Blocking Delivery**
+
+Line items require at least one Tier 2 Approved creative before they can deliver impressions.
+
+---
+
+## 8. Signals (Conditional Automation)
+
+### 8.1 Overview
+
+Signals enable conditional automation for line item control based on external data sources.
+
+### 8.2 Signal Types
+
+- **Audiences**: Signal based on audience segment targeting
+- **Footfall**: Signal based on store foot traffic
+- **Search**: Signal based on search keyword trends
+- **Weather**: Signal based on weather conditions
+
+### 8.3 Signal Rules
+
+Each signal contains one or more rules specific to the signal type:
+
+**Footfall Rules:**
+- Brand selection
+- Store locations
+- Min/Max Busy % parameters
+
+**Weather Rules:**
+- Location selection
+- Condition types (Temperature Above, Below, Weather Condition)
+- Value parameters
+
+### 8.4 Forecasting Visualizations
+
+- **Footfall**: Weekly heatmap
+- **Weather**: Line graph with predictions
+- **Audiences**: Bar chart
+- **Search**: Trend line chart
+
+### 8.5 Signal-Line Item Integration
+
+- Line items link to signals via signalId
+- When signalEnabled is true, the signal controls activation
+- Signal indicator shown in line items table
+
+### 8.6 UI/UX
+
+- Signals page accessible from sidebar (Zap icon)
+- Two-column form layout
+- Inline rule management
+- Type-specific rule forms
+
+### 8.7 Quick Tips Panel
+
+Signal-specific guidance:
+
+**Footfall Signals**: Activate based on real-time visitor density
+**Weather Signals**: Trigger based on weather conditions
+**Audience Signals**: Activate for specific customer segments
+**Search Signals**: Respond to keyword trends
+
+---
+
+## 9. Ad Serving Process
+
+This section explains how advertisements reach screens in the Influence ecosystem. There are two distinct delivery channels, each designed for different operational scenarios. Understanding both channels is essential because in a real-world deployment, some screens will use one channel and some will use the other — and many networks will use both simultaneously.
+
+### 9.1 The Two Delivery Channels
+
+Influence delivers ads to screens through two channels:
+
+1. **Channel A — Decision Engine (DE)**: An intelligent, real-time decisioning system that sits between the player and the ad server. The Decision Engine is a **separate external microservice** — it is not part of the Influence Adserver application itself, but communicates with it via shared Redis state and API callbacks. The player asks "what should I play next?" and the Decision Engine decides. The player does not need to know about individual deals or line items in advance.
+
+2. **Channel B — VAST Tag Distribution**: A manual distribution model where the Influence user exports VAST tags (URLs, HTML files, or ZIP packages) from the platform and hands them to media owners. The media owner's CMS schedules those tags on specific screens. The CMS controls what plays and when.
+
+Both channels ultimately serve the same creatives from the same deals and line items. The difference is *who decides* what plays on a given screen at a given moment.
+
+**When to use which channel:**
+
+| Scenario | Channel | Why |
+|----------|---------|-----|
+| Screens in your own network with DE-enabled players | Decision Engine | Maximum yield and pacing intelligence |
+| Third-party media owner screens (Broadsign, Scala, etc.) | VAST Distribution | Media owner controls their own CMS |
+| Screens with no internet reliability | VAST Distribution (ZIP) | Offline fallback with buffered content |
+| Mixed network with guaranteed + programmatic demand | Decision Engine | DE arbitrates between deal types in real-time |
+| Simple traditional campaign on partner screens | VAST Distribution (URL) | Easiest integration, no DE setup needed |
+
+#### Diagram: Dual-Channel Ad Delivery Architecture
+
+```
+                                    INFLUENCE PLATFORM
+                                 ┌──────────────────────┐
+                                 │   Deals & Line Items  │
+                                 │   Creatives & Rules   │
+                                 │   Budget & Pacing     │
+                                 └──────┬───────┬────────┘
+                                        │       │
+                        ┌───────────────┘       └────────────────┐
+                        │                                        │
+               CHANNEL A: DE                            CHANNEL B: VAST
+          (Dynamic / Intelligent)                   (Manual / Static Distribution)
+                        │                                        │
+                        ▼                                        ▼
+            ┌───────────────────┐                  ┌──────────────────────┐
+            │  Decision Engine  │                  │  Distribution Tab    │
+            │  ┌─────────────┐  │                  │  (Deal Detail Page)  │
+            │  │ Redis State │  │                  │                      │
+            │  │ (Pacing,    │  │                  │  Export as:          │
+            │  │  Budgets,   │  │                  │  - VAST URL          │
+            │  │  SOV, Caps) │  │                  │  - HTML File         │
+            │  └─────────────┘  │                  │  - ZIP Package       │
+            └────────┬──────────┘                  └──────────┬───────────┘
+                     │                                        │
+                     ▼                                        ▼
+          ┌─────────────────┐                     ┌──────────────────────┐
+          │  Player calls   │                     │  Media owner pastes  │
+          │  DE endpoint    │                     │  VAST tag into their │
+          │  with screen ID │                     │  CMS (Broadsign,     │
+          │  every 15-30min │                     │  Scala, etc.)        │
+          └────────┬────────┘                     └──────────┬───────────┘
+                   │                                         │
+                   ▼                                         ▼
+          ┌─────────────────┐                     ┌──────────────────────┐
+          │  DE returns a   │                     │  CMS calls VAST URL  │
+          │  manifest:      │                     │  per its own         │
+          │  "Play Deal A,  │                     │  schedule/rotation   │
+          │   then Deal B,  │                     │                      │
+          │   then Deal C"  │                     │  Each call = 1 ad    │
+          └────────┬────────┘                     └──────────┬───────────┘
+                   │                                         │
+                   ▼                                         ▼
+          ┌─────────────────┐                     ┌──────────────────────┐
+          │  Player follows │                     │  Influence returns   │
+          │  the manifest   │                     │  VAST XML with       │
+          │  sequence and   │                     │  creative + tracking │
+          │  fires tracking │                     │  pixels              │
+          │  heartbeats     │                     │                      │
+          └─────────────────┘                     └──────────────────────┘
+```
+
+<p align="center"><em>Figure 5: Dual-Channel Ad Delivery Architecture</em></p>
+
+### 9.2 Channel A — Decision Engine
+
+The Decision Engine (DE) is a high-concurrency, low-latency microservice that replaces static round-robin playback with intelligent, multi-factor ad selection. It is the "brain" that sits between the player and the ad server, deciding in real-time which ad should play next on any given screen.
+
+#### 9.2.1 Why the Decision Engine Exists
+
+Without the Decision Engine, DOOH networks operate on fixed-loop (round-robin) logic where all ad slots are treated as equal units of time. This creates four critical problems:
+
+1. **No deal-type awareness.** The system cannot distinguish between a "must-run" Traditional/PG deal (which has a contractual delivery guarantee) and a "can-run" Programmatic deal (which competes on price). This leads to manual ad-ops overrides or missed revenue opportunities.
+
+2. **No pacing intelligence.** The player shows ads at the same rate at 2:00 AM as it does at 6:00 PM. A campaign that is behind schedule during peak hours will under-deliver, and the system has no mechanism to catch up.
+
+3. **No auction cascading.** In Private Marketplace (PMP) deals, if the primary buyer fails to respond or bids below the floor, the system gives up rather than cascading to the next eligible buyer. The slot goes empty.
+
+4. **Stale delivery data.** Delivery stats (impressions, spend) are updated in batches. Without real-time state tracking, the engine makes decisions based on outdated data, causing over-delivery and budget overruns.
+
+#### 9.2.2 How the Decision Engine Works
+
+The Decision Engine processes each request through a three-stage pipeline:
+
+**Stage 1 — Hard Filtering (Validation)**
+
+Eliminate candidates that cannot legally serve. This includes checking flight dates (is the campaign currently active?), creative specifications (does the creative match the screen's resolution and orientation?), budget limits (has the daily or total budget been exhausted?), and geographic eligibility (is this screen in the campaign's target region?).
+
+**Stage 2 — Prioritization (Deal Type Separation)**
+
+Separate deterministic demand from probabilistic demand. Traditional and Programmatic Guaranteed (PG) deals have contractual obligations — they *must* deliver a specific number of impressions. Preferred Deals (PD) and Private Auctions (PMP) compete on price but have no hard delivery guarantee. The engine considers guaranteed deals first, then opens remaining slots to programmatic competition.
+
+**Stage 3 — Dynamic Scoring**
+
+For each eligible candidate, the engine computes a weighted score based on multiple real-time factors:
+
+| Factor | Description | Example |
+|--------|-------------|---------|
+| Pacing Deficit | How far behind is this campaign on its delivery goal? | Campaign at 40% delivery but 60% through its flight dates gets a boost |
+| CPM / Yield | What is the revenue per impression? | A $35 CPM deal scores higher than a $12 CPM deal for yield maximization |
+| Priority | The line item's configured priority (1-10) | Priority 1 always considered before Priority 5 |
+| Share of Voice (SOV) | Is the campaign meeting its guaranteed SOV percentage? | A deal guaranteed 20% SOV but currently at 12% gets a significant boost |
+| Budget Velocity | How fast is the budget being consumed relative to remaining flight? | Near-exhaustion campaigns are slowed down to prevent overspend |
+| Time-of-Day Value | Is this a peak traffic hour? | High-value slots during rush hour are allocated to higher-CPM deals |
+| Frequency Cap | Has this screen already shown this ad too many times today? | Capped campaigns are deprioritized after reaching their limit |
+| Recency Cooldown | When was this creative last played on this screen? | Creatives played recently get a cooldown penalty to prevent repetition |
+
+The candidate with the highest composite score wins the slot.
+
+#### 9.2.3 The Hybrid Manifest Approach
+
+Rather than asking the Decision Engine for every single ad slot (which would generate 20,000+ requests per minute across a 5,000-screen network) or downloading a static 24-hour playlist (which loses all flexibility), Influence uses a hybrid approach:
+
+**Every 15 to 30 minutes**, the player requests a "manifest" — a pre-computed sequence of ads to play during that window. The Decision Engine runs its scoring logic and returns a VAST-wrapped manifest containing multiple ad slots.
+
+This approach balances three concerns:
+
+- **Scale**: API load is reduced by ~98% compared to per-spot requests. A 5,000-screen network generates ~300 requests per minute instead of 20,000.
+- **Yield**: New programmatic demand can be injected into the rotation every 15-30 minutes, which is more than sufficient for DOOH buyers who plan in hours, not seconds.
+- **Resilience**: If the internet connection drops, the player continues showing ads from its current manifest. No black screens, no frozen displays.
+
+**The manifest lifecycle:**
+
+1. **Request**: The player sends its screen reference ID to the Decision Engine endpoint.
+2. **Decision**: The DE runs its three-stage pipeline and builds a sequence of ads for the next 15-30 minutes.
+3. **Execution**: The player consumes the manifest in order, playing each ad for its specified duration.
+4. **Heartbeat**: After each ad plays, the player fires an async tracking pixel to update Redis counters in near real-time.
+5. **Correction**: When the player requests the next manifest, the DE adjusts scores based on the heartbeats it received, ensuring pacing stays accurate.
+
+#### 9.2.4 Decision Engine Scenarios
+
+The following table illustrates how the Decision Engine handles real-world situations compared to a legacy fixed-rotation system:
+
+| Scenario | Legacy System (Round-Robin) | Decision Engine |
+|----------|-----------------------------|-----------------|
+| 2 PG Deals, equal priority | Alternates 1:1 regardless of remaining goal | Prioritizes the PG deal with the highest delivery deficit |
+| 1 PG vs. 2 PD Deals | Rotates all three equally (33% each) | Forces PG until pacing is healthy, then allows PD to compete |
+| Under-delivering PG deal | No change in frequency; likely to miss goal | Applies "behind-on-delivery" boost to ensure 100% fill |
+| Peak hour traffic | Serves same rotation; wastes high-value slots | Adjusts scoring via impression multiplier to maximize yield |
+| Low traffic (midnight) | Burns limited plays on high-value deals | Deprioritizes high-CPM deals to save budget for peak hours |
+| 2 PD Deals (price competition) | Rotates 1:1 even if one pays 2x more | Favors the higher CPM deal to maximize revenue |
+| Multi-buyer PMP auction | Fails if first buyer doesn't bid; slot goes empty | Evaluates all buyers; selects highest valid bid |
+| Daily cap reached (PG) | Continues serving; over-delivers | Hard-stops the deal immediately once threshold is met |
+| SOV guarantee (min 20%) | Cannot guarantee; depends on total rotation count | Monitors real-time SOV; boosts score if below target |
+| Budget near exhaustion | Serves until API returns error; overspends | Predictive pacing slows down delivery as budget thins |
+
+#### 9.2.5 Decision Engine API
+
+The Decision Engine is deployed as a **separate external microservice** with its own base URL (e.g., `https://de.influence.io`). Its API endpoints are *not* part of the Influence Adserver's `/api` namespace. The DE reads deal, line item, and creative data from the shared database and maintains its own real-time state in Redis. Influence Adserver and the Decision Engine communicate through shared data stores, not direct API calls between each other.
+
+For the integration relationship between Influence Adserver and the Decision Engine, see [Section 10.6 — Decision Engine Integration](#106-decision-engine-integration).
+
+**Decision Request: `POST /v1/decision/simple`**
+
+The player sends a request containing its screen reference ID to the DE's base URL. Optionally, the request can include a specific `dealId` for validation mode (checking if a deal is still live and under budget) or `windowMinutes` for manifest mode.
+
+```json
+{
+  "referenceId": "MYS-MOV-D-00000-09159",
+  "dealId": "DEAL-123",
+  "windowMinutes": 20
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `referenceId` | string | Yes | The unique identifier of the screen (inventory reference) |
+| `dealId` | string | No | If provided, triggers "Validation Mode" — skips scoring, only checks if the deal is live and under budget |
+| `windowMinutes` | integer | No | If provided, triggers "Manifest Mode" — returns a sequence of ads for the specified time window |
+
+**Decision Response (Manifest Mode):**
+
+```json
+{
+  "manifestId": "MF-998877",
+  "expiresAt": "2025-10-14T15:00:00Z",
+  "sequence": [
+    {
+      "dealId": "GD-00704",
+      "lineItemId": "LI-001",
+      "duration": 15,
+      "creativeUrl": "https://cdn.influence.io/creatives/cr_abc123.mp4",
+      "trackingUrl": "https://api.influence.io/v3/track?id=1",
+      "resumeToken": "rt_xk29f"
+    },
+    {
+      "dealId": "PA-00201",
+      "lineItemId": "LI-045",
+      "duration": 15,
+      "creativeUrl": "https://cdn.influence.io/creatives/cr_def456.mp4",
+      "trackingUrl": "https://api.influence.io/v3/track?id=2",
+      "resumeToken": "rt_m83qp"
+    }
+  ]
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `manifestId` | Unique identifier for this manifest, used for logging and debugging |
+| `expiresAt` | ISO 8601 timestamp after which the player should request a new manifest |
+| `sequence` | Ordered array of ad slots to play |
+| `sequence[].dealId` | The deal this ad belongs to |
+| `sequence[].lineItemId` | The line item this ad belongs to |
+| `sequence[].duration` | How many seconds to display this ad |
+| `sequence[].creativeUrl` | Direct URL to the creative media file |
+| `sequence[].trackingUrl` | URL the player calls after the ad plays (fires the heartbeat) |
+| `sequence[].resumeToken` | If the player restarts mid-manifest, it sends this token to resume from the correct position |
+
+**Heartbeat Endpoint: `GET /v3/track`**
+
+A high-speed, lightweight listener. When called, it performs a single atomic increment in Redis for the specific deal/line item. This keeps the Decision Engine's state accurate between manifest cycles.
+
+Performance target: p99 latency under 50ms, to handle high-frequency bursts from thousands of concurrent screens.
+
+#### 9.2.6 Decision Engine Example: A Day in the Life of Screen SCR-4421
+
+To make the Decision Engine concrete, here is a walkthrough of what happens on a single screen over the course of a morning.
+
+**Setup**: Screen SCR-4421 is a portrait LCD in a shopping mall food court. It has three active campaigns assigned to it:
+
+- **Deal A** (PG, Priority 1): "Nike Summer Collection" — Guaranteed 500,000 impressions over 30 days, $25 CPM. Currently at 38% delivery on day 15 (should be at 50%).
+- **Deal B** (PD, Priority 3): "Coca-Cola Refresh" — Preferred Deal at $18 CPM. No hard delivery guarantee.
+- **Deal C** (PMP, Priority 5): "Local Restaurant" — Private Marketplace with a $10 CPM floor.
+
+**6:00 AM — First manifest request of the day.**
+
+The player sends `{ "referenceId": "SCR-4421", "windowMinutes": 30 }` to the DE. Traffic at 6 AM is low (estimated 200 impressions in this window). The DE builds a manifest:
+
+- Deal A gets 80% of slots (it is behind on pacing and has highest priority)
+- Deal B gets 15% of slots (moderate CPM, fills remaining time)
+- Deal C gets 5% of slots (lowest priority, but floor price is met by one DSP bidder)
+
+The manifest contains ~120 ad slots (one every 15 seconds for 30 minutes). The player downloads it and begins playback.
+
+**8:30 AM — Peak morning traffic begins.**
+
+The player requests a new manifest. Traffic is now high (estimated 1,200 impressions in this window). The DE recalculates:
+
+- Deal A still gets priority (pacing deficit has improved slightly to 42% vs. expected 52%), but the DE recognizes these are high-value impressions. It allocates 60% to Deal A.
+- Deal B's CPM ($18) is competitive for peak hours. It gets 30%.
+- Deal C: The DSP bid of $12 exceeds the $10 floor. It gets 10%.
+
+Revenue per slot is maximized because the DE gives more peak-hour impressions to higher-CPM deals instead of wasting them on lower-value demand.
+
+**11:00 AM — Deal A hits its daily cap.**
+
+During the 11:00 AM manifest request, the DE checks Redis and finds that Deal A has reached its daily impression cap (set to prevent front-loading the entire monthly goal). The DE hard-stops Deal A for the rest of the day:
+
+- Deal A: 0% (daily cap reached, will resume tomorrow)
+- Deal B: 70% (now the highest-value eligible deal)
+- Deal C: 20% (PMP auction clears above floor)
+- Remaining 10%: House ad (mall promotion filler content)
+
+**Key takeaway**: The player never needed to know about Deal A, B, or C. It simply asked the DE "what should I play?" and followed the manifest. The complexity of pacing, priority, CPM optimization, and cap enforcement all happened inside the Decision Engine.
+
+### 9.3 Channel B — VAST Tag Distribution
+
+VAST Tag Distribution is the manual delivery channel, described in detail in [Section 4.10](#410-vast-tag-distribution). In this model, the Influence user exports VAST endpoint URLs (or HTML/ZIP packages) from the Distribution tab on the Deal Detail page and shares them with media owners. The media owner's CMS (Broadsign, Scala, BrightSign, etc.) schedules those VAST tags on specific screens.
+
+The key difference from the Decision Engine channel is that the **CMS controls the schedule**, not Influence. The CMS decides when to call the VAST URL. Influence's role is limited to responding with the correct creative and tracking the impression.
+
+#### 9.3.1 VAST Distribution Example: Campaign on a Partner Network
+
+Consider the same "Nike Summer Collection" campaign, but this time some of the screens belong to a third-party media owner (Clear Channel) who manages their own CMS and does not use the Influence Decision Engine.
+
+**Step 1**: The Influence user goes to the Deal Detail page for "Nike Summer Collection" and clicks "Activate Deal". The Distribution tab appears.
+
+**Step 2**: The user copies the VAST endpoint URL for the "Mall Entrance Screens" line item:
+```
+https://adserver.influence.io/vast/v1/deal_abc123/li_mall01?screen_id={SCREEN_ID}&player_id={PLAYER_ID}
+```
+
+**Step 3**: The user emails this URL to the Clear Channel ad operations team.
+
+**Step 4**: Clear Channel's ad-ops team logs into their Broadsign CMS, creates a new campaign, and pastes the VAST URL as the ad source. They schedule it to run on 50 mall entrance screens from June 1 to June 30, rotating every 15 seconds alongside their other content.
+
+**Step 5**: When a screen is ready to play the Nike ad, Broadsign calls the VAST URL. Influence checks the line item's targeting rules, flight dates, budget, and frequency caps. If the ad is eligible, Influence returns a VAST XML response containing the creative video URL and tracking pixels. If the ad is not eligible (budget exhausted, outside flight dates, frequency cap hit), Influence returns an empty VAST response and the CMS moves to the next item in its rotation.
+
+**Step 6**: After each play, the tracking pixels fire back to Influence, recording the impression for reporting and billing.
+
+**What the VAST URL contains and why:**
+
+| URL Component | Purpose | Why It's Needed |
+|---------------|---------|-----------------|
+| `deal_abc123` (Deal ID) | Identifies which deal this request belongs to | Allows Influence to look up deal-level rules (budget, flight dates, status) |
+| `li_mall01` (Line Item ID) | Identifies the specific line item | Each line item has its own targeting, creative assignments, CPM, and delivery goals |
+| `screen_id` (Query param) | Identifies which physical screen is making the request | Enables screen-level frequency capping and geographic validation |
+| `player_id` (Query param) | Identifies the media player software instance | Enables player-level diagnostics and proof-of-play correlation |
+
+The Deal ID and Line Item ID are required in the URL because the CMS is explicitly requesting a *specific* ad. Unlike the Decision Engine (where the player asks "what should I play?" and the DE chooses), the VAST Distribution model is a pull system: the CMS already knows which ad it wants and is asking Influence to serve it.
+
+### 9.4 Channel Comparison: When Ads Reach Screens
+
+The following example shows the same campaign delivered through both channels simultaneously to illustrate the operational difference.
+
+**Campaign**: "Samsung Galaxy Launch" — $75,000 budget, 2 million target impressions, 60-day flight.
+
+**Line Item 1**: "Airport Screens" — 500 screens in the advertiser's own network, all DE-enabled.
+**Line Item 2**: "Mall Screens - JCDecaux" — 200 screens owned by JCDecaux, managed via Broadsign CMS.
+
+| Aspect | Line Item 1 (DE Channel) | Line Item 2 (VAST Distribution) |
+|--------|--------------------------|----------------------------------|
+| **Who decides what plays** | Decision Engine | JCDecaux's Broadsign CMS |
+| **How ads are scheduled** | Automatically via manifest | Manually by JCDecaux ad-ops team |
+| **How often decisions are made** | Every 15-30 minutes (manifest refresh) | Every time the CMS rotation triggers a VAST call |
+| **Pacing intelligence** | Yes — DE adjusts delivery rate based on real-time progress | No — CMS plays at a fixed rate regardless of delivery progress |
+| **Programmatic competition** | Yes — DE can open slots to PMP/PD auctions when PG deals are healthy | No — VAST URL serves only the assigned line item's creative |
+| **Yield optimization** | Yes — high-value slots go to higher-CPM deals | No — CMS treats all slots equally |
+| **Offline resilience** | Yes — player buffers current manifest | Depends on CMS capabilities |
+| **Setup effort** | Low — screens auto-connect to DE | Medium — requires sharing URLs and CMS configuration |
+| **Revenue reporting** | Real-time via Redis heartbeats | Near real-time via tracking pixels |
+
+Both line items report into the same deal-level dashboard in Influence. The user sees combined delivery metrics, budget spend, and impression counts regardless of which channel delivered the ads. The reporting layer treats both channels identically — an impression is an impression, whether it came from a DE-managed screen or a VAST-tag-managed screen.
+
+### 9.5 Legacy Ad Serving Decision Flow
+
+For reference, the original step-by-step ad serving flow (used before the Decision Engine) is documented below. This flow applies to VAST Distribution requests, where Influence evaluates a single ad request in isolation.
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198324)**
+
+**Step 1: Screen Request** — The screen player sends a request with its unique identifier.
+
+**Step 2: Screen Validation** — The system checks if the screen is active.
+
+**Step 3: Find Eligible Deals** — Query for deals where today's date is between start and end dates, status is Active, and targeting includes this screen.
+
+**Step 4: Find Eligible Line Items** — Get active line items within those deals.
+
+**Step 5: Apply Filters** — Filter out line items that have exhausted budget, are over-delivering, or are paused.
+
+**Step 6: Select Winner** — Normalize allocations, sort by priority, apply weighted random selection.
+
+**Step 7: Return Advertisement** — Return the winning creative's URL to the screen.
+
+**Step 8: Confirm Delivery** — After playback, the screen sends confirmation to update delivery metrics.
+
+---
+
+## 10. External System Integrations
+
+### 10.1 Integration Overview
+
+Influence operates as part of a larger advertising ecosystem and integrates with several external systems:
+
+| System | Purpose | Deal Type |
+|--------|---------|-----------|
+| Planner | Campaign planning and inventory reservation | Traditional |
+| Activate | Programmatic RFP workflows | Programmatic |
+| Booking Engine | Inventory reservation management | All |
+| Admin Console | DSP/Seat configuration, company management | All |
+| Decision Engine | Real-time intelligent ad selection for DE-enabled screens | All |
+
+### 10.2 Planner Integration
+
+Planner is the campaign planning platform used across the advertising ecosystem. It is used by agencies, advertisers, media owners, resellers, internal users, and partner users to build Traditional advertising campaigns. When a campaign is activated in Planner, it flows into Influence for execution. This integration automates the creation of deals and line items, eliminating manual data entry while maintaining the data integrity required for accurate delivery.
+
+**Campaign Activation and Pre-Approval**
+
+By the time a campaign reaches Influence from Planner, it has already completed all planning and approval workflows. Inventory reservation, hold requests, pricing negotiation, and stakeholder approvals happen entirely within Planner. Influence receives the campaign in an execution-ready state with status set to Active. Statuses such as "Generated", "Reserved", or "Negotiation" are internal to Planner and have no meaning in Influence.
+
+All campaigns from Planner are Traditional deals. If a user wants programmatic execution, they select the RFP flow in Planner, which routes the campaign to Activate instead (see Section 10.3).
+
+**Automatic Deal Creation**
+
+When Planner activates a campaign, Influence automatically creates a corresponding deal. The deal receives all mandatory fields populated from Planner data:
+
+The deal name comes from the campaign name in Planner. The External Deal ID field stores the Planner campaign ID for cross-platform tracking. Since Planner only sends Traditional campaigns, the Deal Type is always set to Traditional. The SSP Partner defaults to "Influence" (the built-in SSP). Brand and Agency are linked based on Planner selections. Countries, currency, budget, goals, and flight dates all transfer from Planner configuration. The Source field is automatically set to "Planner" to identify the deal's origin.
+
+**Note on Multi-Media Owner Campaigns:** When a Planner campaign involves multiple media owners, the system creates a single deal with separate line items for each media owner. The deal ID remains the same across all line items, but each line item is assigned to its specific media owner. This approach enables proper access control while maintaining campaign-level reporting and budget tracking.
+
+**Automatic Line Item Creation by Media Owner**
+
+The most important aspect of Planner integration is how line items are created. Influence creates one line item for each media owner included in the campaign. This design enables proper access control and ensures each media owner can manage only their portion of the campaign.
+
+Consider a campaign called "Holiday Promo 2026" that uses screens from five different media owners: JCDecaux Malaysia with 200 screens, Clear Channel Singapore with 150 screens, oOh!media New Zealand with 100 screens, Lamar Advertising with 75 screens, and Outfront Media with 50 screens. When this campaign is sent to Influence, the system creates one deal and five line items. Each line item is named by appending the media owner name to the deal name (for example, "Holiday Promo 2026 - JCDecaux Malaysia").
+
+Each line item receives configuration from Planner including the creative type (Display, Video, or Audio), the specific screens pre-selected in Planner, the negotiated CPM rate for that media owner, and geography targeting within the deal's countries. Target impressions are allocated based on Planner's configuration for each media owner segment. Priority defaults to 5 and can be adjusted within Influence if needed. Traffic allocation follows the default behavior described in Section 6.2—each line item is assigned 100%, and the normalization logic distributes traffic proportionally across all active line items.
+
+**Media Owner Access Control**
+
+The multi-media owner structure enables granular access control. When a media owner logs into Influence, they see only the deals and line items that belong to them. This isolation is fundamental to the platform's multi-tenant architecture.
+
+An agency or advertiser who created the campaign sees the complete deal with all line items across all media owners. They can monitor overall campaign performance, track delivery across all markets, and manage budget at the deal level.
+
+A media owner sees only their portion. When JCDecaux Malaysia logs in, they see the "Holiday Promo 2026" deal but only with their single line item visible. They cannot see line items belonging to Clear Channel, oOh!media, or any other media owner. This prevents competitors from viewing each other's pricing, performance data, or delivery status.
+
+The access control extends throughout the platform. In the Deals list, media owners see deals containing at least one of their line items. In the Deal Detail page, they see only their line items. In the Line Item Detail, they manage only their assigned items. In Inventory, they see only screens they own. In Content Hub, they see only creatives assigned to their line items for Tier 2 approval.
+
+**Planner Responsibilities**
+
+Several workflows remain entirely within Planner and do not occur in Influence. These include inventory reservation, inventory hold, approval workflows, and pricing negotiation. Additionally, Planner is responsible for updating the Booking Engine for campaigns it creates. Influence does not update the Booking Engine for Planner-originated campaigns.
+
+### 10.3 Activate Integration
+
+**Campaign Flow from Activate**
+
+When a user completes an RFP (Request for Proposal) workflow in Activate, the resulting deal is sent to Influence for execution.
+
+1. **RFP Flow Selection**: In Planner, users can select the RFP flow if they want programmatic execution. This routes the campaign to Activate.
+
+2. **Programmatic Deals**: All deals from Activate are Programmatic deals in Influence (PG, Preferred Deal, PMP, Always On, or Open Auction as configured in Activate).
+
+3. **DSP Configuration**: DSP and seat information is established during the RFP process in Activate and passed to Influence.
+
+**RFP Badge Display**
+
+Deals that originate from Activate display an "RFP" badge in the user interface:
+- In the Deals list: The RFP badge appears in the Source column next to "Activate"
+- In the Deal Detail page: The RFP badge appears in the page header alongside the deal name
+- Purpose: The badge indicates to media owners that this deal requires RFP review and approval
+
+**RFP Filter**
+
+The Deals list filter drawer includes an RFP Status filter allowing users to filter deals by:
+- RFP (Pending Review): Shows deals that are RFP deals from Activate
+- Not RFP: Shows traditional deals or programmatic deals that are not from the RFP workflow
+
+### 10.4 Booking Engine Integration
+
+The Booking Engine is a separate service that manages inventory reservations and campaign scheduling across the Influence ecosystem.
+
+**Update Responsibilities**
+
+| Deal Source | Who Updates Booking Engine |
+|-------------|---------------------------|
+| Influence (created locally) | Influence |
+| Planner | Planner |
+| Activate | Activate |
+
+**When Influence Updates Booking Engine**
+
+When a media owner creates a Traditional campaign directly in Influence:
+1. The campaign is assumed to be approved offline
+2. When the Deal is fully configured and created, Influence updates the Booking Engine
+3. The Booking Engine records the inventory reservation
+
+**Traditional Deal Assumption**
+
+For Traditional deals created in Influence by media owners, it is assumed that the campaign approval has happened offline through direct communication with the advertiser/agency.
+
+### 10.5 Admin Console Integration
+
+The Admin Console is the central management platform for partner configurations, company data, and access control.
+
+**Data Sourced from Admin Console**
+
+| Data Type | Description | Used In |
+|-----------|-------------|---------|
+| SSP Partners | Supply-Side Platform configurations available to the company | Deal Form - SSP Partner dropdown |
+| Media Owner Access | Which media owners are available per SSP | Deal Form - Media Owner dropdown (filtered by SSP) |
+| DSP Partners | Demand-Side Platform configurations | Deal Form - DSP Partner dropdown |
+| DSP Access | Which DSPs are available to each company (Agency/Brand) | Deal Form - filters DSP dropdown based on selected Agency/Brand |
+| Seat Names | Buyer seat configurations per DSP per company | Deal Form - Seat Name dropdown |
+| Seat IDs | Unique identifiers for each seat | Deal Form - Seat ID field (view-only, verified on save) |
+| Country Access | Which countries the logged-in user can access | Deal Form - Countries multi-select dropdown |
+| Company Hierarchy | Media owner parent-child relationships | Deal Form - Media Owner dropdown hierarchy |
+| User Home Country | Default country for the logged-in user | Deal Form - Countries default selection |
+
+**SSP Access Workflow**
+
+1. **Company SSP Configuration**: In Admin Console, each company has a list of SSP partners they can access.
+2. **SSP Dropdown Population**: When a user opens the Deal Form, the SSP Partner dropdown is populated with SSPs that the user's company has access to.
+3. **Default SSP**: Influence (built-in SSP) is always available and is the default selection.
+
+**Media Owner Filtering**
+
+1. **SSP-Media Owner Relationship**: Each media owner's inventory is connected to specific SSP partners.
+2. **Dynamic Filtering**: When an SSP is selected, the Media Owner dropdown is filtered to show only media owners with inventory connected to that SSP.
+
+**Country Access Workflow**
+
+1. **User Country Permissions**: In Admin Console, each user account has country access permissions configured.
+2. **Countries Dropdown Population**: The Countries multi-select dropdown only shows countries the user has permission to access.
+3. **Default Country**: The user's home country (configured in Admin Console) is pre-selected by default.
+4. **Line Item Geography Constraint**: Line items can only target cities, areas, and towns within the countries selected at the Deal level.
+
+**DSP/Seat Management Workflow**
+
+1. **Viewing DSPs in Influence**: When creating a programmatic deal, the DSP dropdown shows options sourced from Admin Console based on the selected company's (Agency or Brand) DSP Access configuration.
+
+2. **Creating Seats**: While creating or editing an agency in Influence, users can select DSP and create seats. This data is created in Admin Console via API.
+
+3. **Seat ID Verification**: Before saving a deal, the system verifies the Seat ID exists and is valid in Admin Console. Invalid or removed Seat IDs will cause the save to fail.
+
+4. **Seat ID Display**: Seat IDs are fetched from Admin Console and displayed as read-only in Influence. Users cannot manually edit Seat IDs.
+
+**Integration Architecture**
+
+**[View Interactive Diagram in Miro](https://miro.com/app/board/uXjVGH3XGbs=?moveToWidget=3458764657790198328)**
+
+<p align="center"><em>Figure: Admin Console Integration Architecture</em></p>
+
+### 10.6 Decision Engine Integration
+
+The Decision Engine (DE) is an external microservice that provides intelligent ad selection for screens in the network. Unlike Planner or Activate (which send data *into* Influence), the Decision Engine reads data *from* Influence and makes real-time serving decisions independently.
+
+**Deployment Model**
+
+The Decision Engine runs as a separate service with its own infrastructure. It is not embedded within the Influence Adserver application. The DE has its own base URL (e.g., `https://de.influence.io`), its own API endpoints, and its own Redis instance for real-time state tracking. The Influence Adserver and the Decision Engine share access to the same underlying deal, line item, and creative data, but they do not call each other's APIs directly during normal operation.
+
+**Data Flow**
+
+| Direction | Data | Mechanism |
+|-----------|------|-----------|
+| Influence → DE | Deal configurations, line item rules, creative assignments, budget limits, flight dates, targeting | Shared database (DE reads from Influence's data store) |
+| DE → Redis | Real-time pacing counters, SOV trackers, budget consumption, frequency cap state | Direct Redis writes from DE and heartbeat endpoint |
+| Player → DE | Screen reference ID, manifest requests | DE API: `POST /v1/decision/simple` |
+| Player → DE | Impression confirmations (heartbeats) | DE API: `GET /v3/track` |
+| DE → Player | Manifest (sequence of ads with creative URLs and tracking) | DE API response |
+
+**What Influence Provides to the Decision Engine**
+
+The Decision Engine requires the following data from Influence to make serving decisions:
+
+1. **Active deals and line items** — which campaigns are currently in-flight, their priorities, budgets, and delivery goals
+2. **Creative assignments** — which creatives are approved and assigned to each line item, including media file URLs and dimensions
+3. **Targeting rules** — geographic targeting, venue types, screen specifications, and dayparting schedules
+4. **Traffic allocation and priority** — the configured allocation percentages and priority rankings for each line item
+5. **Frequency cap settings** — maximum plays per screen per time period for programmatic deal types
+
+**What the Decision Engine Returns to Players**
+
+The DE returns a time-limited manifest containing a sequence of ads to play. Each entry in the manifest includes the deal ID, line item ID, creative URL, duration, tracking URL, and a resume token. The full API specification is documented in [Section 9.2.5 — Decision Engine API](#925-decision-engine-api).
+
+**Relationship to VAST Distribution**
+
+The Decision Engine and VAST Distribution (Section 4.10) are complementary, not competing. A single deal can have some line items served through the DE (on DE-enabled screens) and other line items distributed via VAST tags (on third-party CMS-managed screens). Both channels report impressions back to Influence, and the deal-level dashboard aggregates data from both sources. See [Section 9.4 — Channel Comparison](#94-channel-comparison-when-ads-reach-screens) for a detailed side-by-side comparison.
+
+---
+
+## 11. Inventory Integration
+
+### 11.1 External Product Overview
+
+The Inventory Management product handles:
+- Screen registration and configuration
+- Screen health monitoring
+- Device management
+- Physical location and venue mapping
+- Display specifications
+- Daily impression forecasting
+
+### 11.2 Accessing Inventory Management
+
+Click "Inventory" in the sidebar to open the Inventory Management application in a new tab.
+
+---
+
+## 12. Integrations
+
+### 12.1 Built-in SSP
+
+Influence includes a native Supply-Side Platform called "Influence SSP". This SSP is always active and cannot be disabled.
+
+### 12.2 External SSP Partners
+
+Operators can connect additional SSP partners:
+- Hivestack
+- Vistar
+- Place Exchange
+- VIOOH
+- Broadsign
+- Magnite
+
+### 12.3 DSP Partners
+
+DSP integrations define which demand partners can bid on inventory. DSP configurations are managed through Admin Console.
+
+---
+
+## 13. User Interface Navigation
+
+### 13.1 Application Layout
+
+The application uses a sidebar-and-main-content layout with header bar.
+
+### 13.2 Sidebar Navigation
+
+| Menu Item | Purpose |
+|-----------|---------|
+| Dashboard | Main overview with metrics |
+| Deals | Deal management with drill-down to line items and creatives |
+| Content Hub | Creative library (Tier 1 approval) |
+| Inventory | External Inventory Management product (external link) |
+| Proof of Play | Ad playback verification and playlog uploads |
+| Integrations | SSP/DSP partner connections |
+| Measure | External reporting and analytics platform (external link) |
+| Configuration | Dropdown menu containing Signals, Custom POIs, Tags, and Settings |
+
+### 13.3 Navigation Flow
+
+The primary navigation follows a drill-down pattern:
+
+```
+Deals List → Deal Detail → Line Item Form → Line Item Creatives → Creative Assignment
+```
+
+URLs follow this pattern:
+- `/deals` - Deals list
+- `/deals/:id` - Deal detail
+- `/deals/:id/line-items/new` - Create line item
+- `/deals/:id/line-items/:lineItemId` - Edit line item
+- `/deals/:id/line-items/:lineItemId/creatives` - Line item creatives
+
+### 13.4 Header Controls
+
+The header bar includes:
+- Sidebar toggle
+- Language switcher
+- Product switcher
+- User menu
+
+### 13.5 User Menu
+
+Accessed from the avatar in the header:
+- Profile settings
+- Account preferences
+- Sign out
+
+### 13.6 Theme Settings
+
+Light and dark mode toggle available in settings.
+
+### 13.7 Form Pages
+
+Forms use a two-column layout:
+- Left column: Form fields organized in sections
+- Right column: Insights panel with contextual guidance
+
+### 13.8 Filter Drawer
+
+Filter drawers slide in from the right with:
+- Searchable dropdowns
+- Date range pickers
+- Apply/Clear All buttons
+
+### 13.9 Inline Filtering and Sorting
+
+Tables support:
+- Column sorting
+- Search input
+- Status filters
+
+### 13.10 Dialog Usage
+
+Dialogs are used for:
+- Confirmations (delete, publish)
+- Quick create (agency, brand)
+- Previews
+
+---
+
+## 14. History Logs and Audit Trail
+
+### 14.1 Overview
+
+All changes to deals, line items, and creative assignments are logged for audit purposes.
+
+### 14.2 What Gets Tracked
+
+| Entity | Tracked Changes |
+|--------|-----------------|
+| Deal | Create, update, status change, delete |
+| Line Item | Create, update, status change, delete |
+| Creative Assignment | Create, update, approval status change |
+
+### 14.3 Created By Attribution
+
+Each record tracks:
+- Created by (user)
+- Created at (timestamp)
+- Last modified by (user)
+- Last modified at (timestamp)
+
+### 14.4 View History Button
+
+A "View History" button on detail pages opens the audit log showing all changes with timestamps and user attribution.
+
+### 14.5 API Endpoints
+
+History logs are accessible via API for integration with external audit systems.
+
+---
+
+## 15. Recommendation Engine Integration
+
+### 15.1 Overview
+
+Influence integrates with MW Planner's Recommendation Engine V2 to provide AI-driven inventory recommendations. The engine analyzes available screens against campaign parameters and returns ranked recommendations based on an 8-factor scoring system.
+
+### 15.2 Campaign Goals
+
+The recommendation engine optimizes for the following campaign goal types:
+
+| Goal Type | Description | Primary Optimization |
+|-----------|-------------|----------------------|
+| Impressions | Maximize total ad views | Screen reach and traffic |
+| Reach | Maximize unique audience exposure | Geographic distribution |
+| Share of Voice | Achieve target ad presence percentage | Availability and frequency |
+| Ad Plays | Maximize content display frequency | High-frequency screens |
+| Carbon Emission | Minimize environmental impact | Energy-efficient displays |
+
+### 15.3 Scoring System (8 Factors)
+
+Each inventory is scored 0-100 across eight factors:
+
+1. **Measure Fit** (20-28%): How well the inventory delivers the campaign goal
+2. **Geo Fit** (15-22%): Location relevance to target geography
+3. **Availability** (10-15%): Fraction of requested schedule available
+4. **Budget Fit** (15-20%): Cost efficiency relative to budget
+5. **Audience Fit** (8-12%): Audience segment overlap
+6. **Brand Fit** (8-10%): Brand category to venue affinity
+7. **Quality Fit** (5-20%): Physical and creative quality score
+8. **Time Fit** (4%): Daypart and date alignment
+
+Weights vary by goal type. For example, "carbon_emission" goals weight Quality Fit at 20%, while "impressions" goals weight Measure Fit at 25%.
+
+### 15.4 Recommendation Panel (Line Item Form)
+
+When creating or editing a line item, the AI Recommendations panel appears in the sidebar:
+
+- **Trigger**: Panel activates when the parent deal has start/end dates
+- **Display**: Shows top 10 recommended screens with scores
+- **Actions**: Click "+" to add recommended screen to selection
+- **Refresh**: Manual refresh button for updated recommendations
+
+Each recommendation shows:
+- Score badge (color-coded by score range)
+- Screen name and format
+- Location (city, country)
+- Estimated impressions and CPM
+- AI explanation ("Why recommended")
+
+### 15.5 Score Breakdown Tooltip
+
+Hovering over the score badge reveals a breakdown of all 8 scoring components with progress bars. This helps users understand why a screen was recommended.
+
+### 15.6 Auto-Optimize Feature
+
+Line items can be automatically optimized via the Deal Detail page:
+
+1. Open Deal Detail page
+2. Click the actions menu (...) for a line item
+3. Select "Auto-Optimize"
+4. System analyzes and recommends top 5 screens
+5. Confirmation shows: inventories added, estimated impressions, estimated cost
+
+**Note**: Auto-optimize does not overwrite manual screen selections; it adds recommended screens to the existing selection.
+
+### 15.7 API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/recommendations` | POST | Get inventory recommendations |
+| `/api/deals/:id/recommendations` | GET | Get recommendations for a deal |
+| `/api/line-items/:id/auto-optimize` | POST | Auto-optimize a line item |
+
+### 15.8 Request Parameters
+
+```json
+{
+  "country": "US",
+  "startDate": "2024-01-01",
+  "endDate": "2024-01-31",
+  "budget": 50000,
+  "goalType": "impressions",
+  "goalValue": 1000000,
+  "geography": {
+    "cities": ["New York", "Los Angeles"]
+  },
+  "limit": 10
+}
+```
+
+### 15.9 Response Structure
+
+```json
+{
+  "runId": "uuid",
+  "status": "success",
+  "recommendations": [
+    {
+      "inventoryId": "screen-001",
+      "inventoryName": "Times Square Billboard",
+      "score": 87,
+      "scoreComponents": { ... },
+      "metrics": {
+        "estimatedImpressions": 500000,
+        "estimatedCost": 15000,
+        "cpm": 30.00
+      },
+      "whyRecommended": "Excellent location match • High impression delivery"
+    }
+  ],
+  "summary": {
+    "totalInventoriesAnalyzed": 150,
+    "totalReturned": 10,
+    "estimatedTotalImpressions": 2500000,
+    "estimatedTotalCost": 45000,
+    "budgetUtilization": 90
+  }
+}
+```
+
+### 15.10 External Engine Integration
+
+The recommendation service supports both internal mock scoring and external API integration:
+
+- **Mock Mode**: Default; uses internal scoring algorithms
+- **External Mode**: Set `RECOMMENDATION_ENGINE_URL` environment variable to connect to MW Planner's external engine
+
+When the external engine is unavailable, the system gracefully falls back to mock recommendations.
+
+---
+
+## 16. Proof of Play (PoP) System
+
+Proof of Play (PoP) records verify that advertisements were displayed as scheduled. These records provide accountability to advertisers and enable accurate billing and performance reporting.
+
+### 16.1 Overview
+
+PoP records contain proof media (images or videos) captured during ad playback on screens. Each record verifies that a specific creative was displayed on a specific screen at a specific time.
+
+### 16.2 PoP Record Sources
+
+PoP data can originate from two sources:
+
+| Source | Description |
+|--------|-------------|
+| CMS Integration | Automatic playlog data pulled from connected CMS platforms (Studio, Broadsign, etc.) |
+| Manual Upload | Playlog files uploaded by media owners for traditional campaigns |
+
+### 16.3 PoP Record Display
+
+The Proof of Play page displays a table with the following columns:
+
+| Column | Description |
+|--------|-------------|
+| Inventory | Screen name and location |
+| Player | Player device identifier |
+| Creative | Creative name and thumbnail |
+| Deal / Line Item | Associated deal and line item |
+| Play Time | Timestamp of ad playback |
+| Status | Verification status (Verified, Pending, Failed) |
+
+**Duration Calculation**: Play duration is calculated from the timestamp difference between play start and end times.
+
+### 16.4 Status Workflow
+
+| Status | Description |
+|--------|-------------|
+| Pending | PoP record received, awaiting verification |
+| Verified | Proof media confirmed, record valid |
+| Failed | Verification failed (missing media, timestamp mismatch) |
+
+---
+
+## 17. Playlog Upload System
+
+Media owners can manually upload playlogs for traditional campaigns that do not have CMS integration.
+
+### 17.1 Upload Interface
+
+The playlog upload interface includes:
+- **Deal/Line Item pre-fill**: When accessed from a specific deal or line item, IDs are pre-filled
+- **File upload area**: Drag-and-drop or click to select CSV/Excel files
+- **Template download**: Link to download the standard playlog template
+- **Preview table**: Shows parsed data before submission
+
+### 17.2 CSV Template
+
+The playlog template includes the following columns:
+
+| Column | Required | Description |
+|--------|----------|-------------|
+| inventory_id | Yes | Screen/inventory identifier |
+| player_id | No | Player device identifier |
+| creative_id | Yes | Creative identifier |
+| play_start | Yes | Playback start timestamp (ISO 8601) |
+| play_end | No | Playback end timestamp |
+| duration_seconds | No | Play duration in seconds |
+
+**Template URL**: Available via download button on the upload page.
+
+### 17.3 File Processing
+
+The system handles:
+- CSV file parsing with automatic delimiter detection
+- Excel file conversion (.xlsx, .xls)
+- Date format normalization
+- Validation against existing deals, line items, and inventory
+
+---
+
+## 18. Configuration Menu
+
+The Configuration dropdown in the sidebar provides access to administrative and setup features.
+
+### 18.1 Menu Items
+
+| Item | Description |
+|------|-------------|
+| Signals | Trigger-based automation rules for campaign optimization |
+| Custom POIs | Points of Interest management for geotargeting |
+| Tags | Cross-platform tag management |
+| Settings | Platform-wide configuration options |
+
+### 18.2 Signals
+
+Signals enable conditional automation based on real-time triggers. See Section 8 for detailed documentation.
+
+### 18.3 Custom POIs
+
+Custom POIs allow users to create their own Points of Interest for geotargeting. Features include:
+
+**POI Library View**:
+- Table with columns: Name, Category, Location, Radius, Status, Created By, Created Date
+- Search and filter functionality
+- Actions: View on map, Edit, Delete
+
+**POI Categories**:
+- Shopping, Office, Sports, Entertainment, Restaurant, Hotel, Hospital, Education, Transit, Retail, Custom
+
+**POI Fields**:
+- Name (required)
+- Category (required)
+- Latitude/Longitude (required)
+- Address, City, Country
+- Radius in meters
+- Status (enabled/disabled)
+
+**Bulk Upload**:
+- CSV file upload with downloadable template
+- Template includes all required and optional fields
+- Validation and preview before import
+
+### 18.4 Tags
+
+Tags provide cross-platform organization integrated with Admin Console:
+
+- **Storage**: Tags are stored in Admin Console for consistency across Influence, Planner, and Measure
+- **Properties**: Name, Color (hex), Description
+- **Usage Tracking**: Shows count of deals, creatives, and line items using each tag
+- **Color Presets**: 8 preset colors plus custom color picker
+
+---
+
+## 19. Settings Module
+
+The Settings page provides comprehensive platform configuration organized into 11 sections.
+
+### 19.1 General Settings
+
+Basic configuration for the ad server:
+- **Company Name**: Organization name displayed in reports
+- **Timezone**: Default timezone (UTC, EST, PST, CET, IST)
+- **Default Currency**: Currency for new deals (USD, EUR, GBP, INR)
+- **Date Format**: Display format (MM/DD/YYYY, DD/MM/YYYY, YYYY-MM-DD)
+
+### 19.2 Notifications
+
+Alert and notification preferences:
+- **Deal Alerts**: Notifications when deals reach budget thresholds
+- **Screen Status Updates**: Alerts when screens go offline or require maintenance
+- **Daily Performance Reports**: Daily email summaries of deal performance
+- **Integration Status**: Notifications for SSP/DSP connectivity issues
+
+### 19.3 Traffic Control
+
+Default settings for traffic allocation and delivery:
+- **Default Traffic Allocation**: Initial percentage (25%, 50%, 75%, 100%)
+- **Delivery Pacing**: Even, ASAP, or Frontloaded
+- **Enable Programmatic Fallback**: Fill unfilled inventory with programmatic demand
+
+### 19.4 Forecasting Defaults
+
+Default settings for line item forecasting:
+- **Default Goal Type**: Impressions, Reach, Share of Voice, Ad Plays, or Carbon Emission
+- **Confidence Level**: Low (70%), Medium (85%), or High (95%)
+- **Budget Buffer**: Extra budget allowance percentage for forecast variance
+- **Forecast Refresh Interval**: Real-time, Hourly, Daily, or Weekly
+- **Include Historical Performance**: Toggle to use historical data for forecast accuracy
+
+### 19.5 Optimization Preferences
+
+Configuration for AI-powered optimization behavior:
+- **Optimization Mode**: Aggressive (maximize performance), Balanced (performance + stability), or Conservative (minimal changes)
+- **Re-optimization Frequency**: Never (manual only), Daily, Weekly, or Monthly
+- **Auto-Optimize New Line Items**: Automatically apply AI recommendations to new line items
+- **Enable A/B Testing**: Allow AI to run A/B tests on inventory selection
+- **Show Optimization Insights**: Display AI reasoning and recommendations in the UI
+
+### 19.6 Recommendation Weights
+
+Adjustment of the 8-factor scoring system for AI recommendations. Each factor has a weight slider (0-30%):
+
+| Factor | Default Weight | Description |
+|--------|---------------|-------------|
+| Measure Fit | 15% | Alignment with campaign measurement goals |
+| Geo Fit | 15% | Geographic proximity to target locations |
+| Availability | 15% | Screen availability during campaign period |
+| Budget Fit | 10% | Cost efficiency relative to budget |
+| Audience Fit | 15% | Match with target demographic profiles |
+| Brand Fit | 10% | Suitability for brand guidelines |
+| Quality Fit | 10% | Screen quality and placement |
+| Time Fit | 10% | Daypart and timing alignment |
+
+**Reset to Defaults**: Button to restore all weights to default values.
+
+### 19.7 Workflow Settings
+
+Approval workflows and automation:
+- **Require Creative Approval**: All creatives must be approved before going live
+- **Two-Tier Creative Approval**: Enable Tier 2 (Media Owner) approval after Tier 1 (Content Hub)
+- **Auto-Accept Deals**: Automatically accept deals from trusted partners
+- **Deal Locking**: Lock deals after acceptance to prevent modifications
+
+### 19.8 Terminology
+
+Customize labels used throughout the platform:
+- Deal, Line Item, Creative, Inventory, Advertiser, Campaign
+
+### 19.9 Themes & Branding
+
+Visual customization:
+- **Theme Mode**: Light, Dark, or System
+- **Primary Color**: Color picker with hex value
+- **Logo URL**: Custom logo for white-labeling
+- **Compact Mode**: More compact UI with smaller spacing
+
+### 19.10 Inventory Whitelisting
+
+Control which inventory is available:
+- **Enable Inventory Whitelisting**: Only show whitelisted inventory
+- **Whitelisted Inventory IDs**: Comma-separated or newline-separated list
+- **Exclude Adult Content Venues**: Automatically exclude venues with adult content
+
+### 19.11 API Settings
+
+API configuration:
+- **API Endpoint**: Display-only endpoint URL
+- **Rate Limit**: Requests per minute limit
+- **Request Timeout**: Timeout in milliseconds