# Architecture Overview

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

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

## Workspace Structure

```
opendeviationbar-py/
├── Cargo.toml                 # Workspace root + PyO3 cdylib
├── src/lib.rs                 # PyO3 bindings (Python entry point)
├── crates/                    # 10 Rust crates (5 on crates.io, 5 internal)
│   ├── opendeviationbar-core/         # Layer 0: Core algorithm
│   ├── opendeviationbar-config/       # Layer 0: Configuration
│   ├── opendeviationbar-hurst/        # Layer 0: Hurst exponent (independent)
│   ├── 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-client/       # Independent: SSE bar consumer
│   ├── 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

opendeviationbar-client (independent, SSE consumer via eventsource-client + reqwest)

opendeviationbar-hurst (independent library, MIT-licensed fork of GPL-3.0)
```

## 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]
version.workspace = true   # All crates share workspace version
edition.workspace = true   # 2024
# 5 crates publish to crates.io (no publish key needed);
# 5 internal crates set publish = false explicitly.
```

### 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. **Dual publishing**: 5 crates publish to crates.io (`opendeviationbar-core`, `opendeviationbar-providers`, `opendeviationbar-streaming`, `opendeviationbar-client`, `opendeviationbar-hurst`). Python wheels publish to PyPI. 5 internal-only crates have `publish = false`.

2. **Modular architecture**: 10 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
