Behavioral Event Pipeline Design

Companion write-up for Product Analytics Pipeline.

Problem

Telemetry calls sat directly on vendor SDKs inside feature views:

1. Sandbox leakage — missing or inline env guards let staging events into production Amplitude projects
2. Duplicate spikes — re-renders and auth toggles re-fired .identify() and events, skewing funnels
3. Chatty network — high-frequency actions paid one HTTP request each on poor mobile links

Constraints

• Identical behavior on Flutter mobile and web
• User/company traits attached automatically, not hand-copied at every call site
• Events must survive disconnects and app restarts without blocking the UI

Approach

A single ProductAnalytics facade implements AnalyticsProvider and owns routing, dedup, and accumulation:

flowchart TD
  App[Feature Action Sites] -->|AppEvent Payload| Facade[ProductAnalytics Facade]
  Facade --> Env{Environment Guard}
  Env -->|Sandbox/Dev| DevLogs[Console Mock Logger]
  Env -->|Production| Filter[Sliding-Window Deduplication]
  Filter -->|Duplicate Hash| Drop[Silent Drop]
  Filter -->|Unique Event| Route{Route}
  Route -->|Standard Event| Amp[AmplitudeProvider]
  Route -->|High-Frequency Activity| Accumulator[CrmActivityAccumulator]
  Accumulator -->|Persist| HiveStore[(Hive)]
  HiveStore -->|Flush on Idle| Amp
  Amp -->|Batch HTTP| RemoteCloud[Analytics Destination]

Pieces that matter

1. Vendor-agnostic facade — feature code does not import Amplitude
2. Sliding-window dedup — payload hashes suppress duplicates inside the window
3. Hive accumulator — high-frequency activity survives restarts and flushes in batches
4. Environment isolation — sandbox/dev routes to mock logging by default

Outcomes (high confidence)

• Offline and flaky-network sessions stop silently dropping buffered activity once connectivity returns
• Sandbox pollution of production dashboards stopped after env routing lived in one place
• High-frequency actions stopped issuing one request per tap

Absolute delivery guarantees are not claimed here — they would need verified ops metrics. The architectural intent is persistence before transmit, not marketing uptime language.