orderflow_backtest/docs/CONTEXT.md

# Project Context

## Current State

The project implements a modular, efficient orderflow processing pipeline:
- Stream orderflow from SQLite (`DBInterpreter.stream`).
- Process trades and orderbook updates through modular `OHLCProcessor` architecture.
- Exchange data with the UI via atomic JSON files (`viz_io`).
- Render OHLC+Volume, Depth, and Metrics charts with a Dash app (`app.py`).

The system features a clean composition-based architecture with specialized modules for different concerns, providing OBI/CVD metrics alongside OHLC data.

## Recent Work

- **Modular Refactoring**: Extracted `ohlc_processor.py` into focused modules:
  - `level_parser.py`: Orderbook level parsing utilities (85 lines)
  - `orderbook_manager.py`: In-memory orderbook state management (90 lines) 
  - `metrics_calculator.py`: OBI and CVD metrics calculation (112 lines)
- **Architecture Compliance**: Reduced main processor from 440 to 248 lines (250-line target achieved)
- Maintained full backward compatibility and functionality
- Implemented read-only, batched SQLite streaming with PRAGMA tuning.
- Added robust JSON IPC with atomic writes and tolerant UI reads.
- Built a responsive Dash visualization polling at 500ms.
- Unified CLI using Typer, with UV for process management.

## Conventions

- Python 3.12+, UV for dependency and command execution.
- **Modular Architecture**: Composition over inheritance, single-responsibility modules
- **File Size Limits**: ≤250 lines per file, ≤50 lines per function (enforced)
- Type hints throughout; concise, focused functions and classes.
- Error handling with meaningful logs; avoid bare exceptions.
- Prefer explicit JSON structures for IPC; keep payloads small and bounded.

## Priorities

- Improve configurability: database path discovery, CLI flags for paths and UI options.
- Add tests for `DBInterpreter.stream` and `OHLCProcessor` (run with `uv run pytest`).
- Performance tuning for large DBs while keeping UI responsive.
- Documentation kept in sync with code; architecture reflects current design.

## Roadmap (Future Work)

- Enhance OBI metrics with additional derived calculations (e.g., normalized OBI).
- Optional repository layer abstraction and a storage orchestrator.
- Extend visualization with additional subplots and interactivity.
- Strategy module for analytics and alerting on derived metrics.

## Tooling

- Package management and commands: UV (e.g., `uv sync`, `uv run ...`).
- Visualization server: Dash on `http://localhost:8050`.
- Linting/testing: Pytest (e.g., `uv run pytest`).