Architecture Overview

OneTrack is a comprehensive frontend tracking library designed with a modular architecture. This document provides an overview of the system design and key components.

High-Level Architecture

┌─────────────────────────────────────────────────────────────┐
│                     User Interactions                        │
│              (clicks, forms, page views, etc.)              │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Tracking Systems                          │
│         (click/, form/, input/, fetchInterceptor/)          │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                  Event Data Generation                       │
│         (50+ platform integrations in eventDataGeneration/) │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Rule Engine                             │
│      (triggers, conditions, actions, variables)             │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Compliance Check                           │
│           (consent management via compliance/)              │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                Third-Party Connections                       │
│       (Meta, TikTok, Google, LinkedIn, Pinterest)           │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   Server Connection                          │
│              (event dispatch, recovery, ASL)                │
└─────────────────────────────────────────────────────────────┘

Directory Structure

lib/
├── index.ts                 # Main entry point
├── config.ts                # Server configuration
│
├── scriptLoading/           # Initialization system
│   ├── configLoader.ts      # Configuration loading
│   ├── compileMe.ts         # Core compilation
│   └── clientScript.js      # Client-side script
│
├── eventDataGeneration/     # Event generation
│   ├── basic/               # Core events (pageView, click, etc.)
│   └── [50+ integrations]   # Platform-specific
│
├── tracking/                # Tracking systems
│   ├── click/               # Click tracking
│   ├── form/                # Form submission tracking
│   ├── input/               # Input monitoring
│   └── fetchInterceptor/    # HTTP interception
│
├── ruleEngine/              # Event processing
│   ├── core/                # RuleEngine class
│   ├── triggers/            # Trigger matching
│   ├── conditions/          # Condition evaluation
│   ├── actions/             # Action execution
│   ├── variables/           # Variable resolution
│   └── debug/               # Debug system
│
├── thirdPartyConnections/   # Platform integrations
│   ├── meta/                # Facebook/Instagram
│   ├── tiktok/              # TikTok
│   ├── google/              # GA4, GTM, gtag
│   ├── linkedin/            # LinkedIn Insight
│   └── pinterest/           # Pinterest Tag
│
├── serverConnection/        # Server communication
│   ├── eventDispatcher.ts   # Event sending
│   ├── eventBuilder.ts      # Event construction
│   └── asl/                 # Automatic Script Loading
│
├── data/                    # Data management
│   ├── cleaning/            # Data sanitization
│   ├── comparison/          # Validation
│   ├── personalData/        # PII handling
│   └── storage/             # localStorage utils
│
└── compliance/              # Consent management
    ├── cookiebot/
    ├── klaro/
    ├── iubenda/
    └── complianz/

Key Components

1. Script Loading System

Handles OneTrack initialization with localStorage caching for performance:

• First-party cookie matching by TLD+1 domain detection
• Multiple fallback mechanisms
• Async loading without blocking page render

2. Event Generation

Transforms platform-specific data into OneTrack's unified event schema:

• 50+ platform integrations (Shopify, Magento, ClickFunnels, etc.)
• Self-contained transformation logic per platform
• Automatic detection and loading via ASL

3. Rule Engine

Configurable event processing without code changes:

• Triggers: When rules fire (events, scroll, time, postMessage)
• Conditions: If rules should execute (operators, transforms)
• Actions: What rules do (fire, suppress, modify)
• Variables: Dynamic values (dataLayer, DOM, cookies, etc.)

Detailed Rule Engine Documentation →

4. Third-Party Connections

Manages event dispatch to marketing platforms:

• Meta/Facebook with advanced matching
• TikTok with pixel integration
• Google (GTM, GA4, gtag)
• LinkedIn Insight tag
• Pinterest conversion tracking

5. Server Connection

Handles event dispatch and recovery:

• Async event dispatch with Promise support
• Automatic retry and recovery
• ASL for dynamic adapter loading

Event Flow

1. User Action
   └─→ Tracking system captures interaction

2. Event Generation
   └─→ Platform integration transforms to OneTrack schema

3. Rule Engine Processing
   └─→ Triggers matched → Conditions evaluated → Actions executed

4. Compliance Check
   └─→ Consent status verified

5. Third-Party Dispatch
   └─→ Events sent to configured platforms

6. Server Communication
   └─→ Events sent to OneTrack servers

Module System

Uses @onetrack/* path mapping (configured in tsconfig.json):

import { processEventThroughRules } from '@onetrack/ruleEngine';
import { dispatchEvent } from '@onetrack/serverConnection';

Build System

• Webpack for production bundling
• TypeScript with ES2022 target
• Obfuscation in production builds
• Console.log removal in production (preserved in debug builds)

Testing

• Jest with jsdom environment
• Browser API mocking (localStorage, cookies)
• Event simulation for click/form/input testing
• Test files in *.test.ts format