---
title: "Architecture"
description: "Public architecture of OpenPit and its integration model."
---

# Architecture

Public architecture of OpenPit and its integration model.

## Design Goals

- `Embeddable`: no separate service, no network hop, no runtime requirement
- `Deterministic`: the same order, policy state, and policy set produce the
  same decision
- `Fail-safe by default`: unfinalized reservations roll back automatically
- `Financially precise`: domain values use exact decimal semantics through
  `param` types

## Public API Areas

- `Domain values`: prices, quantities, pnl, cash flow, volume, side, leverage
  Go: `openpit/param`
  Python: `openpit.param`
  C++: `openpit::param`
  Rust: `openpit::param`
  C: `OpenPitParam*` value handles and structs
- `Core entities`: order, execution report, account adjustment, instrument, engine
  Go: package root `openpit`
  Python: package root and `openpit.core`
  C++: `openpit::model` and `openpit::Engine`
  Rust: crate root and `openpit::core`
  C: `OpenPitOrder`, `OpenPitExecutionReport`, and `OpenPitEngine`
- `Pre-trade pipeline`: policies, rejects, requests, reservations, reports
  Go: `openpit/pretrade`
  Python: `openpit.pretrade`
  C++: `openpit::pretrade`
  Rust: `openpit::pretrade`
  C: `OpenPitPretrade*` handles and functions

## Engine

`Engine` coordinates the public pre-trade lifecycle:

1. Build an engine.
2. Run the `start stage`.
3. Execute the deferred request.
4. Finalize the reservation.
5. Apply post-trade feedback.
6. Optionally validate non-trade operation (NTO) batches through
   `apply account adjustments`.

Current engine behavior:

- Policy names must be unique across both stages.
- Threading capability of the engine handle follows from the chosen sync
  policy. See [Threading Contract](Threading-Contract.md).
- A deferred request or reservation depends on the engine instance that
  created it.
- Account-adjustment batch validation is atomic: the first reject aborts the
  whole batch.

## Order, Execution Report and Account Adjustment Contracts

OpenPit currently exposes public integration models for orders, execution reports,
and non-trading account adjustments:

- C++ exposes fixed model value types and client-payload adapter templates:
  `openpit::model::Order`, `openpit::model::ExecutionReport`, and
  `openpit::pretrade::StartPolicyAdapter` /
  `openpit::pretrade::PolicyAdapter`. Adapter policies choose an explicit
  cast mode so dynamic-boundary checks are visible at the call site.
- Go exposes fixed public model records plus generic policy interfaces for
  caller-defined payloads.
- Python exposes fixed public record models:
  `openpit.Order`, `openpit.ExecutionReport`, and `openpit.AccountAdjustment`.
- Rust can evaluate caller-defined order and execution-report types directly
  when they implement the required capability traits. Order traits include
  `HasTradeAmount`, `HasOrderPrice`, `HasInstrument`, and `HasSide`. Report
  traits include `HasPnl`, `HasFee`, and `HasInstrument`. Policies declare
  only the traits they actually use, so a policy that only inspects trade
  amount and price requires `O: HasTradeAmount + HasOrderPrice` and is
  compatible with any order type that provides those two capabilities.
- C exposes POD views and opaque handles for ABI-stable embedders.

All SDKs use the same staged flow and the same standard reject shape.

Language-specific custom-payload guidance is documented in the corresponding
[Custom Go Types](Custom-Go-Types.md), [Custom Python Types](Custom-Python-Types.md),
[Custom JS Types](Custom-JS-Types.md), [Custom Cpp Types](Custom-Cpp-Types.md), and
[Custom Rust Types](Custom-Rust-Types.md) pages.

## Two-Stage Pipeline

OpenPit separates early admission checks from main-stage checks that may
reserve state. The start stage stops at the first reject; the main stage
evaluates every registered policy, aggregates rejects, and rolls back collected
mutations if any reject is produced.

See [Pre-trade Pipeline](Pre-trade-Pipeline.md) for the full lifecycle, return
types, and code examples.

## Account Adjustment Pipeline

`Account adjustment` validation runs as an atomic batch: deterministic
traversal by batch and policy registration order, first reject aborts,
all-or-nothing outcome.

See [Account Adjustments](Account-Adjustments.md) for the data model and
rollback rules.

## State Changes

Main-stage policies do not finalize state directly. They emit `Pre-trade mutation`
pairs that the engine applies later.

Current public mutation kinds are:

- Reserve notional for a settlement asset
- Set a kill-switch state

## Current Boundaries

OpenPit is intentionally narrow:

- It is a pre-trade engine, not an OMS or EMS.
- It does not provide persistence or external data sources.
- It does not provide venue connectivity.
- Built-in policies may participate in the start, main, post-trade, and
  account-adjustment stages according to their state and reconciliation needs.

## Related Pages

- [Getting Started](Getting-Started.md): First engine construction
- [Custom Go Types](Custom-Go-Types.md): Typed Go client payloads
- [Custom Python Types](Custom-Python-Types.md): Python model subclasses
- [Custom JS Types](Custom-JS-Types.md): Typed JavaScript policy payloads
- [Custom Cpp Types](Custom-Cpp-Types.md): C++ polymorphic client payloads
- [Custom Rust Types](Custom-Rust-Types.md): Capability traits and wrapper authoring
- [Pre-trade Pipeline](Pre-trade-Pipeline.md): Request and reservation lifecycle
- [Account Adjustments](Account-Adjustments.md): Non-trade operation (NTO) batch
  model and semantics
- [Policies](Policies.md): Built-in controls and custom policy hooks
- [Domain Types](Domain-Types.md): Typed financial values used by the engine