Tech Documentation

Internal technical documentation for the OneTrack engineering team. This section covers architecture, implementation details, and design decisions.

Architecture Overview

OneTrack is a comprehensive frontend tracking library with a modular architecture:

lib/
├── scriptLoading/       # Initialization & caching
├── eventDataGeneration/ # 50+ platform integrations
├── tracking/            # Click, form, input tracking
├── ruleEngine/          # Configurable event processing
├── thirdPartyConnections/ # Meta, TikTok, Google, etc.
├── serverConnection/    # Event dispatch & ASL
├── data/                # Storage & validation
└── compliance/          # Consent management

Full Architecture Overview →

Rule Engine

The Rule Engine is a core component enabling runtime behavior modification:

Document	Description
Architecture	Directory structure & processing pipeline
Core Processing	RuleEngine class & workspace isolation
Triggers	TriggerMatcher & background monitors
Conditions	ConditionEvaluator & operators
Variables	VariableResolver & path resolution
Debug System	PostMessage broadcasting
Performance	O(1) indexing & optimizations

Key Design Decisions

Workspace Isolation

Events are deep-cloned per workspace to prevent cross-workspace contamination:

// core/ruleEngine.ts:329
const workspaceEventClone = deepClone(event);

O(1) Trigger Matching

TriggerMatcher uses Map-based indexing for constant-time lookup regardless of rule count:

// triggers/TriggerMatcher.ts:25-83
private eventTypeIndex: Map<string, Set<Rule>> = new Map();

Infinite Loop Prevention

Recursion depth is tracked and limited to prevent circular rule execution:

// core/ruleEngine.ts:127-128
private static readonly MAX_RECURSION_DEPTH = 10;

Quick Reference

Entry Points

import {
  initializeRuleEngine,
  processEventThroughRules,
  enableRuleEngineDebug
} from '@onetrack/ruleEngine';

// Initialize
initializeRuleEngine();

// Process event
const processedEvents = processEventThroughRules(event);

// Enable debug
enableRuleEngineDebug();

Key Files

File	Purpose	Lines
core/ruleEngine.ts	Main processing	1349
interface.ts	Type definitions	506
triggers/TriggerMatcher.ts	O(1) matching	~150
conditions/conditionEvaluator.ts	Condition logic	~800
variables/variableResolver.ts	Variable resolution	~300

Development

Build Commands

npm run build          # Production build
npm run build:debug    # Debug build (console.log preserved)
npm run test           # Run tests

Testing

Tests are in lib/ruleEngine/tests/unit/ with 40+ test files covering:

• Trigger matching
• Condition evaluation
• Action execution
• Variable resolution
• Background monitors

Contributing

When modifying the Rule Engine:

1. Read the relevant documentation first
2. Follow existing patterns
3. Add tests for new functionality
4. Update documentation if needed
5. Run the full test suite before committing