# segmentio/analytics-next architecture

> Architecture diagram of the GitHub repository segmentio/analytics-next, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/segmentio/analytics-next
- Repository: https://github.com/segmentio/analytics-next

## Overview

- the browser SDK (“@segment/analytics-next” located in packages/browser) for web use and
- the Node SDK (“@segment/analytics-node” in packages/node) for server-side environments.
In addition, there is a host of supporting packages (such as packages/core, packages/generic-utils, packages/consent, packages/signals, etc.) and a robust set of integration and unit tests that underlie the overall functionality.

##### Main Components
- Browser SDK: Represented by the packages/browser directory. This package includes all browser-specific logic, integration tests, plugins, and polyfills.
- Node SDK: Shown with the packages/node folder, which contains the Node-specific analytics logic, server initialization, and supporting libraries.
- Core Libraries: Represent essential shared modules such as packages/core (event dispatch, callback handling, configuration, etc.) and packages/generic-utils.
- Plugins and Extensions: Several sub-packages under “plugins” exist both for browser and node (e.g., segmentio plugins, middleware, remote-loader, etc.) which encapsulate integration points for various destinations.
- Consent and Signals: The packages/consent and packages/signals directories (and their inner packages) manage compliance-related functionality and advanced signal processing.
- Configuration & Build Tools: Highlight the packages/config and packages/config-webpack for build configuration, the CI/CD tooling (present under .buildkite, .github, scripts), and other shared developer tools.
- Testing Infrastructure: Include the integration test suites (e.g., packages/browser-integration-tests, packages/node-integration-tests, packages/core-integration-tests, meta-tests and test-helpers directories) that validate product behaviors.

##### Out Relationships and Interactions
- That both SDKs share common utilities and plugins – drawing lines from them to the core libraries and generic utilities.
- Integration points between the consent/signals packages and the main SDKs (which likely wrap, modify, or intercept analytics events).
- Build and deployment pipeline components (CI/CD in .github workflows, Buildkite configurations, and scripts) which coordinate releases and testing.

##### Architectural Patterns and Design Principles
- Modular Monorepo Structure: Emphasize the separation of concerns between packages (SDKs, core libraries, plugins, consent/signals, configuration, and testing), which makes it easier to maintain and extend functionality.
- Layered Architecture: Show how high-level SDKs sit atop a shared core and plugin layer. This abstraction allows both browser and Node environments to reuse similar underlying logic.
- Integration & Pipeline Automation: Include CI/CD layers (with Buildkite, GitHub workflows, linting, and formatting tools) that automate testing, linting, and releasing processes.

