Production Architecture

Overlay engine

The overlay engine runs inside the viewer's browser. ReactionSDK loads your marketing video element (or reaction-video), attaches overlays (tap, rating, poll, slider, CTA), and captures those interactions. Recorded video reactions are handled by ReactifySDK, not this overlay ingest path.

flowchart LR
  subgraph Client["Browser"]
    Video[Video element]
    Engine[Overlay engine]
    Tap[Tap overlay]
    Rating[Rating overlay]
    Poll[Poll overlay]
    Slider[Slider overlay]
    CTA[CTA overlay]
    Video --> Engine
    Engine --> Tap
    Engine --> Rating
    Engine --> Poll
    Engine --> Slider
    Engine --> CTA
    Tap --> Events[Event queue]
    Rating --> Events
    Poll --> Events
    Slider --> Events
    CTA --> Events
  end
  Events --> Ingest[POST /api/events/ingest]

• SDK initializes with API key and optional config (overlays, position, CTA).
• Overlays render as DOM overlays on top of the video; interactions are queued and sent with deviceHash, sessionId, campaignId.
• Recording consent and campaign rules gate optional capture flows; usage caps can return throttling from ingest.

Event ingestion

Events from the SDK hit POST /api/events/ingest (and the legacy POST /api/sdk/event). The ingest layer validates the Bearer API key, enforces origin allowlist (CORS), applies fraud controls (rate limit per key and per device, throttle, view uniqueness), and writes to the unified event store. Billing and webhooks are triggered from the same path.

flowchart TB
  SDK[SDK: sendEvent]
  Ingest[POST /api/events/ingest]
  Auth[Validate API key]
  Origin[Origin allowlist]
  Fraud[Fraud: rate limit, throttle, dedup]
  Cap[Usage cap check]
  Norm[Normalize event]
  Store[recordEvent → events]
  Billing[recordImpressionUsage / recordInteractionUsage]
  Webhook[Webhook dispatch]
  SDK --> Ingest
  Ingest --> Auth
  Auth --> Origin
  Origin --> Fraud
  Fraud --> Cap
  Cap --> Norm
  Norm --> Store
  Store --> Billing
  Store --> Webhook

• Impressions are deduplicated by (accountId, campaignId, userId); duplicates return 202 with duplicate: true.
• Fraud blocks (per-key and per-device limits, throttle minutes) protect against abuse; suspended or insufficient-funds accounts receive 403.

Analytics pipeline

The analytics pipeline is built on a single events collection (MongoDB). Each document represents one impression or interaction: eventType, campaignId, deviceHash, timestamp, watchedSeconds, interactionType, value, etc. Aggregation services (dashboard-metrics, creative engagement timeline, top creative, hook strength, engagement momentum) query this collection by accountId and optional campaignId/date range to compute metrics, heatmaps, and scores.

flowchart LR
  Events[(events collection)]
  DM[dashboard-metrics]
  CET[creativeEngagementTimeline]
  TCS[topCreativeService]
  HS[hookStrength]
  EM[engagementMomentum]
  Events --> DM
  Events --> CET
  Events --> TCS
  Events --> HS
  Events --> EM
  DM --> API[GET /api/dashboard/analytics]
  CET --> API2[GET /api/dashboard/creative-engagement-timeline]
  TCS --> API3[GET /api/dashboard/top-performing-video]
  HS --> API4[GET /api/dashboard/hook-strength-trend]
  EM --> API5[GET /api/dashboard/engagement-momentum]

• Metrics include impressions, interactions, interaction rate, completion rate, dropoff curve, interaction heatmap (0–2s, 2–4s, …), creative score, hook strength, engagement momentum.
• Plan gating: some endpoints (e.g. creative intelligence, top-performing video) require Professional or higher.

Template system

The template system provides starter repos (Next.js, React, HTML, Vercel one-click) that developers can duplicate from the docs or the marketplace. Templates are defined in lib/templates.ts; each has an id, name, SDK(s), duplicateUrl (GitHub "Use this template" or Vercel clone), and optional framework. Duplicate actions are tracked as template_installs in developer telemetry.

flowchart TB
  Docs[/docs/templates]
  Market[/templates]
  Data[lib/templates.ts: TEMPLATES]
  Card[TemplateCard: Duplicate template]
  GitHub[GitHub Use this template]
  Vercel[Vercel clone]
  Telemetry[developer_telemetry: template_installs]
  Data --> Docs
  Data --> Market
  Docs --> Card
  Market --> Card
  Card --> GitHub
  Card --> Vercel
  Card --> Telemetry

