# imnotbond/bb-tracker-template architecture

> Architecture diagram of the GitHub repository imnotbond/bb-tracker-template, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/imnotbond/bb-tracker-template
- Repository: https://github.com/imnotbond/bb-tracker-template

## Overview

bb-tracker is a browser and server-side conversion-tracking product for quiz, VSL, advertorial, landing-page, and Shopify funnels. The main path captures browser behavior and attribution in bb-tracker.js, sends events to the generic CAPI endpoint, resolves product/market pixels, and forwards events to TikTok and Meta. Shopify orders have a separate HMAC-verified Purchase path; a Meta relay supports Shopify Custom Pixels. The README also documents GTM/GA4 and browser-to-server deduplication. Source excerpts show the main calls; Shopify Custom Pixel and GTM/GA4 wiring is documented, not sampled.

Main entry points: [`api/capi/event.js`](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/event.js) (Browser event API), [`api/capi/shopify-purchase.js`](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/shopify-purchase.js) (Purchase webhook), [`bb-tracker.js`](https://github.com/imnotbond/bb-tracker-template/blob/master/bb-tracker.js) (Browser tracker), [`api/capi/meta-event.js`](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/meta-event.js) (Meta event relay)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser tracking"]
  node_tracker["Browser tracker<br/>[bb-tracker.js]"]
  node_gtm_ga4["GTM / GA4"]
  node_posthog["PostHog bridge"]
end

subgraph group_routing["Event routing"]
  node_event_api["Browser event API<br/>[event.js]"]
  node_meta_api["Meta event relay<br/>[meta-event.js]"]
  node_pixel_routing["Pixel configuration<br/>[_lib.js]"]
  node_event_mapping["Event mapping<br/>[_lib.js]"]
  node_payload_helpers["Payload helpers<br/>[_lib.js]"]
end

subgraph group_shopify["Shopify purchases"]
  node_purchase_api["Purchase webhook"]
end

subgraph group_delivery["CAPI delivery"]
  node_tiktok_capi["TikTok CAPI"]
  node_meta_capi["Meta CAPI"]
end

node_visitor(("Funnel visitor"))
node_shopify_pixel(("Shopify Custom Pixel"))
node_shopify_store(("Shopify store"))

node_visitor -->|"uses"| node_tracker
node_tracker -->|"posts events"| node_event_api
node_tracker -.->|"pushes events"| node_gtm_ga4
node_tracker -->|"bridges events"| node_posthog
node_shopify_store -->|"posts orders"| node_purchase_api
node_shopify_pixel -->|"relays events"| node_meta_api
node_event_api -->|"maps events"| node_event_mapping
node_event_api -->|"resolves pixels"| node_pixel_routing
node_event_api -->|"builds payloads"| node_payload_helpers
node_event_api -->|"sends events"| node_tiktok_capi
node_event_api -->|"sends events"| node_meta_capi
node_meta_api -->|"resolves pixel"| node_pixel_routing
node_meta_api -->|"builds payload"| node_payload_helpers
node_meta_api -->|"sends event"| node_meta_capi
node_purchase_api -->|"resolves pixels"| node_pixel_routing
node_purchase_api -->|"builds payloads"| node_payload_helpers
node_purchase_api -->|"sends purchase"| node_tiktok_capi
node_purchase_api -->|"sends purchase"| node_meta_capi

click node_tracker "https://github.com/imnotbond/bb-tracker-template/blob/master/bb-tracker.js"
click node_event_api "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/event.js"
click node_meta_api "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/meta-event.js"
click node_purchase_api "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/shopify-purchase.js"
click node_pixel_routing "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js"
click node_event_mapping "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js"
click node_payload_helpers "https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tracker,node_gtm_ga4,node_posthog toneBlue
class node_event_api,node_meta_api,node_pixel_routing,node_event_mapping,node_payload_helpers toneAmber
class node_purchase_api toneMint
class node_tiktok_capi,node_meta_capi toneRose
class node_visitor,node_shopify_pixel,node_shopify_store toneIndigo
```

## Components

### Browser tracking

- [Browser tracker](https://github.com/imnotbond/bb-tracker-template/blob/master/bb-tracker.js): `bb-tracker.js`
- **GTM / GA4**
- **PostHog bridge**

### Event routing

- [Browser event API](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/event.js): `api/capi/event.js`
- [Meta event relay](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/meta-event.js): `api/capi/meta-event.js`
- [Pixel configuration](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js): `api/capi/_lib.js`
- [Event mapping](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js): `api/capi/_lib.js`
- [Payload helpers](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/_lib.js): `api/capi/_lib.js`

### Shopify purchases

- [Purchase webhook](https://github.com/imnotbond/bb-tracker-template/blob/master/api/capi/shopify-purchase.js): `api/capi/shopify-purchase.js`

### CAPI delivery

- **TikTok CAPI**
- **Meta CAPI**

### Other components

- **Funnel visitor**
- **Shopify Custom Pixel**
- **Shopify store**

## Connections

- Funnel visitor → Browser tracker: uses (evidence: `README.md`)
- Browser tracker → Browser event API: posts events (evidence: `bb-tracker.js`)
- Browser tracker → GTM / GA4: pushes events (evidence: `README.md`)
- Browser tracker → PostHog bridge: bridges events (evidence: `bb-tracker.js`)
- Shopify store → Purchase webhook: posts orders (evidence: `README.md`)
- Shopify Custom Pixel → Meta event relay: relays events (evidence: `README.md`)
- Browser event API → Event mapping: maps events (evidence: `api/capi/event.js`)
- Browser event API → Pixel configuration: resolves pixels (evidence: `api/capi/event.js`)
- Browser event API → Payload helpers: builds payloads (evidence: `api/capi/event.js`)
- Browser event API → TikTok CAPI: sends events (evidence: `api/capi/event.js`)
- Browser event API → Meta CAPI: sends events (evidence: `api/capi/event.js`)
- Meta event relay → Pixel configuration: resolves pixel (evidence: `api/capi/meta-event.js`)
- Meta event relay → Payload helpers: builds payload (evidence: `api/capi/meta-event.js`)
- Meta event relay → Meta CAPI: sends event (evidence: `api/capi/meta-event.js`)
- Purchase webhook → Pixel configuration: resolves pixels (evidence: `api/capi/shopify-purchase.js`)
- Purchase webhook → Payload helpers: builds payloads (evidence: `api/capi/shopify-purchase.js`)
- Purchase webhook → TikTok CAPI: sends purchase (evidence: `api/capi/shopify-purchase.js`)
- Purchase webhook → Meta CAPI: sends purchase (evidence: `api/capi/shopify-purchase.js`)
