# Architecture Overview

**Parent**: [/CLAUDE.md](/CLAUDE.md)

**opendeviationbar-py** is a unified Rust workspace with Python bindings. This document describes the 8-crate modular architecture.

## Workspace Structure

```
opendeviationbar-py/
├── Cargo.toml                 # Workspace root + PyO3 cdylib
├── src/lib.rs                 # PyO3 bindings (Python entry point)
├── crates/                    # 8 Rust crates (all publish = false)
│   ├── opendeviationbar-core/         # Layer 0: Core algorithm
│   ├── opendeviationbar-config/       # Layer 0: Configuration
│   ├── opendeviationbar-providers/    # Layer 1: Data sources
│   ├── opendeviationbar-io/           # Layer 1: I/O operations
│   ├── opendeviationbar-streaming/    # Layer 2: Real-time processing
│   ├── opendeviationbar-batch/        # Layer 2: Batch analytics
│   ├── opendeviationbar-cli/          # Layer 3: CLI tools (disabled)
│   └── opendeviationbar/              # Layer 3: Meta-crate
├── python/opendeviationbar/           # Python API layer
└── pyproject.toml             # Maturin configuration
```

## Dependency Graph

```
                    opendeviationbar (meta-crate, v4.0 compat)
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
   opendeviationbar-cli          opendeviationbar-batch      opendeviationbar-streaming
        │                     │                     │
        └──────────┬──────────┴──────────┬──────────┘
                   │                     │
             opendeviationbar-io          opendeviationbar-providers
                   │                     │
                   └──────────┬──────────┘
                              │
                        opendeviationbar-core
                              │
                        opendeviationbar-config
```

## Crate Details

### Layer 0: Foundation

| Crate | Purpose | Key Types |
|-------|---------|-----------|
| **opendeviationbar-config** | Configuration management | `Settings` |
| **opendeviationbar-core** | Core algorithm (minimal deps) | `AggTrade`, `OpenDeviationBar`, `FixedPoint`, `OpenDeviationBarProcessor` |

**opendeviationbar-core** features:
- 8-decimal fixed-point arithmetic (avoids floating-point errors)
- Non-lookahead breach detection (temporal integrity)
- `test-utils` feature for CSV loading
- `python` feature for PyO3 types
- `api` feature for utoipa OpenAPI

### Layer 1: Data Access

| Crate | Purpose | Key Types |
|-------|---------|-----------|
| **opendeviationbar-providers** | Data sources | `HistoricalDataLoader`, `ExnessFetcher` |
| **opendeviationbar-io** | I/O operations | Polars DataFrame integration |

**opendeviationbar-providers** features:
- `binance` - Binance spot/UM/CM futures (aggTrades)
- `exness` - 10 forex pairs (EURUSD, GBPUSD, etc.)
- `all-providers` - Enable all

**opendeviationbar-io** features:
- `parquet` - Polars Parquet I/O
- Export to CSV, Parquet, Arrow IPC

### Layer 2: Processing Engines

| Crate | Purpose | Key Types |
|-------|---------|-----------|
| **opendeviationbar-streaming** | Real-time processor | `StreamingProcessor`, `StreamingConfig` |
| **opendeviationbar-batch** | Batch analytics | `BatchAnalysisEngine`, `AnalysisReport` |

**opendeviationbar-streaming** features:
- Bounded memory (configurable limits)
- Circuit breaker pattern
- `stats` - Streaming statistics
- `indicators` - Technical indicators

**opendeviationbar-batch** features:
- Rayon parallel processing
- High-throughput batch analysis

### Layer 3: Applications

| Crate | Purpose | Status |
|-------|---------|--------|
| **opendeviationbar-cli** | 6 CLI tools | Disabled for PyPI |
| **opendeviationbar** | Meta-crate | v4.0 backward compatibility |

**CLI binaries** (source preserved, not built):
- `tier1-symbol-discovery`
- `opendeviationbar-analyze`
- `data-structure-validator`
- `spot-tier1-processor`
- `polars-benchmark`
- `temporal-integrity-validator`

## Python Integration

The Python layer sits on top of the Rust workspace:

```
Python API (python/opendeviationbar/)
├── __init__.py          # get_open_deviation_bars(), process_trades_*()
├── clickhouse/          # Tier 2 cache (ClickHouse)
└── storage/             # Tier 1 cache (Parquet)
        │
        ▼
PyO3 Bindings (src/lib.rs)
├── PyOpenDeviationBarProcessor  # Wraps opendeviationbar-core::OpenDeviationBarProcessor
├── PyAggTrade           # Wraps opendeviationbar-core::AggTrade
└── Data fetching        # Uses opendeviationbar-providers (optional feature)
        │
        ▼
Local Crates (crates/)
└── opendeviationbar-core, opendeviationbar-providers, etc.
```

## Build Configuration

### Workspace Inheritance

All crates inherit from workspace:
```toml
[package]
publish.workspace = true  # Inherits false - no crates.io
version.workspace = true  # Inherits 6.1.1
edition.workspace = true  # Inherits 2024
```

### Optimization Profiles

```toml
[profile.release]
lto = "thin"           # Cross-platform LTO
codegen-units = 1      # Maximum optimization
# panic = "abort"      # FORBIDDEN with PyO3!

[profile.wheel]
inherits = "release"
strip = "symbols"      # Minimize wheel size
```

### PyO3 Configuration

```toml
[lib]
crate-type = ["cdylib"]  # Python extension module

[dependencies]
pyo3 = { version = "0.22", features = ["extension-module", "abi3-py39"] }
```

The `abi3-py39` feature enables stable ABI, producing **one wheel per platform** instead of one per Python version.

## Development Workflow

```bash
# Install tools
mise install

# Build Python extension
mise run build           # maturin develop

# Run tests
mise run test            # Rust tests (excludes PyO3 crate)
mise run test-py         # Python tests

# Quality checks
mise run check-full      # fmt + lint + test + deny

# Benchmarks
mise run bench:run       # Full benchmarks
mise run bench:validate  # Verify 1M ticks < 100ms
```

## Design Decisions

1. **PyPI-only publishing**: All crates have `publish = false`. Only Python wheels are distributed.

2. **Modular architecture**: 8 specialized crates enable:
   - Independent testing
   - Optional features (e.g., streaming without batch)
   - Clear separation of concerns

3. **Local crates**: No external crates.io dependencies for opendeviationbar-* crates. All source is in this repo.

4. **CLI disabled**: CLI binaries are preserved as source but not built, focusing the project on Python API.

5. **Thin LTO**: Chosen over fat LTO for cross-platform compatibility (macOS + Linux builds).

## Related Documentation

- [/CLAUDE.md](/CLAUDE.md) - Project hub
- [/crates/CLAUDE.md](/crates/CLAUDE.md) - Detailed crate documentation
- [/python/opendeviationbar/CLAUDE.md](/python/opendeviationbar/CLAUDE.md) - Python layer details
- [/docs/api.md](/docs/api.md) - Python API reference
- [/docs/development/RELEASE.md](/docs/development/RELEASE.md) - Release workflow
