orderflow_backtest/docs/modules/app.md

Module: app

Purpose

The app module provides a real-time Dash web application for visualizing OHLC candlestick charts, volume data, Order Book Imbalance (OBI) metrics, and orderbook depth. It implements a polling-based architecture that reads JSON data files and renders interactive charts with a dark theme.

Public Interface

Functions

• build_empty_ohlc_fig() -> go.Figure: Create empty OHLC chart with proper styling
• build_empty_depth_fig() -> go.Figure: Create empty depth chart with proper styling
• build_ohlc_fig(data: List[list], metrics: List[list]) -> go.Figure: Build complete OHLC+Volume+OBI chart
• build_depth_fig(depth_data: dict) -> go.Figure: Build orderbook depth visualization

Global Variables

• _LAST_DATA: Cached OHLC data for error recovery
• _LAST_DEPTH: Cached depth data for error recovery
• _LAST_METRICS: Cached metrics data for error recovery

Dash Application

• app: Main Dash application instance with Bootstrap theme
• Layout with responsive grid (9:3 ratio for OHLC:Depth charts)
• 500ms polling interval for real-time updates

Usage Examples

Running the Application

# Start the Dash server
uv run python app.py

# Access the web interface
# Open http://localhost:8050 in your browser

Programmatic Usage

from app import build_ohlc_fig, build_depth_fig

# Build charts with sample data
ohlc_data = [[1640995200000, 50000, 50100, 49900, 50050, 125.5]]
metrics_data = [[1640995200000, 0.15, 0.22, 0.08, 0.18]]
depth_data = {
    "bids": [[49990, 1.5], [49985, 2.1]],
    "asks": [[50010, 1.2], [50015, 1.8]]
}

ohlc_fig = build_ohlc_fig(ohlc_data, metrics_data)
depth_fig = build_depth_fig(depth_data)

Dependencies

Internal

• viz_io: Data file paths and JSON reading
• viz_io.DATA_FILE: OHLC data source
• viz_io.DEPTH_FILE: Depth data source
• viz_io.METRICS_FILE: Metrics data source

External

• dash: Web application framework
• dash.html, dash.dcc: HTML and core components
• dash_bootstrap_components: Bootstrap styling
• plotly.graph_objs: Chart objects
• plotly.subplots: Multiple subplot support
• pandas: Data manipulation (minimal usage)
• json: JSON file parsing
• logging: Error and debug logging
• pathlib: File path handling

Chart Architecture

OHLC Chart (Left Panel, 9/12 width)

• Main subplot: Candlestick chart with OHLC data
• Volume subplot: Bar chart sharing x-axis with main chart
• OBI subplot: Order Book Imbalance candlestick chart in blue tones
• Shared x-axis: Synchronized zooming and panning across subplots

Depth Chart (Right Panel, 3/12 width)

• Cumulative depth: Stepped line chart showing bid/ask liquidity
• Color coding: Green for bids, red for asks
• Real-time updates: Reflects current orderbook state

Styling and Theme

Dark Theme Configuration

• Background: Black (#000000)
• Text: White (#ffffff)
• Grid: Dark gray with transparency
• Candlesticks: Green (up) / Red (down)
• Volume: Gray bars
• OBI: Blue tones for candlesticks
• Depth: Green (bids) / Red (asks)

Responsive Design

• Bootstrap grid system for layout
• Fluid container for full-width usage
• 100vh height for full viewport coverage
• Configurable chart display modes

Data Polling and Error Handling

Polling Strategy

• Interval: 500ms for near real-time updates
• Graceful degradation: Uses cached data on JSON read errors
• Atomic reads: Tolerates partial writes during file updates
• Logging: Warnings for data inconsistencies

Error Recovery

# Pseudocode for error handling pattern
try:
    with open(data_file) as f:
        new_data = json.load(f)
    _LAST_DATA = new_data  # Cache successful read
except (FileNotFoundError, json.JSONDecodeError):
    logging.warning("Using cached data due to read error")
    new_data = _LAST_DATA  # Use cached data

Performance Characteristics

• Client-side rendering: Plotly.js handles chart rendering
• Efficient updates: Only redraws when data changes
• Memory bounded: Limited by max bars in data files (1000)
• Network efficient: Local file polling (no external API calls)

Testing

Run application tests:

uv run pytest test_app.py -v

Test coverage includes:

• Chart building functions
• Data loading and caching
• Error handling scenarios
• Layout rendering
• Callback functionality

Configuration Options

Server Configuration

• Host: 0.0.0.0 (accessible from network)
• Port: 8050 (default Dash port)
• Debug mode: Disabled in production

Chart Configuration

• Update interval: 500ms (configurable via dcc.Interval)
• Display mode bar: Enabled for user interaction
• Logo display: Disabled for clean interface

Known Issues

• High CPU usage during rapid data updates
• Memory usage grows with chart history
• No authentication or access control
• Limited mobile responsiveness for complex charts

Development Notes

• Uses Flask development server (not suitable for production)
• Callback exceptions suppressed for partial data scenarios
• Bootstrap CSS loaded from CDN
• Chart configurations optimized for financial data visualization