Real-Time Options Flow & Off-Exchange Analysis

This repository contains a real-time market-flow analysis platform focused on options flow, off-exchange equity trades, and inferred institutional behavior, built for low-latency, explainable analysis rather than black-box signals.

The system ingests real-time options trades/quotes and equity prints, clusters raw activity into higher-level flow events (sweeps, spreads, rolls, ladders), applies rule-first classifiers, and visualizes the results through a high-performance, TradingView-smooth interface with full replay and backtesting support.

CURRENT STATE (Plan Progress)

Plan progress (rough): [####------]

Done now (in repo):

Bun monorepo + infra docker compose (ClickHouse, Redis, NATS JetStream)
Shared event schemas + logging + config helpers
Synthetic options/equity prints published to NATS and persisted to ClickHouse
Deterministic option FlowPacket clustering (time window) + persistence
API: REST for prints/flow packets, WS for live options/equities/flow, replay endpoints
UI: live tapes for options/equities/flow + replay toggle + pause controls

In progress / blocked:

Real data adapters (requires licensed data source)
Rolling stats and advanced clustering

Not started:

Classifiers + alert scoring
Dark pool inference
Candle service and chart overlays
Auth / secure deployment

Core Principles

Explainability first — every alert and signal is backed by observable data and explicit logic.
Event-sourced architecture — all raw and derived events are persisted and replayable.
Market microstructure correctness — conservative handling of aggressor inference, OI, and off-exchange prints.
Low-latency, tangible UX — smooth real-time interaction that feels like an instrument panel, not a spreadsheet.

Current Capabilities

Synthetic options/equity prints with deterministic sequencing
Ingest adapter seam (env-selected, default synthetic) for options and equities
Raw event persistence in ClickHouse + streaming via NATS JetStream
Deterministic option FlowPacket clustering (time-window)
API gateway with REST, WS, and replay endpoints
UI tapes for options/equities/flow packets with live/replay toggle and pause controls

Planned Capabilities (from PLAN.md)

Real-time licensed market data ingestors (options + equities)
Rule-first classifiers and alert scoring
Dark pool inference and evidence linking
Candle aggregation + chart overlays
Replay/backtesting metrics and calibration

Tech Stack

Runtime & tooling: Bun
Language: TypeScript
Frontend: Next.js + React
Realtime: WebSockets
Event streaming: NATS JetStream or Redpanda
Storage: ClickHouse, Redis
Charting: TradingView Lightweight Charts + custom canvas/WebGL overlays

Repository Structure

apps/ web/ services/ ingest-options/ ingest-equities/ compute/ api/ packages/ types/ ui/ chart/

Build and Run

Install dependencies:

bun install

Start infra:

docker compose up -d

Start everything (infra + services + web):

bun run dev

Run just the web app (auto-picks a free port in 3001-3005):

bun --cwd apps/web run dev

Run just the API:

bun --cwd services/api run dev

Run tests:

bun test

Status

Active build for personal, non-delayed analytical use. Multi-user access and redistribution are intentionally out of scope.

Non-Goals

No black-box AI predictions
No profit guarantees
No real-time data redistribution
No guessing at intent without evidence

License / Usage

For research and personal analytical use.
Market data usage is subject to the terms of the data providers.

3.6 KiB Raw Blame History