##### Important Technologies and Tools
- Languages: Note the use of TypeScript and JavaScript as indicated by .ts/ .tsx files and TS configuration files.
- Testing: Emphasize integration with Jest, Playwright, and other test tools.
- Build Tools: Mark the build configuration tools such as Webpack, and scripts such as Makefiles and shell scripts.
- CI/CD Systems: Reflect the use of Buildkite, GitHub Actions workflows, and husky for pre-commit and pre-push hooks.
- Monorepo Management: The inclusion of Yarn (with Yarn 3 plugins) and Turbo (turbo.json) should be depicted to show how the packages are coordinated.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% SDK Layer
    subgraph "SDKs Layer"
        Browser_SDK["Browser SDK"]:::sdk
        Node_SDK["Node SDK"]:::sdk
    end

    %% Core Libraries
    subgraph "Core & Utilities"
        Core["Core Libraries"]:::core
        Generic_Utils["Generic Utils"]:::core
    end

    %% Plugins & Extensions
    subgraph "Plugins & Extensions"
        Browser_Plugins["Browser Plugins"]:::plugin
        Node_Plugins["Node Plugins"]:::plugin
    end

    %% Compliance & Signals
    subgraph "Compliance & Signals"
        Consent["Consent Tools"]:::compliance
        Signals["Signals Processing"]:::compliance
    end

    %% Configuration & Build Tools
    subgraph "Configuration & Build Tools"
        subgraph "Build Tools"
            Build_Config["Build Config"]:::build
            Webpack_Config["Webpack Config"]:::build
        end
        subgraph "CI/CD & Dev Tools"
            Buildkite["Buildkite"]:::build
            GitHub["GitHub Workflows"]:::build
            Scripts["Scripts"]:::build
        end
    end

    %% Testing Infrastructure
    subgraph "Testing Infrastructure"
        Browser_Tests["Browser Integration Tests"]:::test
        Node_Tests["Node Integration Tests"]:::test
        Core_Tests["Core Integration Tests"]:::test
        Meta_Tests["Meta Tests"]:::test
        Test_Helpers["Test Helpers"]:::test
    end

    %% Relationships from SDKs to Core & Plugins and Compliance
    Browser_SDK -->|"calls"| Core
    Browser_SDK -->|"calls"| Generic_Utils
    Browser_SDK -->|"loads"| Browser_Plugins
    Browser_SDK -->|"integrates"| Consent
    Browser_SDK -->|"integrates"| Signals

    Node_SDK -->|"calls"| Core
    Node_SDK -->|"calls"| Generic_Utils
    Node_SDK -->|"loads"| Node_Plugins
    Node_SDK -->|"integrates"| Consent
    Node_SDK -->|"integrates"| Signals

    %% Core provides extension points to Plugins
    Core -->|"extension"| Browser_Plugins
    Core -->|"extension"| Node_Plugins

    %% Build Tools build SDKs and Core
    Build_Config -->|"builds"| Browser_SDK
    Build_Config -->|"builds"| Node_SDK
    Build_Config -->|"builds"| Core
    Build_Config -->|"builds"| Generic_Utils

    %% CI/CD triggers testing
    GitHub -->|"triggers"| Browser_Tests
    GitHub -->|"triggers"| Node_Tests
    GitHub -->|"triggers"| Core_Tests
    GitHub -->|"triggers"| Meta_Tests
    GitHub -->|"triggers"| Test_Helpers

    %% Click Events
    click Browser_SDK "https://github.com/segmentio/analytics-next/tree/master/packages/browser"
    click Node_SDK "https://github.com/segmentio/analytics-next/tree/master/packages/node"
    click Core "https://github.com/segmentio/analytics-next/tree/master/packages/core"
    click Generic_Utils "https://github.com/segmentio/analytics-next/tree/master/packages/generic-utils"
    click Browser_Plugins "https://github.com/segmentio/analytics-next/tree/master/packages/browser/src/plugins"
    click Node_Plugins "https://github.com/segmentio/analytics-next/tree/master/packages/node/src/plugins"
    click Consent "https://github.com/segmentio/analytics-next/tree/master/packages/consent"
    click Signals "https://github.com/segmentio/analytics-next/tree/master/packages/signals"
    click Build_Config "https://github.com/segmentio/analytics-next/tree/master/packages/config"
    click Webpack_Config "https://github.com/segmentio/analytics-next/tree/master/packages/config-webpack"
    click Buildkite "https://github.com/segmentio/analytics-next/blob/master/.buildkite"
    click GitHub "https://github.com/segmentio/analytics-next/blob/master/.github"
    click Scripts "https://github.com/segmentio/analytics-next/tree/master/scripts"
    click Browser_Tests "https://github.com/segmentio/analytics-next/tree/master/packages/browser-integration-tests"
    click Node_Tests "https://github.com/segmentio/analytics-next/tree/master/packages/node-integration-tests"
    click Core_Tests "https://github.com/segmentio/analytics-next/tree/master/packages/core-integration-tests"
    click Meta_Tests "https://github.com/segmentio/analytics-next/tree/master/meta-tests"
    click Test_Helpers "https://github.com/segmentio/analytics-next/tree/master/packages/test-helpers"

    %% Styles
    classDef sdk fill:#e0bbff,stroke:#8a2be2,stroke-width:2px;
    classDef core fill:#bbd1f2,stroke:#0a74da,stroke-width:2px;
    classDef plugin fill:#c2f0c2,stroke:#228b22,stroke-width:2px;
    classDef compliance fill:#fff2b2,stroke:#f0ad4e,stroke-width:2px;
    classDef build fill:#ffd6d6,stroke:#ff4d4d,stroke-width:2px;
    classDef test fill:#d6ffff,stroke:#008b8b,stroke-width:2px;
```
