FlowMap

An institutional-grade, dual-market order-flow visualizer — real-time liquidity heatmap, DOM ladder, time & sales, and order-flow overlays for crypto and US equities, in one renderer.

_{Live binance-spot:BTCUSDT — WebGL2 liquidity heatmap, DOM ladder, and tick tape, ~15 minutes into a session. Columns are rasterized once on the GPU, so pan/zoom cost never grows with history.}

FlowMap is a ground-up rebuild of an earlier PyQt6 desktop app that re-rasterized the entire visible history on the CPU every pan/zoom frame, so scrolling back through history collapsed to ~1 fps. FlowMap puts history in a WebGL2 texture and makes pan/zoom a pure view transform — interaction cost is independent of history depth. It unifies two market-data engines (Crypcodile for crypto, stockodile for US equities) behind one market-agnostic renderer.

Highlights

• 60 fps pan/zoom at any history depth. A column, once uploaded to the GPU, is never re-rasterized; pan and both zoom axes only change a uniform. Measured: draw cost is ~0.2 ms whether 200 or 10 000 columns are resident (history-independent — the old 1-fps bug is structurally gone).
• Professional order flow: liquidity heatmap (thermal, with correct SUM-mip zoom-out so walls don't dilute), DOM ladder, time & sales tape, trade bubbles, BBO, VWAP, volume profile, event markers, crosshair with exact liquidity readout, deep scroll-back, replay transport.
• Two markets, one renderer, honest tiers: crypto shows full L2 depth + tick tape; US equities show what their free data actually supports — a keyless two-sided volume-at-price SYNTH depth (Yahoo 1 m bars, bid below / ask above a reference price that tracks the market) that upgrades to real Alpaca IEX L1 top-of-book with zero code change when ALPACA_API_KEY/SECRET are set. Synthetic depth renders in a distinct amber ramp and carries a SYNTH badge — capability badges (L2 / L1 / SYNTH, TAPE TICK / TAPE POLL, SIDE EXCHANGE / SIDE NA) are always honest, no fabricated depth.

Screenshots

equity:AAPL on the keyless SYNTH tier, replaying a recorded market-hours session — distinct amber ramp, honest SYNTH / TAPE POLL badges, market-closed banner, synthetic book in the DOM.	sim:SIM-DEMO deterministic feed — liquidity walls, buy/sell trade bubbles, VWAP line, and LIQ liquidation event markers.
Crosshair with the exact per-cell readout: source tier, column timestamp, price, and resting bid/ask liquidity.	The display pipeline is live: contrast (gamma), colormap, normalization percentile, tick grouping, bubble threshold, and per-overlay toggles.

Architecture

client/   TypeScript + React + WebGL2 renderer (Vite)
          heatmap tile-array + SUM-mips + camera + overlays + DOM/tape + UI shell
server/   Python 3.13 asyncio gateway (FastAPI, binary WebSocket, loopback-only)
          time-weighted density grid + sessions + parquet recording/replay
          feeds/  crypto (Crypcodile) · equity (stockodile) · deterministic sim

The client is a pure renderer of a canonical binary stream (docs/superpowers/specs/); the server normalizes every market into that stream + a capability descriptor. See docs/superpowers/plans/m1-verification.md, m2-verification.md, m3-verification.md for the verification record (live Binance + live equity evidence, perf gates, parity matrix).

Install (macOS)

Download FlowMap_1.1.0_aarch64.dmg from the latest release, open it, and drag FlowMap.app to Applications. The app is fully self-contained — it bundles the client and the Python server, so there is nothing else to install (no Python, no Node).

First launch — Gatekeeper. The app is ad-hoc signed but not notarized (that needs a paid Apple Developer ID, which this project doesn't have), so macOS will warn on first open. Either right-click → Open (then confirm once), or run once in Terminal: xattr -cr /Applications/FlowMap.app. After that it launches normally.

Apple Silicon only. Intel Macs and other platforms: run from source (below).

Run it

Prereqs: Python 3.13 + uv, Node 22 + npm.

./scripts/dev.sh          # boots the server (:8720) + the client dev server (:5173)
# then open http://localhost:5173

Or manually:

# terminal 1 — server
cd server && uv sync && FLOWMAP_PORT=8720 uv run python -m flowmap_server
# terminal 2 — client
cd client && npm install && npm run dev

In the top-bar symbol search: pick SIM-DEMO (deterministic demo feed), a crypto pair (BTCUSDT → live Binance), or a US ticker (AAPL → keyless two-sided SYNTH depth; real Alpaca L1 top-of-book + live tick during market hours with Alpaca keys).

Optional live tiers (auto-detected from the environment): ALPACA_API_KEY + ALPACA_API_SECRET → equity L1 tick tape + quotes; FINNHUB_API_KEY → equity tick tape. Without keys, equities run the honest keyless SYNTH tier.

Tests

cd server && uv run pytest -q          # gateway: grid, protocol, sessions, feeds, recording
cd client && npm test && npm run e2e   # renderer units + Playwright (heatmap, perf gate, parity)

The Playwright suite includes the §10 performance gate (history-independent frame cost) and the two-market parity matrix.

License

Apache-2.0 — see LICENSE.