How elbwalker/walkeros works
Project Type and Purpose
• This is a modular, full-stack monorepo for an open-source event data collection and tag management platform (walkerOS).
• It provides:
• Sources packages (data collection in various environments: browser, Node.js, GCP, dataLayer)
• Destinations packages (mapping and forwarding events to third-party tools)
• Shared utilities and types
• Configuration packages for linting, testing, builds
• Demo apps (React, static tagging demo) and a documentation website
Main Architectural Components
a. Monorepo Orchestrator
• Turbo (turbo.json) coordinates builds, tests, and deployments across all packages/apps.
• Root-level config: ESLint, Prettier, VSCode, GitHub workflows.
b. Core Libraries
• packages/types: shared event and API type definitions
• packages/utils: low-level helpers for event construction, consent, session, network calls
• packages/config: ESLint, Jest, tsconfig, tsup presets for consistent setup
c. Sources Layer (Collection)
• packages/sources/*: implement “push” interfaces and state management for each environment
• walkerjs (browser), node, dataLayer, GCP, custom “tagger” CLI
d. Destinations Layer (Activation)
• packages/destinations/*: for each tool (AWS Firehose, BigQuery, Google Ads, GA4, GTM, Meta Pixel, Plausible, Piwik Pro, generic API)
• Each destination package consumes events, applies mapping, forwards via HTTP/SDK
e. Demos and Website
• apps/demos: quickstart React and plain JS tagging examples illustrating integration of Sources → Destinations
• website: Docusaurus-based documentation and marketing site
Data Flow and Interactions
• Application Code (demo or customer app) imports a Source package → calls push(event)
• Source layer enriches event (session, device, consent) and emits it to a generic pipeline → Utils functions handle retries, error handling
• Destinations layer subscribes to pipeline output, maps events per destination config → forwards to external Tools (Analytics, Storage, Marketing)
• Types package ensures schema consistency end-to-end
• CI/CD pipelines (GitHub Actions) run lint/tests/build for every package
Architectural Patterns and Principles
• Monorepo with package-per-concern: clear separation of collection vs activation
• Shared core (utils, types, config) encourages DRY and consistency
• Plugin-style destinations allow easy extensibility (add new third-party integrations)
• Turbo-driven incremental builds for scale
• Test-first approach: each package has its own Jest config and suite