# interactiveadvertisingbureau/global-privacy-platform architecture

> Architecture diagram of the GitHub repository interactiveadvertisingbureau/global-privacy-platform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/interactiveadvertisingbureau/global-privacy-platform
- Repository: https://github.com/interactiveadvertisingbureau/global-privacy-platform

## Overview

##### Project type and purpose
- This is a documentation/specification repository for the IAB Global Privacy Platform (GPP).
- The GPP is a “transport layer” for conveying user consent and preference signaling across the digital advertising supply chain.

##### File structure
- Top-level “Core” folder: holds the two primary technical specs—Consent String Specification and CMP API Specification.
- Top-level “Sections” folder: subdivided into region- or jurisdiction-specific specification extensions (Canada, EEA, US-National, US-States → CA, CO, CT, … VA).
- A single “implementation.md” file: describes example or reference implementations.

##### README for architectural clues
- The GPP consists of:
– A Consent Management API (CMP API) that allows CMPs to read/write consent data.
– A Consent String format for serializing user choices.
– A registry of “Sections” which map to region-specific privacy rules.
- GPP messages flow from user agent (browser/app) → CMP → ad tech vendors via bid requests.

##### Main logical components
a. CMP (Consent Management Platform) – front-end/UI in the user’s browser or app.
b. CMP API (from Core/CMP API Specification.md) – JavaScript (or native) interface exposing getConsent(), setConsent(), etc.
c. Consent String Encoder/Decoder (from Core/Consent String Specification.md) – component that serializes/deserializes the consent string.
d. Section Extensions (from Sections/…) – plugins or modules for jurisdictional rules (e.g., EU-TCF, CCPA, MSPA).
e. Ad Tech Supply Chain (Publishers, SSPs, DSPs, Ad Servers) – external parties that consume the consent string.
f. Storage Mechanism – cookie or localStorage where the consent string is persisted.
g. Implementation Layer – reference code or library (implementation.md).

##### Relationships and data flows
- User interacts with CMP UI → CMP API calls → Consent String Encoder writes user choices → stored locally.
- On each ad request, the stored consent string is attached to HTTP headers or ad request payload → Ad Tech Supply Chain components.
- Section Extension modules contribute additional bits/fields to the consent string according to jurisdiction.
- Downstream vendors decode the string (Consent String Decoder) to apply regional rules.

##### Architectural patterns and design principles
- Modular extension pattern: the “Sections” directory defines plug-in modules that extend the core consent string with region-specific fields.
- Client-side focus: The entire GPP logic lives in the user agent (no central server component).
- Stateless transport: each ad request carries the entire consent state.

##### Relevant technologies/frameworks (even if hypothetical)
- JavaScript/TypeScript library for CMP API and Consent String logic.
- Storage: document.cookie or window.localStorage.
- HTTP ad-tech integration (OpenRTB headers or custom X-GPP-String header).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client-side Components
    subgraph "Client-side Components"
        direction TB
        CMP_UI["CMP UI"]:::frontend
        CMP_API["Consent Management API"]:::api
        Encoder["Consent String Encoder/Decoder"]:::core
        Storage["Storage (cookie/localStorage)"]:::storage
        Implementation["Reference Implementation"]:::implementation
        subgraph "Section Extensions"
            direction TB
            Sec_CAN["Canada Extension"]:::extension
            Sec_EEA["EEA Extension"]:::extension
            Sec_USN["US-National MSPA Extension"]:::extension
            subgraph "US States Extensions"
                direction TB
                Sec_CA["CA Extension"]:::extension
                Sec_CO["CO Extension"]:::extension
                Sec_CT["CT Extension"]:::extension
                Sec_DE["DE Extension"]:::extension
                Sec_FL["FL Extension"]:::extension
            end
        end
        Decoder["Consent String Decoder"]:::core
    end

    %% External Consumers
    subgraph "External Consumers"
        direction TB
        Publishers["Publishers"]:::external
        SSP["SSPs"]:::external
        DSP["DSPs"]:::external
        AdServers["Ad Servers"]:::external
    end

    %% Data Flows
    User["User"]:::external -->|"interacts"| CMP_UI
    CMP_UI -->|"getConsent() call"| CMP_API
    CMP_API -->|"encodeConsent()"| Encoder
    Encoder -->|"storeConsentString()"| Storage
    Storage -->|"GPP consent string in header"| Publishers
    Storage -->|"GPP consent string in header"| SSP
    Storage -->|"GPP consent string in header"| DSP
    Storage -->|"GPP consent string in header"| AdServers
    Publishers -->|"decodeConsent() call"| Decoder
    SSP -->|"decodeConsent() call"| Decoder
    DSP -->|"decodeConsent() call"| Decoder
    AdServers -->|"decodeConsent() call"| Decoder

    %% Extensions integration
    Sec_CAN -->|"add fields"| Encoder
    Sec_EEA -->|"add fields"| Encoder
    Sec_USN -->|"add fields"| Encoder
    Sec_CA -->|"add fields"| Encoder
    Sec_CO -->|"add fields"| Encoder
    Sec_CT -->|"add fields"| Encoder
    Sec_DE -->|"add fields"| Encoder
    Sec_FL -->|"add fields"| Encoder

    %% Click Events
    click CMP_API "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Core/CMP API Specification.md"
    click Encoder "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Core/Consent String Specification.md"
    click Implementation "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/implementation.md"
    click Sec_CAN "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/Canada/GPPExtension: IAB Canada TCF.md"
    click Sec_EEA "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/EEA/GPPExtension: IAB Europe TCF.md"
    click Sec_USN "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-National/IAB Privacy’s Multi-State Privacy Agreement (MSPA) US National Technical Specification.md"
    click Sec_CA "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-States/CA/GPP Extension: California Privacy Technical Specification.md"
    click Sec_CO "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-States/CO/GPP Extension: Colorado Privacy Technical Specification.md"
    click Sec_CT "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-States/CT/GPP Extension: Connecticut Privacy Technical Specification.md"
    click Sec_DE "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-States/DE/GPP Extension: IAB Privacy’s Delaware Privacy Technical Specification.md"
    click Sec_FL "https://github.com/interactiveadvertisingbureau/global-privacy-platform/blob/main/Sections/US-States/FL/GPP Extension: IAB Privacy’s Florida Privacy Technical Specification.md"

    %% Styles
    classDef frontend fill:#AEDFF7,stroke:#000,stroke-width:1px
    classDef api fill:#88C0D0,stroke:#000,stroke-width:1px
    classDef core fill:#81A1C1,stroke:#000,stroke-width:1px
    classDef storage fill:#EBCB8B,stroke:#000,stroke-width:1px
    classDef extension fill:#D08770,stroke:#000,stroke-width:1px
    classDef external fill:#4C566A,stroke:#000,stroke-width:1px,color:#FFF
    classDef implementation fill:#A3BE8C,stroke:#000,stroke-width:1px
```
