# datadog/browser-sdk architecture

> Architecture diagram of the GitHub repository datadog/browser-sdk, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datadog/browser-sdk
- Repository: https://github.com/datadog/browser-sdk

## Overview

##### Project Type and Purpose
- This is a multi‐package monorepo (managed by Lerna & Yarn) that implements the Datadog Browser SDK: a set of JavaScript libraries for collecting logs, RUM (Real User Monitoring), session replay, and telemetry from a web application and shipping that data to Datadog.
- In addition to core SDK packages, it includes a developer browser extension (Chrome/Firefox), a web‐worker for payload compression, and a suite of E2E/unit tests plus CI/CD scripts.

##### File Structure Highlights
- Top‐level: monorepo config (`lerna.json`, `package.json`), CI/CD (`.github/`, `.gitlab/`), build & deploy scripts (`scripts/`), tsc/webpack configs.
- `packages/`: each subfolder is an independent npm package:
- `core`: foundational event/context/transport logic
- `logs`: browser log collection APIs
- `rum-core` & `rum`/`rum-slim`: Real User Monitoring event tracking
- `rum-react`: React integration plugin
- `worker`: web‐worker for deflate/compression
- `flagging`, `performances`, etc.
- `developer-extension/`: a browser extension with content scripts, background, devtools panel UI (React/TypeScript).
- `test/`: integration & E2E tests (Playwright, mock intake servers).

