# opendeviationbar-py: Directory Structure & Repository Layout

**Parent**: [`/CLAUDE.md`](/CLAUDE.md) | **Architecture**: [`ARCHITECTURE.md`](./ARCHITECTURE.md)

Comprehensive guide to the repository layout, 10-crate workspace organization, naming conventions, and key file locations.

---

## Table of Contents

1. [Top-Level Directory Structure](#top-level-directory-structure)
2. [Rust Workspace Structure](#rust-workspace-structure)
3. [Python Package Structure](#python-package-structure)
4. [Build & Configuration Files](#build--configuration-files)
5. [Documentation & Testing](#documentation--testing)
6. [Naming Conventions](#naming-conventions)
7. [Key File Locations Reference](#key-file-locations-reference)

---

## Top-Level Directory Structure

```
opendeviationbar-py/
├── .cargo/              Configuration for Rust build (cross-compilation)
├── .claude/             Claude Code agent memory & skills (symlink structure)
│   ├── CLAUDE.md        Project-level instructions (hub-and-spoke network)
│   ├── skills/          Executable skills for common tasks
│   │   ├── odb-ship/               Release + publish + deploy pipeline
│   │   ├── symbol-onboarding/      Add new symbol (9 call sites)
│   │   ├── sidecar-restart-zero-overlap-zero-gap-recovery-playbook/
│   │   ├── gitnexus/               Code intelligence & impact analysis
│   │   └── ...
│   └── projects/        User memory per project (auto-persisted)
│
├── .git/                Version control
├── .github/             GitHub Actions workflows
├── .gitnexus/           GitNexus index (code intelligence)
├── .mise/               Mise version manager config
├── .planning/           Analysis & planning outputs
│   └── codebase/        This directory
│       ├── ARCHITECTURE.md
│       └── STRUCTURE.md
│
├── benches/             Criterion benchmarks
│   ├── bar_generation.rs
│   ├── microstructure_features.rs
│   ├── streaming_throughput.rs
│   └── ...
│
├── crates/              10-crate Rust workspace (see below)
│   ├── opendeviationbar-core/
│   ├── opendeviationbar-config/
│   ├── opendeviationbar-hurst/
│   ├── opendeviationbar-providers/
│   ├── opendeviationbar-io/
│   ├── opendeviationbar-streaming/
│   ├── opendeviationbar-batch/
│   ├── opendeviationbar-client/
│   ├── opendeviationbar-cli/
│   └── opendeviationbar/
│
├── data/                ClickHouse symlinks (local debugging)
│   ├── opendeviationbar_cache/
│   │   ├── open_deviation_bars → ../../store/3f4/...
│   │   └── population_checkpoints → ../../store/3b8/...
│   └── system/
│
├── deploy/              Deployment & operations
│   ├── opendeviationbar.local.env  Secrets (ignored by git)
│   ├── systemd/         5 systemd services + 1 timer
│   │   ├── opendeviationbar-sidecar.service
│   │   ├── opendeviationbar-kintsugi.service
│   │   ├── opendeviationbar-heartbeat.service
│   │   ├── opendeviationbar-heartbeat.timer (5-min interval)
│   │   └── CLAUDE.md    Service configuration SSoT
│   └── monit/           Monit watchdog rules (10 monitors)
│
├── dist/                Python wheel distributions (built by maturin)
│
├── docs/                All project documentation
│   ├── OPEN-DEVIATION-BAR.md  Full algorithm + oracle proof (866K bars)
│   ├── ARCHITECTURE.md         System design (reference)
│   ├── CONTEXT.md              Project motivation
│   ├── api/                    API reference
│   │   ├── INDEX.md            API table of contents
│   │   ├── primary-api.md      get_open_deviation_bars, etc.
│   │   ├── cache-api.md        populate_cache_resumable
│   │   ├── processing-api.md   process_trades_*, process_trades_chunked
│   │   └── ...
│   ├── adr/                    Architecture Decision Records
│   ├── development/            Dev workflow documentation
│   │   ├── RELEASE.md          Release workflow (zig cross-compile, 4 phases)
│   │   ├── PERFORMANCE.md      Benchmarking guide
│   │   ├── ISSUE-107-SIDECAR-RELIABILITY.md
│   │   └── ...
│   ├── plans/                  Feature planning & RFCs
│   ├── research/               ML, regime analysis, TDA
│   └── verification/           Bit-exact oracle validation reports
│
├── examples/            Usage examples
│   ├── backtesting_py_integration.py
│   ├── streaming_sidecar.py
│   ├── polars_example.py
│   └── ...
│
├── logs/                Log output directory (systemd journals, local runs)
│
├── node_modules/        npm dependencies (semantic-release, gitnexus CLI)
│
├── python/              Python package (built by maturin)
│   └── opendeviationbar/   Main Python module (see below)
│
├── scripts/             Operational scripts (pueue jobs, validation)
│   ├── kintsugi.py              Self-healing gap reconciliation
│   ├── health_heartbeat.py      Monitoring daemon
│   ├── stream_manager_monitor.py Streaming liveness
│   ├── systemd/                 systemd service files (CLAUDE.md SSoT)
│   ├── data_validation/         Data integrity checks
│   └── CLAUDE.md                Operational SSoT
│
├── src/                 PyO3 bindings (Rust → Python)
│   ├── lib.rs                   Module entry point (200 lines)
│   ├── helpers.rs               f64 ↔ FixedPoint conversion
│   ├── core_bindings.rs         PyOpenDeviationBarProcessor
│   ├── arrow_bindings.rs        Arrow I/O (optional)
│   ├── binance_bindings.rs      Binance data fetching
│   ├── exness_bindings.rs       Exness data (optional)
│   ├── streaming_bindings.rs    PyLiveBarEngine
│   ├── stream_manager_bindings.rs PyStreamManager (Issue #161)
│   ├── odb_engine_bindings.rs   PyOdbEngine (Issue #178)
│   ├── gap_bindings.rs          PyGapEventWatcher (Issue #257)
│   └── thread_pool_init.rs      Rayon initialization
│
├── supply-chain/        Supply chain security
│   ├── Cargo.lock       Locked dependency tree
│   └── supply-chain/    SigStore signatures
│
├── target/              Rust build artifacts (ignored by git)
│   ├── release/         Optimized binaries
│   └── wheel/           maturin wheel staging
│
├── tests/               Integration tests (pytest)
│   ├── test_e2e_optimized.py                End-to-end tests
│   ├── test_get_open_deviation_bars.py      Date-bounded API
│   ├── test_get_n_open_deviation_bars.py    Count-bounded API
│   ├── test_streaming.py                    Sidecar tests
│   ├── test_kintsugi.py                     Gap reconciliation
│   ├── test_microstructure_features.py      Feature validation
│   └── ...
│
├── Cargo.toml           Workspace root (version + features SSoT)
├── Cargo.lock           Dependency lock (reproducible builds)
├── pyproject.toml       Maturin config, pytest, ruff, semantic-release
├── CLAUDE.md            Project memory hub (hub-and-spoke network)
├── README.md            User-facing project overview
└── package.json         npm config (semantic-release, node scripts)
```

---

## Rust Workspace Structure

**Location**: `crates/`

10 specialized crates with clear separation of concerns.

### Crate Overview

| Crate                         | Location                             | Lines | Published | Purpose                           |
| ----------------------------- | ------------------------------------ | ----- | --------- | --------------------------------- |
| opendeviationbar-core         | `crates/opendeviationbar-core/`      | ~5K   | ✓         | Core algorithm, microstructure    |
| opendeviationbar-config       | `crates/opendeviationbar-config/`    | ~200  | ✗         | Configuration (pydantic-settings) |
| opendeviationbar-hurst        | `crates/opendeviationbar-hurst/`     | ~1K   | ✓         | Hurst exponent (independent)      |
| opendeviationbar-providers    | `crates/opendeviationbar-providers/` | ~3K   | ✓         | Data sources (Binance, Exness)    |
| opendeviationbar-io           | `crates/opendeviationbar-io/`        | ~500  | ✗         | I/O operations (Polars, Arrow)    |
| opendeviationbar-streaming    | `crates/opendeviationbar-streaming/` | ~3K   | ✓         | Real-time processing (LiveEngine) |
| opendeviationbar-batch        | `crates/opendeviationbar-batch/`     | ~500  | ✗         | Batch analytics (Rayon)           |
| opendeviationbar-client       | `crates/opendeviationbar-client/`    | ~800  | ✓         | SSE consumer (independent)        |
| opendeviationbar-cli          | `crates/opendeviationbar-cli/`       | ~3K   | ✗         | CLI tools (disabled for PyPI)     |
| opendeviationbar (meta-crate) | `crates/opendeviationbar/`           | ~500  | ✓         | v4.0 backward compat re-exports   |

### Core Crate Structure

Each crate follows this structure:

```
crates/{crate-name}/
├── Cargo.toml              Crate manifest
├── src/
│   ├── lib.rs              Public API
│   ├── {module}.rs         Implementation files
│   └── ...
├── benches/                Criterion benchmarks
├── tests/                  Integration tests
└── data/                   Test fixtures (CSV, JSON)
```

### Key Implementation Files (opendeviationbar-core)

```
crates/opendeviationbar-core/src/
├── lib.rs                   Public API exports
├── processor.rs             (1184 lines) Core algorithm + microstructure
├── types.rs                 AggTrade, OpenDeviationBar, FixedPoint
├── checkpoint.rs            Checkpoint serialization, trade-ID continuity
├── intrabar.rs              10 intra-bar features (duration, OFI, etc.)
├── interbar.rs              16 inter-bar lookback features
├── fixed_point.rs           8-decimal fixed-point arithmetic
├── errors.rs                ProcessingError types
├── export_processor.rs      ExportOpenDeviationBarProcessor (minimal features)
├── hurst_estimator.rs       DFA-based Hurst computation
├── intrabar/                Submodules for intra-bar feature computation
│   ├── complexity.rs        Complexity metrics
│   ├── hurst.rs             Hurst per-bar computation
│   └── ...
└── tests/
    ├── processor_tests.rs    (2000+ tests)
    ├── microstructure_tests.rs
    └── ...
```

### Key Implementation Files (opendeviationbar-streaming)

```
crates/opendeviationbar-streaming/src/
├── lib.rs                   Public API exports
├── live_engine.rs           (2500 lines) LiveBarEngine, CompletedBar, FormingBar
├── stream_manager.rs        (800 lines) StreamManager, TradeIdGapDetector
├── gap/                     Submodule: Gap detection & fill
│   ├── detector.rs          TradeIdGapDetector
│   ├── fill.rs              Puck inline gap fill
│   └── events.rs            GapEvent, GapFillCommand
├── engine/                  Submodule: Unified engine (Issue #178)
│   ├── mod.rs               BarSource, BarSink traits
│   ├── live_source.rs       LiveBarSource (WS stream)
│   ├── channel_sink.rs      ChannelSink (completed bars)
│   └── clock.rs             EngineClock, LiveClock, HistoricalClock
├── processor.rs             StreamingProcessor wrapper
├── replay_buffer.rs         Dead-letter replay buffer
├── ring_buffer.rs           ConcurrentRingBuffer (bounded memory)
├── stats.rs                 StreamingStatsEngine
├── indicators.rs            Technical indicators (RSI, MACD, CCI)
└── tests/
    ├── live_engine_tests.rs
    └── gap_detection_tests.rs
```

### Dependency Graph (Visual)

```
[Top level]
    opendeviationbar (meta-crate)

[Layer 3]
    opendeviationbar-cli
    opendeviationbar-batch
    opendeviationbar-streaming

[Layer 2]
    opendeviationbar-io
    opendeviationbar-providers

[Layer 1]
    opendeviationbar-core
    opendeviationbar-config

[Independent]
    opendeviationbar-client (SSE consumer)
    opendeviationbar-hurst (Hurst exponent)
```

---

## Python Package Structure

**Location**: `python/opendeviationbar/`

### Directory Layout

```
python/opendeviationbar/
├── __init__.py              (300+ lines) Public API re-exports
├── __init__.pyi             (200 lines) Type stubs (re-export index only, per PEP 561)
├── _core.abi3.so            PyO3 extension (built by maturin)
│
├── sidecar.py               (3000+ lines) Streaming orchestrator (Issue #91)
├── sidecar.pyi              Type stubs
├── sidecar_api.py           (800 lines) Consumer API (ariadne, gap-fill, catchup)
│
├── checkpoint.py            (2000+ lines) Checkpoint persistence & validation
├── backfill.py              (1500+ lines) Historical backfill & population
├── kintsugi.py              (2000+ lines) Self-healing gap reconciliation (Issue #115)
│
├── clickhouse/              Tier-2 cache (ClickHouse, bigblack)
│   ├── __init__.py
│   ├── cache.py             (800+ lines) Read/write operations
│   ├── schema.sql           Table definition + migrations
│   ├── write_lock.py        Redis lock for concurrent-writer safety
│   ├── dedup.py             Dedup hardening (v12.4+)
│   └── CLAUDE.md            ClickHouse infrastructure (SSoT)
│
├── storage/                 Tier-1 cache (local Parquet)
│   ├── __init__.py
│   ├── parquet.py           (600+ lines) TickStorage class
│   ├── CLAUDE.md            Tier-1 architecture (SSoT)
│   └── ...
│
├── orchestration/           Request pipeline
│   ├── __init__.py
│   ├── open_deviation_bars.py  Main entry point logic
│   ├── count_bounded.py        Count-bounded API
│   ├── circuit_breaker.py      Failure handling
│   ├── stream.py               Streaming integration
│   └── CLAUDE.md               Pipeline architecture (SSoT)
│
├── validation/              Data integrity framework
│   ├── __init__.py
│   ├── tier1.py             (<30 sec) Fast smoke tests
│   ├── tier2.py             (~10 min) Statistical validation
│   ├── day_mode/            Day-mode Ouroboros enforcement
│   │   ├── __init__.py
│   │   ├── gate.py          Pre-write cross-midnight detection
│   │   ├── oracle.py        Heartbeat monitoring
│   │   └── CLAUDE.md        Day-mode SSoT
│   └── CLAUDE.md            Validation framework (SSoT)
│
├── plugins/                 Feature provider system (Issue #98)
│   ├── __init__.py
│   ├── base.py              FeatureProvider protocol
│   ├── manager.py           Entry-point discovery & loading
│   └── CLAUDE.md            Plugin architecture (SSoT)
│
├── symbol_registry.py       (400 lines) Mandatory registration gate (Issue #79)
├── data/                    Package data (importlib.resources)
│   ├── __init__.py
│   └── symbols.toml         Unified Symbol Registry (SSoT)
│
├── config/                  Configuration (pydantic-settings)
│   ├── __init__.py
│   ├── base.py              BaseSettings
│   ├── sidecar.py           SidecarConfig
│   ├── backfill.py          BackfillConfig
│   ├── resilience.py        ResilienceConfig
│   └── CLAUDE.md            Configuration (SSoT)
│
├── processors/              Data processors
│   ├── __init__.py
│   ├── api.py               Entry-point wrappers
│   ├── bulk_operations.py   Batch processing with validation
│   ├── polars_processor.py  Polars-native path
│   └── ...
│
├── notify/                  Notifications (Telegram, Pushover)
│   ├── __init__.py
│   ├── telegram.py
│   ├── pushover.py
│   └── ...
│
├── exceptions.py            Custom exception types
├── constants.py             Public constants (TIER1_SYMBOLS, etc.)
├── conversion.py            Dict ↔ DataFrame conversion
├── ouroboros.py             Day-mode utilities
├── exness.py                Exness data utilities
├── health_checks.py         Health monitoring
├── logging.py               Logging configuration
├── progress.py              Progress bar utilities
├── phi_accrual.py           Phi accrual failure detection
├── resource_guard.py        Memory protection (dual-layer)
├── binance_vision.py        Vision archive utilities
│
├── population.py            Cache population entry points
├── hooks.py                 Git pre-commit hooks
├── cli.py                   Command-line interface
│
├── CLAUDE.md                Python layer (SSoT)
├── compat/                  Backward compatibility
│   ├── __init__.py
│   ├── alpha_forge_compat.py  alpha-forge API compatibility
│   └── ...
│
└── *.pyi                    Type stub files (per-module)
    ├── checkpoint.pyi
    ├── backfill.pyi
    ├── exceptions.pyi
    └── ...
```

### Public API (Re-exports in **init**.py)

**Categories**:

1. **Core Classes**: `OpenDeviationBarProcessor`, `PositionVerification`, `StreamingConfig`
2. **Data Types**: `AggTrade`, `OpenDeviationBar`, `GapInfo`, `TierSummary`
3. **Entry Points**:
   - `get_open_deviation_bars()` (date-bounded)
   - `get_n_open_deviation_bars()` (count-bounded)
   - `process_trades_to_dataframe()` (existing DataFrame)
   - `process_trades_polars()` (Polars native, 2-3x faster)
   - `populate_cache_resumable()` (pre-populate cache)
4. **Streaming**: `run_sidecar()`, `SidecarConfig`
5. **Constants**: `TIER1_SYMBOLS`, `THRESHOLD_PRESETS`, `VALIDATION_PRESETS`
6. **Exceptions**: `SymbolNotRegisteredError`, `ThresholdError`, `ContinuityError`

---

## Build & Configuration Files

### Cargo.toml (Workspace Root)

**Location**: `Cargo.toml`

**Key Sections**:

- `[workspace]` — Shared version (all crates inherit)
- `[workspace.dependencies]` — Dependency SSoT (all crates use workspace inheritance)
- `[lib]` — PyO3 extension (`crate-type = ["cdylib"]`)
- `[profile.release]` — LTO, codegen-units
- `[profile.wheel]` — wheel-specific settings (strip symbols)
- `[features]` — Feature composition
  - `arrow-export` (default)
  - `data-providers` (default)
  - `streaming` (default)
  - `all` (enables everything)

**Version Management**: `semantic-release` bumps `workspace.package.version` on each release, automatically cascading to all crates and PyO3 bindings.

### pyproject.toml (Maturin + Tool Config)

**Location**: `pyproject.toml`

**Key Sections**:

- `[project]` — Package metadata (PyPI)
- `[tool.maturin]` — Maturin settings
  - `module-name = "opendeviationbar._core"`
  - `features = ["data-providers", "arrow-export", "streaming"]`
- `[tool.pytest.ini_options]` — pytest config
- `[tool.ruff]` — Ruff linter config
- `[tool.semantic-release]` — Release configuration (4 phases)
  - Python wheels + Rust crates version sync
  - Changelog generation
  - GitHub release creation
  - Publish to PyPI + crates.io

### .mise.toml (Task Runner + Tool Installation)

**Location**: `.mise.toml`

**Key Tasks**:

- `build` — `maturin develop`
- `test` — `cargo nextest run`
- `test-py` — `pytest`
- `check-full` — fmt + lint + test + deny
- `release:*` — Release phases (zig cross-compile for Linux)
- `kintsugi:*` — Gap reconciliation (daemon, catchup, pass)
- `bench:*` — Performance benchmarks

**Tool Versions**: Centralized in `.mise.toml` (mise pins versions for reproducibility)

### .releaserc.yml (semantic-release Config)

**Location**: `.releaserc.yml`

**Phases**:

1. **Analyze** — Scan commits, determine version bump
2. **Generate** — Update CHANGELOG, version files
3. **Prepare** — Build wheels (maturin build --release)
4. **Publish** — Upload to PyPI + crates.io

---

## Documentation & Testing

### Documentation Structure

```
docs/
├── OPEN-DEVIATION-BAR.md         Full algorithm (866K bar examples)
├── ARCHITECTURE.md               System design (reference)
├── CONTEXT.md                    Why this project
├── api/
│   ├── INDEX.md                  API table of contents
│   ├── primary-api.md            Main entry points
│   ├── cache-api.md              Cache operations
│   └── processing-api.md         Data processing
├── adr/                          Architecture decisions
│   ├── 2026-01-31-realtime-streaming-api.md
│   └── ...
├── development/                  Developer guides
│   ├── RELEASE.md                Release workflow
│   ├── PERFORMANCE.md            Benchmarking
│   └── ISSUE-*.md                Issue-specific docs
├── plans/                        Feature planning
│   ├── issue-59-inter-bar-features.md
│   └── ...
├── research/                     ML & analysis
├── verification/                 Bit-exact oracle proofs
└── ...
```

### Testing Structure

```
tests/
├── test_e2e_optimized.py                     (500+ lines) End-to-end
├── test_get_open_deviation_bars.py           Date-bounded API
├── test_get_n_open_deviation_bars.py         Count-bounded API
├── test_streaming.py                        Sidecar tests
├── test_kintsugi.py                         Gap reconciliation
├── test_microstructure_features.py          Feature validation
├── test_market_microstructure.py            Microstructure compute
├── conftest.py                              pytest fixtures
└── ...

crates/*/tests/
├── *_tests.rs          Per-crate integration tests
└── ...
```

### Example Scripts

```
examples/
├── backtesting_py_integration.py    backtesting.py usage
├── streaming_sidecar.py             Sidecar setup
├── polars_example.py                Polars API
├── get_open_deviation_bars.py       Basic usage
└── ...
```

---

## Naming Conventions

### File Naming

| Pattern         | Meaning                                  | Example                 |
| --------------- | ---------------------------------------- | ----------------------- |
| `*.rs`          | Rust source files                        | `processor.rs`          |
| `*_bindings.rs` | PyO3 binding modules (in `src/`)         | `core_bindings.rs`      |
| `*_tests.rs`    | Rust test modules (in `crates/*/tests/`) | `processor_tests.rs`    |
| `test_*.py`     | Python test modules                      | `test_e2e_optimized.py` |
| `*.pyi`         | Python type stub files                   | `__init__.pyi`          |
| `*_tests/`      | Test data directories                    | `data/tests/`           |
| `CLAUDE.md`     | SSoT documentation for directory         | `crates/CLAUDE.md`      |

### Type Naming

| Pattern                       | Rust Meaning                     | Python Meaning                 |
| ----------------------------- | -------------------------------- | ------------------------------ |
| `OpenDeviationBar`            | Output bar struct (58 columns)   | Dataclass or dict              |
| `AggTrade`                    | Input trade data                 | dict with a, p, q, T, m        |
| `PyOpenDeviationBarProcessor` | —                                | PyO3 wrapper class             |
| `OpenDeviationBarProcessor`   | Stateful Rust processor          | —                              |
| `StreamingConfig`             | Streaming configuration          | Both Rust + Python (re-export) |
| `FixedPoint`                  | 8-decimal fixed-point arithmetic | Converted to f64 for Python    |

### Python Module Naming

| Pattern                     | Purpose                                           |
| --------------------------- | ------------------------------------------------- |
| `get_*`                     | Getter function (e.g., `get_open_deviation_bars`) |
| `process_*`                 | Processing function                               |
| `_*` (leading underscore)   | Private/internal (not re-exported)                |
| `run_*`                     | Long-running service (e.g., `run_sidecar`)        |
| `*_gate`                    | Validation gate (e.g., pre-write gate)            |
| `validate_*`                | Validation function                               |
| `*_watchdog` or `*_monitor` | Monitoring service                                |

### Python Function/Variable Naming

| Pattern                         | Meaning                              | Example                   |
| ------------------------------- | ------------------------------------ | ------------------------- |
| `symbol`                        | Trading symbol (always string)       | `"BTCUSDT"`, `"ETHUSDT"`  |
| `threshold`                     | Threshold in decimal basis points    | `250`, `500`, `1000`      |
| `threshold_decimal_bps`         | Full parameter name (explicit)       | Function parameter        |
| `bar_dict` / `bars_df`          | dict / DataFrame of bars             | Local variable            |
| `trades_df` / `trades_iterator` | Input trades (DataFrame or iterator) | Function parameter        |
| `checkpoint` / `checkpoints`    | Processor checkpoint state           | Nested dict structure     |
| `cache` or `ch_cache`           | ClickHouse cache instance            | `OpenDeviationBarCache()` |

### GitHub Issue Naming

| Pattern              | Meaning                            | Example             |
| -------------------- | ---------------------------------- | ------------------- |
| `Issue #NNN`         | GitHub issue number (reference)    | Issue #91 (sidecar) |
| `Issue #NNN Phase N` | Multi-phase issue tracking         | Issue #238 Phase 2  |
| `Task #NNN`          | GitHub task number (part of issue) | Task #144           |
| `PR #NNN`            | Pull request number                | PR #1234            |

---

## Key File Locations Reference

### Critical Configuration & Secrets

| File                                | Purpose                           | Tracked?        |
| ----------------------------------- | --------------------------------- | --------------- |
| `deploy/opendeviationbar.local.env` | Deploy secrets (tokens, URLs)     | ✗ (git-ignored) |
| `.mise.local.toml`                  | Local tool config overrides       | ✗ (git-ignored) |
| `Cargo.lock`                        | Dependency lock (reproducibility) | ✓ (tracked)     |
| `supply-chain/Cargo.lock`           | Audited lock file                 | ✓ (tracked)     |

### Entry Points

| Type                | File Path                                              | Function/Class Name         |
| ------------------- | ------------------------------------------------------ | --------------------------- |
| **Main Python API** | `python/opendeviationbar/__init__.py`                  | `get_open_deviation_bars()` |
| **Streaming**       | `python/opendeviationbar/sidecar.py`                   | `run_sidecar()`             |
| **Gap Repair**      | `python/opendeviationbar/kintsugi.py`                  | `kintsugi_pass()`           |
| **Rust Core**       | `crates/opendeviationbar-core/src/lib.rs`              | `OpenDeviationBarProcessor` |
| **Rust Streaming**  | `crates/opendeviationbar-streaming/src/live_engine.rs` | `LiveBarEngine`             |
| **PyO3 Module**     | `src/lib.rs`                                           | `#[pymodule] fn _core()`    |

### Schema & Data Structure Definitions

| File                                            | Defines                           |
| ----------------------------------------------- | --------------------------------- |
| `crates/opendeviationbar-core/src/types.rs`     | `AggTrade`, `OpenDeviationBar`    |
| `python/opendeviationbar/clickhouse/schema.sql` | ClickHouse table (58 columns)     |
| `python/opendeviationbar/data/symbols.toml`     | Symbol registry (unified SSoT)    |
| `python/opendeviationbar/constants.py`          | Column names, presets, tier1 list |

### Cache & Checkpoint Locations

| Location                                                      | Purpose                   | Scope      |
| ------------------------------------------------------------- | ------------------------- | ---------- | --------- |
| `~/.cache/opendeviationbar/ticks/{SYMBOL}/YYYY-MM-DD.parquet` | Tier-1 ticks cache        | Per day    |
| `~/.cache/opendeviationbar/checkpoints/`                      | Streaming checkpoints     | Per symbol | threshold |
| `bigblack:opendeviationbar_cache.open_deviation_bars`         | ClickHouse bars           | Remote     |
| `/tmp/opendeviationbar-dead-letter/`                          | Dead-letter Parquet files | Transient  |

### Systemd Services & Timers

| Service                            | File Location                                       | Schedule           |
| ---------------------------------- | --------------------------------------------------- | ------------------ |
| `opendeviationbar-sidecar`         | `deploy/systemd/opendeviationbar-sidecar.service`   | Always running     |
| `opendeviationbar-kintsugi`        | `deploy/systemd/opendeviationbar-kintsugi.service`  | Always running     |
| `opendeviationbar-heartbeat`       | `deploy/systemd/opendeviationbar-heartbeat.service` | Triggered by timer |
| `opendeviationbar-heartbeat.timer` | `deploy/systemd/opendeviationbar-heartbeat.timer`   | Every 5 minutes    |

### Monitoring & Logging

| Type                | File                                       | Purpose                    |
| ------------------- | ------------------------------------------ | -------------------------- |
| **Monit Config**    | `deploy/monit/`                            | 10 watchdog monitors       |
| **systemd Journal** | `journalctl -u opendeviationbar-*`         | Service logs               |
| **Sidecar Journal** | `journalctl -u opendeviationbar-heartbeat` | Health checks              |
| **Logs Directory**  | `logs/`                                    | Local log files (optional) |

---

## Summary

| Aspect               | Location                                               | Notes                            |
| -------------------- | ------------------------------------------------------ | -------------------------------- |
| **Core Algorithm**   | `crates/opendeviationbar-core/src/processor.rs`        | 1184 lines, non-lookahead breach |
| **Streaming Engine** | `crates/opendeviationbar-streaming/src/live_engine.rs` | 2500 lines, multiplexes WS       |
| **Python API**       | `python/opendeviationbar/__init__.py`                  | 300+ lines, 20+ entry points     |
| **PyO3 Bindings**    | `src/lib.rs` + domain modules                          | 200-line orchestrator            |
| **Sidecar**          | `python/opendeviationbar/sidecar.py`                   | 3000+ lines, Puck/Niffler/Charon |
| **ClickHouse Cache** | `python/opendeviationbar/clickhouse/`                  | Schema + read/write operations   |
| **Configuration**    | `Cargo.toml`, `pyproject.toml`, `.mise.toml`           | Workspace-level SSoT             |
| **Release Workflow** | `.releaserc.yml`, `docs/development/RELEASE.md`        | 4-phase semantic-release         |
| **Deployment**       | `deploy/systemd/`, `deploy/monit/`                     | 5 services + 1 timer             |
| **Testing**          | `tests/`, `crates/*/tests/`                            | 914+ tests (all passing)         |
| **Documentation**    | `docs/`, `CLAUDE.md` (hub-and-spoke)                   | Architecture + API + algorithms  |

---

## Related Documentation

- **Architecture**: [`ARCHITECTURE.md`](./ARCHITECTURE.md)
- **Project Hub**: [`/CLAUDE.md`](/CLAUDE.md)
- **Python Layer**: [`/python/opendeviationbar/CLAUDE.md`](/python/opendeviationbar/CLAUDE.md)
- **Rust Crates**: [`/crates/CLAUDE.md`](/crates/CLAUDE.md)
- **Release Workflow**: [`/docs/development/RELEASE.md`](/docs/development/RELEASE.md)
- **Deployment**: [`/deploy/CLAUDE.md`](/deploy/CLAUDE.md)
