MouseFlow — Systems Telemetry Utility

A high-performance Java desktop utility that intercepts and normalizes global mouse telemetry at the OS level. Built with JNA (Java Native Access) against the Win32 API, it captures high-frequency cursor data across all applications — not just its own window — for use in UX heatmaps, productivity analysis, and behavioral research.

Tech Stack

Java 21 JavaFX 21 JNA 5.13 JNativeHook 2.1 Maven Win32 API

Architecture

Windows OS
    │  WH_MOUSE_LL (SetWindowsHookEx via JNativeHook)
    ▼
App.java  ─── Engine thread (40ms pulse)
    │           ├─ Win32 calls via JNA: GetForegroundWindow, WindowFromPoint
    │           ├─ Weighted-pulse CSV logging (5px deadzone, accumulated dwell time)
    │           └─ Platform.runLater → UI updates
    ▼
TrackerUI.java  ─── JavaFX Application thread
                        ├─ Live stats: X/Y, active window, window under cursor
                        ├─ Resizable path canvas (multi-monitor normalized)
                        └─ Dark themed dashboard
    ▼
logs/mouse_log_<timestamp>.csv
    (timestamp, ActiveWindow, HoveredWindow, x, y, durationMS)

Key Design Decisions

Weighted-Pulse Logging

Instead of writing every mouse-move event to disk (which at native polling rates would saturate I/O), the engine fires every 40ms and only commits a CSV row when the cursor has moved ≥5px or the active window has changed. During idle periods it accumulates a durationMS counter — capturing both trajectory and dwell time while keeping disk I/O minimal.

Multi-Monitor Coordinate Normalization

Windows reports coordinates relative to the primary monitor, producing negative values or dead zones in staggered multi-monitor setups. The UI queries all Screen bounds via JavaFX to compute the total virtual desktop, then normalizes raw hook coordinates to canvas-relative percentages — ensuring the path trail is accurate regardless of monitor arrangement.

Thread Isolation

The Win32 low-level hook runs on a dedicated worker thread. All UI mutations are marshaled to the JavaFX Application thread via Platform.runLater(), preventing the hook's message pump from blocking (which would cause system-wide input lag or hook timeouts).

Building & Running

Requires Java 21+ and Maven. The global mouse hook works out of the box on Windows.

mvn compile      # compile
mvn exec:java    # launch (UI + tracking)
mvn javafx:run   # alternative launcher

Performance

• CPU overhead: sub-1% during active telemetry ingestion
• Polling rate: 25 Hz (40ms fixed-rate pulse)
• Capture fidelity: 100% across multi-monitor 4K setups
• Disk I/O: minimal — writes only on significant movement or window switch

Project Roadmap

• Phase I: Core Ingestion — Low-level hook, coordinate normalization, weighted-pulse CSV logging
• Phase IV: Visualization — JavaFX dashboard with live stats and resizable path trail canvas
• Phase II: Persistence — Replace raw CSV with SQLite for structured telemetry storage
• Phase III: Analytics — Distance-traveled calculations, dwell heatmaps, efficiency heuristics