a. Main Runtime Components
1. Web Application (your SPA)
2. Datadog SDK Layer
- Bundled packages: browser-core, browser-logs, browser-rum (or rum-slim), browser-worker
- Boot modules: init/`startRum()`, `startLogs()`, spawn Worker
- Domain modules: event listeners, context managers, session management, telemetry, rate limiting
- Transport modules: batching, HTTP (fetch/XHR), send-with-retry, worker‐bridge
3. Web Worker
- Receives raw payloads via `postMessage` for compression/deflate
- Sends compressed payloads back to SDK transport
4. Datadog Intake Endpoint
- REST API (multiple sites: US1, EU1, etc.)
5. Developer Extension (optional)
- Content script bridges SDK events to background
- Background <–> DevTools panel via messaging
b. Relationships & Data Flow
- App code → SDK boot → domain event collectors → batch controller →
either direct HTTP or Worker-driven deflate → HTTP request → Datadog endpoint
- Developer Extension path: SDK pipes events through `eventBridge` → content script → background → panel
- Test harness: E2E tests spin up mock intake servers and validate request flows
c. Key Architectural Patterns
- Modular monorepo: each feature (core, logs, rum, react integration) isolated in its package
- Plugin architecture: `rum-react` plugs into `rum-core` lifecycle hooks
- Event pipeline: observable streams → debouncing/rate‐limiting → batch → transport
- Worker offload: CPU‐heavy tasks (deflate) delegated to Web Worker
- Developer Extension: “extension as a thin client” with content scripts + background + React panel
d. Technologies & Frameworks
- TypeScript + Jest for code + specs
- Webpack for bundling per‐package (CJS & ESM targets)
- Playwright for E2E tests
- Lerna/Yarn workspaces for monorepo management
- Chrome Extension APIs + React for the developer panel

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% Monorepo and CI/CD
  Monorepo["Monorepo (Lerna & CI/CD)"]:::infra
  click Monorepo "https://github.com/datadog/browser-sdk/blob/main/lerna.json"
  click Monorepo "https://github.com/datadog/browser-sdk/blob/main/package.json"
  click Monorepo "https://github.com/datadog/browser-sdk/tree/main/.github/"
  click Monorepo "https://github.com/datadog/browser-sdk/blob/main/.gitlab-ci.yml"
  click Monorepo "https://github.com/datadog/browser-sdk/tree/main/scripts/"

  %% Application
  subgraph "User Application"
    WebApp["SPA Web Application"]:::app
  end

  %% SDK Foundation Layer
  subgraph "SDK Foundation (Blue)" 
    Core["browser-core"]:::core
    Logs["browser-logs"]:::core
    RumCore["browser-rum-core"]:::core
    Worker["Web Worker"]:::worker
  end
  click Core "https://github.com/datadog/browser-sdk/tree/main/packages/core/src/boot/"
  click Core "https://github.com/datadog/browser-sdk/tree/main/packages/core/src/domain/"
  click Core "https://github.com/datadog/browser-sdk/tree/main/packages/core/src/transport/"
  click Core "https://github.com/datadog/browser-sdk/tree/main/packages/core/test/"
  click Logs "https://github.com/datadog/browser-sdk/tree/main/packages/logs/src/boot/"
  click Logs "https://github.com/datadog/browser-sdk/tree/main/packages/logs/src/domain/"
  click Logs "https://github.com/datadog/browser-sdk/tree/main/packages/logs/src/transport/"
  click RumCore "https://github.com/datadog/browser-sdk/tree/main/packages/rum-core/src/boot/"
  click RumCore "https://github.com/datadog/browser-sdk/tree/main/packages/rum-core/src/domain/"
  click RumCore "https://github.com/datadog/browser-sdk/tree/main/packages/rum-core/src/transport/"
  click Worker "https://github.com/datadog/browser-sdk/tree/main/packages/worker/src/boot/"
  click Worker "https://github.com/datadog/browser-sdk/blob/main/packages/worker/src/domain/deflate.js"

  %% SDK Feature Layer
  subgraph "SDK Features (Green)"
    RumFull["browser-rum (Full)"]:::feature
    RumSlim["browser-rum-slim"]:::feature
    RumReact["rum-react"]:::feature
    Flagging["flagging"]:::feature
    Perf["performances"]:::feature
  end
  click RumFull "https://github.com/datadog/browser-sdk/tree/main/packages/rum/src/boot/"
  click RumFull "https://github.com/datadog/browser-sdk/tree/main/packages/rum/src/domain/deflate/"
  click RumSlim "https://github.com/datadog/browser-sdk/tree/main/packages/rum-slim/src/boot/"
  click RumReact "https://github.com/datadog/browser-sdk/tree/main/packages/rum-react/src/domain/"
  click Flagging "https://github.com/datadog/browser-sdk/tree/main/packages/flagging/src/entries/"
  click Perf "https://github.com/datadog/browser-sdk/tree/main/performances/src/"

  %% Developer Extension
  subgraph "Developer Extension (Purple)"
    Content["Content Script"]:::ext
    Background["Background Script"]:::ext
    Panel["DevTools Panel UI"]:::ext
  end
  click Content "https://github.com/datadog/browser-sdk/tree/main/developer-extension/src/content-scripts/"
  click Background "https://github.com/datadog/browser-sdk/blob/main/developer-extension/src/background/devtoolsPanelConnection.ts"
  click Panel "https://github.com/datadog/browser-sdk/tree/main/developer-extension/src/panel/"

  %% External Systems
  Intake["Datadog Intake Endpoint"]:::external
  Tests["Test Harness"]:::infra
  click Tests "https://github.com/datadog/browser-sdk/tree/main/test/e2e/"
  click Tests "https://github.com/datadog/browser-sdk/tree/main/test/unit/"

  %% Flow Connections
  WebApp -->|"import SDK (npm/CDN)"| Core
  Core -->|"boot:init()"| Logs
  Logs -->|"boot:startLogs()"| RumCore
  RumCore -->|"boot:startRum()"| RumFull
  RumFull -->|"startWorker()"| Worker
  RumFull -->|"eventListeners→contextManagers"| RumSlim
  RumFull -->|"plugins"| RumReact
  RumFull -->|"batchController"| Batch["Batch Controller"]:::transport
  Batch -->|"direct or deflate"| Worker
  Worker -->|"postMessage compressed"| Transport["HTTP Transport"]:::transport
  Batch -->|"HTTP POST" | Transport
  Transport -->|"send-with-retry"| Intake

  %% Extension Flow
  RumFull -->|"eventBridge"| Content
  Content -->|"message"| Background
  Background -->|"sync"| Panel

  %% Test Flow
  Tests -->|"mock intake"| Intake
  Tests -->|"validate flows"| Core

  %% Legend
  subgraph "Legend"
    A["Rectangle: Modules"] 
    B["Cylinder: External/Worker"]
    C["Rounded: Extension UI"]
    D["Blue: Core"] 
    E["Green: Features"] 
    F["Orange: Transport/Worker"]
    G["Purple: Extension"]
  end

  classDef core fill:#e0f7ff,stroke:#009ddc,color:#003d5b;
  classDef feature fill:#e8f5e9,stroke:#43a047,color:#1b5e20;
  classDef worker fill:#fff3e0,stroke:#fb8c00,color:#e65100;
  classDef transport fill:#fff3e0,stroke:#fb8c00,color:#e65100;
  classDef ext fill:#f3e5f5,stroke:#8e24aa,color:#4a148c;
  classDef external fill:#eeeeee,stroke:#666666,color:#333333;
  classDef infra fill:#f5f5f5,stroke:#999999,color:#424242;
  classDef app fill:#e3f2fd,stroke:#1e88e5,color:#0d47a1;
```
