# snowplow/snowplow-javascript-tracker architecture

> Architecture diagram of the GitHub repository snowplow/snowplow-javascript-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/snowplow/snowplow-javascript-tracker
- Repository: https://github.com/snowplow/snowplow-javascript-tracker

## Overview

##### Main Components
- Monorepo Structure managed by Rush – At the highest level, note that this is a monorepo with a “rush.json” file and various common configurations (found in the “common” directory). This organizes multiple packages into a cohesive development and build environment.
- Core Libraries:
– “libraries/browser-tracker-core” and “libraries/tracker-core” represent the fundamental functionalities (such as event creation, payload building, emitting, and state management) shared by the trackers.
- Tracker Packages:
– “trackers/browser-tracker”, “trackers/javascript-tracker”, “trackers/node-tracker”, and “trackers/react-native-tracker” are the project’s different implementations for various platforms.
– These components wrap the core libraries and add platform-specific logic.
- Plugins:
– The “plugins” directory contains many browser plugins (like ad tracking, button click tracking, enhanced-ecommerce, error tracking, etc.). Each plugin module extends the native tracking functionality.
– They integrate with the tracker packages and core libraries to add extra event context or functionality.
- API Documentation:
– The “api-docs” directory contains the documentation system (built likely with Docusaurus); it is instrumental in explaining API usage, but is not part of runtime execution.
- Supporting Scripts and Configuration:
– The “common” directory includes scripts (like auto-installers, git hooks, and build tools), rush configuration files, and version/packaging policies.
– Other configuration files (e.g., .eslintrc.js, .prettierrc, Rollup configurations in many packages) indicate standardized build and style practices.

##### Relationships and Interactions
- The plugins “hook” into the trackers, meaning that they are dynamically loaded or registered—show these as interfacing between the tracker packages and the core functionality.
- Although not shown as an HTTP layer, add an external “Snowplow Collector/Endpoint” component that receives events; the emitter sends data to this external service.

##### Architectural Patterns and Design Principles
- Modularity: The design splits functionalities into trackers, shared libraries, and plugins, following separation of concerns. Each package is independent yet interacts via well-defined interfaces.
- Extensibility: The plugins architecture allows additional tracking behaviors to be mixed into the tracker’s data collection workflow.
- Monorepo Management: Use of Rush, a common configuration folder in “common”, and shared dependencies ensures consistency across packages.
- Cross-platform Support: With distinct trackers for browser, Node.js, React Native, etc., emphasize the pattern of platform-specific adaptations built on top of common core services.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Monorepo Structure
    subgraph "Monorepo Structure"
        MONO_RUS["Rush Config (rush.json)"]:::config
        MONO_COMMON["Common Config & Scripts (common)"]:::config
    end

    %% Core Libraries
    subgraph "Core Libraries"
        CTRK_CORE["Tracker Core (libraries/tracker-core)"]:::core
        BROWSER_CORE["Browser Tracker Core (libraries/browser-tracker-core)"]:::core
    end

    %% Tracker Packages
    subgraph "Tracker Packages"
        BROWSER_TRACKER["Browser Tracker (trackers/browser-tracker)"]:::tracker
        JS_TRACKER["JavaScript Tracker (trackers/javascript-tracker)"]:::tracker
        NODE_TRACKER["Node Tracker (trackers/node-tracker)"]:::tracker
        RN_TRACKER["React Native Tracker (trackers/react-native-tracker)"]:::tracker
    end

    %% Plugins Layer
    subgraph "Plugins"
        PLUGINS["Browser Plugins (plugins)"]:::plugin
    end

    %% Supporting Documentation & Build
    subgraph "Documentation & Tooling"
        API_DOCS["API Documentation (api-docs)"]:::docs
        BUILD["Build & Test Infrastructure (Rush, Scripts)"]:::build
    end

    %% Emitter and External Service
    EMITTER["Emitter Module"]:::emitter
    EXTERNAL["Snowplow Collector (External)"]:::external

    %% Relationships - Event Flow & Dependencies
    %% Tracker Packages use Core Libraries
    BROWSER_TRACKER -->|"calls"| BROWSER_CORE
    BROWSER_TRACKER -->|"calls"| CTRK_CORE
    JS_TRACKER     -->|"calls"| CTRK_CORE
    NODE_TRACKER   -->|"calls"| CTRK_CORE
    RN_TRACKER     -->|"calls"| CTRK_CORE

    %% Plugins enhance Tracker functionality
    PLUGINS -->|"enhances"| BROWSER_TRACKER

    %% Core Libraries emit events via Emitter
    CTRK_CORE    -->|"emits_events"| EMITTER
    BROWSER_CORE -->|"emits_events"| EMITTER

    %% Emitter sends data to External Service
    EMITTER -->|"sends_data"| EXTERNAL

    %% Build & Test flow from Monorepo configs
    MONO_RUS   -->|"builds"| BUILD
    MONO_COMMON-->|"provides_scripts"| BUILD

    %% Style definitions
    classDef config fill:#f4d03f,stroke:#000,stroke-width:2px;
    classDef core fill:#85c1e9,stroke:#000,stroke-width:2px;
    classDef tracker fill:#82e0aa,stroke:#000,stroke-width:2px;
    classDef plugin fill:#f7dc6f,stroke:#000,stroke-width:2px;
    classDef docs fill:#d7bde2,stroke:#000,stroke-width:2px;
    classDef build fill:#f5b7b1,stroke:#000,stroke-width:2px;
    classDef emitter fill:#f0b27a,stroke:#000,stroke-width:2px;
    classDef external fill:#e59866,stroke:#000,stroke-width:2px;

    %% Click Events
    click MONO_RUS "https://github.com/snowplow/snowplow-javascript-tracker/blob/master/rush.json"
    click MONO_COMMON "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/common"
    click BROWSER_CORE "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/libraries/browser-tracker-core"
    click CTRK_CORE "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/libraries/tracker-core"
    click BROWSER_TRACKER "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/trackers/browser-tracker"
    click JS_TRACKER "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/trackers/javascript-tracker"
    click NODE_TRACKER "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/trackers/node-tracker"
    click RN_TRACKER "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/trackers/react-native-tracker"
    click PLUGINS "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/plugins"
    click API_DOCS "https://github.com/snowplow/snowplow-javascript-tracker/tree/master/api-docs"
```
