# `ironcondor` design documentation
Start here. The documents below cover the project from product to
result-bundle wire format. Suggested reading order depends on what you
are doing.
**Honest status note.** Everything in this folder is a forward-looking
design document. The published `v0.0.1` crate is a name-reservation
placeholder; no implementation code exists yet. Where a document says
"the engine does X", read "the engine will do X" — present tense is
used for the design contract, not for shipped behavior.
## Reading paths
**I'm a stakeholder, what is this?**
1. [PRD.md](PRD.md) — vision, users, scope, success metrics.
2. [COMPETITIVE-ANALYSIS.md](COMPETITIVE-ANALYSIS.md) — vs optopsy,
vectorbt, backtrader, hftbacktest, nautilus_trader, and DIY.
3. [ROADMAP.md](ROADMAP.md) — when each piece lands, v0.1 → v1.0.
**I'm a Python quant who wants to backtest options strategies.**
1. [PRD.md](PRD.md) §3 — the use cases, including the Python ones.
2. [06-python-bindings.md](06-python-bindings.md) — PyO3 architecture,
API sketch, packaging.
3. [ROADMAP.md](ROADMAP.md) — PyPI wheels land at v0.4.
**I'm a downstream consumer of backtest results (ChainView, notebooks).**
1. [05-analytics-and-reporting.md](05-analytics-and-reporting.md) —
the IronCondor result bundle: `manifest.json` + Parquet tables.
2. [01-domain-model.md](01-domain-model.md) — the canonical types the
bundle serializes.
3. [SEMVER.md](SEMVER.md) — how the bundle schema is versioned.
**I'm evaluating this for a production research / CI pipeline.**
1. [PRD.md](PRD.md) §1.2 — performance and security as first-class
commitments; the HFT-grade audience expectation.
2. [07-performance-and-security.md](07-performance-and-security.md) — hot-path
performance budgets (DESIGN TARGETS), the threat model, and untrusted-input
hardening.
3. [`../SECURITY.md`](../SECURITY.md) — the vulnerability report channel and
scope.
**I'm contributing to the repo.**
1. [00-design-bootstrap.md](00-design-bootstrap.md) and the
[ADRs](adr/) — why things are shaped the way they are.
2. [02-engine-architecture.md](02-engine-architecture.md) — the replay
loop, `Strategy` trait, determinism contract.
3. [TESTING.md](TESTING.md) — what CI will run and how to add a test.
**I want to understand or extend fill simulation.**
1. [04-execution-models.md](04-execution-models.md) — naive vs
realistic modes, slippage config, market impact, why latency is
deferred, limits of each.
2. [specs/option-chain-orderbook.md](specs/option-chain-orderbook.md)
— the matching surface realistic mode drives.
3. [ADR-0002](adr/0002-order-book-level-fill-simulation.md) — why
order-book-level fills are the differentiator.
**I want to add a data source.**
1. [03-data-layer.md](03-data-layer.md) — historical CSV/Parquet
ingestion schema, synthetic chains, caching.
2. [specs/optionstratlib.md](specs/optionstratlib.md) — the upstream
chain and strategy types you normalize into.
## Document inventory
### Numbered design documents
| 00 | [00-design-bootstrap.md](00-design-bootstrap.md) | All | Draft v1.0 |
| 01 | [01-domain-model.md](01-domain-model.md) | Engineers | Draft v1.0 |
| 02 | [02-engine-architecture.md](02-engine-architecture.md) | Engineers | Draft v1.0 |
| 03 | [03-data-layer.md](03-data-layer.md) | Engineers | Draft v1.0 |
| 04 | [04-execution-models.md](04-execution-models.md) | Engineers, quants | Draft v1.0 |
| 05 | [05-analytics-and-reporting.md](05-analytics-and-reporting.md) | Engineers, quants | Draft v1.0 |
| 06 | [06-python-bindings.md](06-python-bindings.md) | Python users | Draft v1.0 |
| 07 | [07-performance-and-security.md](07-performance-and-security.md) | Engineers, adopters | Draft v1.0 |
### Cross-cutting documents
| [PRD.md](PRD.md) | All | Draft v1.0 |
| [ROADMAP.md](ROADMAP.md) | All | Living |
| [TESTING.md](TESTING.md) | Contributors | Draft v1.0 |
| [COMPETITIVE-ANALYSIS.md](COMPETITIVE-ANALYSIS.md) | Decision-makers | Draft v1.0 |
| [SEMVER.md](SEMVER.md) | Contributors | Draft v1.0 |
| [RELEASE-PROCESS.md](RELEASE-PROCESS.md) | Maintainers | Draft v1.0 |
### External specifications (reference)
| [specs/optionstratlib.md](specs/optionstratlib.md) | `optionstratlib` — strategies, Greeks, chains |
| [specs/option-chain-orderbook.md](specs/option-chain-orderbook.md) | `option_chain_orderbook` — hierarchical matching |
| [specs/README.md](specs/README.md) | How to update these specs |
## Architecture Decision Records
Lightweight ADRs in **Context → Decision → Consequences →
Alternatives** format. Every non-obvious technical choice is captured
here.
| [0001](adr/0001-migrate-optionstratbacktest-core.md) | Migrate the OptionStratBacktest core instead of starting from scratch |
| [0002](adr/0002-order-book-level-fill-simulation.md) | Order-book-level fill simulation as a first-class execution mode |
| [0003](adr/0003-money-as-integer-cents.md) | Money as integer cents across every boundary |
| [0004](adr/0004-parquet-result-bundle.md) | Parquet tables + `manifest.json` as the result-bundle format |
| [0005](adr/0005-pyo3-python-bindings.md) | PyO3 bindings packaged with maturin, published to PyPI |
| [0006](adr/0006-rl-layer-deferred.md) | Reinforcement-learning layer deferred to post-1.0 |
| [0007](adr/0007-production-grade-performance-and-security.md) | Performance and security as first-class, testable product commitments |
## Conventions used in these docs
- **Money is integer cents** (`u64`/`u128`/`i64`) at every API,
storage, and serialization boundary — never `f64`. Derived analytic
values (Greeks, IV, ratios) are the only documented exception. See
[ADR-0003](adr/0003-money-as-integer-cents.md).
- **The result bundle** is a directory: `manifest.json` plus
`fills.parquet`, `equity_curve.parquet`, `positions.parquet`,
`greeks_attribution.parquet`. IronCondor writes it;
[ChainView](https://github.com/joaquinbejar/ChainView) replay mode
consumes it.
- **Diagrams** use box-drawing characters; no images, so they render
in any terminal, IDE, and on GitHub.
- **Code samples are illustrative.** Until the first implementation
lands there is no source of truth in `src/`; the samples sketch the
intended shape and may drift during implementation.
- **Cross-repo links** are absolute GitHub URLs
(`https://github.com/joaquinbejar/<Repo>`); within-repo links are
relative.
- **Status** values: `Draft`, `Living`, `Accepted`, `Deprecated`,
`Superseded by …`.
## Coding rules (binding)
These design documents describe **what** to build. The **how** lives in
two binding documents at the repo root:
- [`../CLAUDE.md`](../CLAUDE.md) — high-level architecture, key
decisions, module boundaries, and the agent workflow.
- [`../rules/global_rules.md`](../rules/global_rules.md) — Rust coding
rules (compiler attributes, type safety, arithmetic, error handling,
engine/replay-loop and execution discipline, the PyO3 boundary, and
the pre-submission checklist). Top-priority non-negotiables: integer
cents not `f64` for money, no `anyhow` outside `main()` / examples, a
deterministic engine loop, and no panic across the FFI boundary.
Any code change must satisfy both. If a design document conflicts with
`rules/global_rules.md`, the rules document wins — the design doc is
the bug. The design is **under active review** — these documents are
maintained locally during the design phase and the v0.1-relevant reviewer
recommendations are being cleared before the set is declared stable; the
first implementation PR (v0.1.0) is what turns them into code.
## How to update these docs
1. Open a PR with the prose change.
2. If the change reflects a non-obvious decision, add or update an ADR
under [adr/](adr/).
3. Bump the document's `Status` and `Last edit` block at the top.
4. Reference the change from [ROADMAP.md](ROADMAP.md) if it affects
scope or milestone acceptance criteria.
5. If the change touches the result-bundle contract, mirror it in the
ChainView design docs in the same week — the two repos must never
describe the bundle differently.