• Docs templates for ReactionSDK point to duplicate starter repos (GitHub / Vercel); Reactify thread templates live under /templates/reactify (legacy /reactify/templates redirects).
• Developer telemetry stores templateId and templateName for funnel analytics.

Cold storage

Today all events are stored in the primary MongoDB events collection. The architecture is designed to evolve with a cold storage layer: older events can be rolled up or archived to cheaper storage (e.g. object store or a dedicated archive cluster) for compliance, long-term analytics, and cost control. Hot path (recent events) remains in MongoDB for real-time dashboard and alerts; cold data can be used for historical reporting and re-aggregation.

flowchart LR
  Events[(events - hot)]
  Rollup[Rollup / archive job]
  Cold[(cold storage)]
  Analytics[Historical analytics]
  Events --> Rollup
  Rollup --> Cold
  Cold --> Analytics

• No cold storage implementation yet; document describes the intended direction (rollup, archive, intelligence layers) for production at scale.

Dashboard

The dashboard is an authenticated Next.js app that reads from dashboard APIs. It displays overview metrics (impressions, interactions, engagement rate), campaign and creative breakdowns, interaction heatmaps, dropoff curves, creative performance score, hook strength, engagement momentum, alerts, and (on higher tiers) top-performing video and creative engagement timeline. Data is scoped by account and optional campaign/date filters.

flowchart TB
  User[User: Dashboard UI]
  Auth[Bearer token / session]
  Overview[GET /api/dashboard/analytics]
  Creative[GET /api/dashboard/creative-*]
  Top[GET /api/dashboard/top-performing-video]
  Timeline[GET /api/dashboard/creative-engagement-timeline]
  Hook[GET /api/dashboard/hook-strength-trend]
  Momentum[GET /api/dashboard/engagement-momentum]
  User --> Auth
  Auth --> Overview
  Auth --> Creative
  Auth --> Top
  Auth --> Timeline
  Auth --> Hook
  Auth --> Momentum
  Overview --> Metrics[dashboard-metrics]
  Creative --> Metrics
  Top --> topCreativeService
  Timeline --> creativeEngagementTimelineService
  Hook --> hookStrengthTrendService
  Momentum --> engagementMomentum
  Metrics --> Events[(events)]

• Capability cards show progress toward plan limits; feature gates (e.g. Professional) restrict access to intelligence and creative endpoints.

Event flow: SDK to analytics dashboards

End-to-end path of an event from the viewer's browser to the dashboard.

sequenceDiagram
  participant Viewer
  participant SDK
  participant Ingest
  participant Store
  participant Billing
  participant Webhook
  participant Agg
  participant Dashboard

  Viewer->>SDK: Interact with overlay (tap, rating, poll, etc.)
  SDK->>SDK: Build payload (campaignId, eventType, deviceHash, sessionId, value, timestamp)
  SDK->>Ingest: POST /api/events/ingest (Bearer API key, Origin)
  Ingest->>Ingest: Validate key, origin, fraud, usage cap
  Ingest->>Store: recordEvent() → events collection
  Ingest->>Billing: recordImpressionUsage / recordInteractionUsage (Stripe meter)
  Ingest->>Webhook: dispatchWebhookEvent (if configured)
  Ingest-->>SDK: 202 Accepted

  Note over Agg,Dashboard: On dashboard load or refresh
  Dashboard->>Agg: GET /api/dashboard/analytics (and other endpoints)
  Agg->>Store: Aggregate events by accountId, campaignId, date
  Agg-->>Dashboard: metrics (impressions, interactions, heatmap, scores, etc.)
  Dashboard->>Viewer: Render charts and cards

1. Viewer interacts with an overlay (tap, rating, poll vote, CTA click, or playback events like impression, completion, dropoff).
2. SDK builds a canonical payload and sends it to POST /api/events/ingest with the account's API key and the page origin.
3. Ingest validates the key, checks origin allowlist, runs fraud controls (rate limit, throttle, dedup), normalizes the event, and writes to the events collection. It also records usage for billing and dispatches webhooks if configured.
4. Dashboard requests metrics via GET /api/dashboard/analytics and related endpoints. Aggregation services read from the same events collection and return precomputed or on-demand metrics (impressions, interaction rate, heatmaps, creative score, etc.).