Document current state and flow UI

README.md

@@ -4,6 +4,28 @@ This repository contains a real-time market-flow analysis platform focused on **
 
 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.
@@ -11,27 +33,21 @@ The system ingests real-time options trades/quotes and equity prints, clusters r
 - **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.
 
-## What This Does
+## Current Capabilities
 
-- Ingests real-time options market data (OPRA-derived via licensed sources)
-- Ingests real-time equity trades and quotes, including off-exchange prints
-- Clusters raw prints into parent flow events:
-  - sweeps
-  - ladders
-  - spreads
-  - rolls
-- Applies rule-first classifiers:
-  - large bullish/bearish sweeps
-  - put selling / overwrites
-  - volatility trades (straddles/strangles)
-  - 0DTE gamma activity
-  - far-dated conviction
-- Infers dark-pool-like behavior (absorption, accumulation, distribution)
-- Visualizes everything in real time with:
-  - live flow terminals
-  - off-exchange print overlays
-  - inferred event markers
-  - replayable charts
+- Synthetic options/equity prints with deterministic sequencing
+- 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
 
@@ -57,6 +73,26 @@ 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.