Heatmap Architecture

Complete data flow from user interaction to visualization with full session replay integration

50ms

Mouse Sampling

150ms

Scroll Sampling

10s

Flush Interval

100KB

Max Payload

Job Polling

📊 Data Flow Architecture

🌐SDK + rrweb

Customer's website
Captures interactions

📦Transport

Buffers events
100KB or 10s batches

🚢API /sdk/ingest

Receives chunks
Stores raw events

ClickHouse

replay_chunks →
heatmap_data

💻 SDK Configuration

rrweb Recording Settings

The SDK uses rrweb library to capture user interactions with optimized sampling

// recorder.ts - rrweb configuration
const recordingConfig = {
  mousemove: 50,        // Sample every 50ms during movement
  scroll: 150,          // Sample every 150ms (throttled)
  mouseInteraction: true // Capture all clicks (100%)
};

// Events captured:
// - MouseInteraction.Click → click coordinates
// - MouseMove → position arrays
// - Scroll → y-offset values
// - Viewport + screen size metadata

Aggregation Pipeline

Raw events are processed into aggregated heatmap data

// heatmapAggregator.ts - data processing
const aggregation = {
  source: 'replay_chunks',
  groupBy: 'hostname|urlPattern|deviceType',
  binning: {
    xPercent: 1,      // 1% increments (0-100)
    yAbsolute: 10,    // 10px increments
    scrollDepth: 5    // 5% increments
  }
};

// Output: heatmap_data table
// Engine: SummingMergeTree()
// Auto-sums 'count' on merge

⚙️ Processing Pipeline

1. SDK Capture

rrweb library recording

Clicks, moves, scrolls, viewport

2. Aggregation

Parse raw rrweb JSON

xPercent, yAbsolute, binning

3. ClickHouse

SummingMergeTree storage

Auto-sum counts, 1yr TTL

4. Frontend

Canvas rendering

Radial gradients, overlay

🎨 Canvas Rendering Algorithm

1. Draw Density Map

For each point, draw a radial gradient circle with alpha proportional to interaction count. Overlapping circles build up density.

2. Color Mapping

Read each pixel's alpha value. Use it as index into 256-color gradient palette (blue→green→yellow→red).

3. Composite Overlay

Overlay the colored heatmap on an iframe showing the actual website. Filter by device type and interaction type.

4. Device Widths

Responsive rendering at 375px (mobile), 768px (tablet), and 1280px (desktop) viewport widths.

🏆 Competitor Comparison

Feature	Claymore	Hotjar	MS Clarity	FullStory
Click Heatmap	✓ Yes	✓ Yes	✓ Yes	✓ Yes
Scroll Heatmap	Data only	✓ Visual	✓ Visual	✓ Visual
Mouse Movement	✓ Yes	✓ Yes	✗ No	✓ Yes
Session Replay	✓ Integrated	✓ Yes	✓ Yes	✓ Yes
Rage Click Detection	✗ No	✓ Yes	✓ Yes	✓ Yes
Element Attribution	Coords only	✓ CSS Selectors	✓ CSS Selectors	✓ CSS Selectors
Self-Hosted Option	✓ Full	✗ SaaS only	✗ SaaS only	✗ SaaS only
Data Ownership	✓ 100%	Shared	Microsoft	Shared
Pricing	Self-hosted	$32-171/mo	Free	$199+/mo
Real-time Processing	Job-based	✓ Near RT	✓ Near RT	✓ Near RT

📋 What We Have & What's Coming

✅ Available Now

Full session replay integration
Click and mouse movement heatmaps
Self-hosted with complete data ownership
Proven rrweb library (industry standard)
Efficient ClickHouse SummingMergeTree
URL pattern normalization
Device-type segmentation
Absolute Y positioning (document coords)

🚀 Coming Soon

Automatic scheduled aggregation
Element-based click tracking (CSS selectors)
Rage click detection
Scroll depth visualization
Dead click analysis
A/B test segmentation
AI-powered insights
Real-time heatmap streaming