166 lines
5.1 KiB
Markdown
166 lines
5.1 KiB
Markdown
# 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
|
|
```bash
|
|
# Start the Dash server
|
|
uv run python app.py
|
|
|
|
# Access the web interface
|
|
# Open http://localhost:8050 in your browser
|
|
```
|
|
|
|
### Programmatic Usage
|
|
```python
|
|
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
|
|
```python
|
|
# 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:
|
|
```bash
|
|
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
|