---
title: "Horizon Architecture"
description: "System design, component overview, and design principles behind the Horizon SDK."
icon: "sitemap"
---

## Horizon Design Principles

<CardGroup cols={2}>
  <Card title="Rust Core" icon="shield">
    All critical paths run in Rust: risk checks, order management, position tracking, exchange communication, and fill processing. Python never touches the hot path.
  </Card>
  <Card title="No IPC" icon="bolt">
    Python calls Rust directly via PyO3. Zero serialization overhead. No sockets, no message queues, no JSON encoding between layers.
  </Card>
  <Card title="f64 Everywhere" icon="hashtag">
    All numeric values at the Python boundary use `f64` for simplicity. No `Decimal` conversion needed.
  </Card>
  <Card title="Enum Dispatch" icon="code-branch">
    Exchange backends use enum dispatch (`ExchangeBackend`) instead of trait objects. Avoids dynamic dispatch overhead and unsafe downcasts.
  </Card>
</CardGroup>

## Component Overview

### Horizon Engine

The `Engine` is the central orchestrator. It owns:

- **RiskManager**: 8-point risk pipeline that every order passes through
- **OrderManager**: tracks order lifecycle with DashMap for concurrent access
- **PositionTracker**: maintains positions with atomic P&L calculations
- **ContingentManager**: manages stop-loss, take-profit, and bracket orders with OCO linking
- **Exchange Map**: multiple exchange backends keyed by name (e.g., `"paper"`, `"polymarket"`, `"kalshi"`)
- **FeedManager**: tokio runtime with spawned async tasks for WebSocket/REST feeds
- **Database**: optional SQLite persistence layer for crash recovery

### Exchange Model

Exchanges are registered by name in a `HashMap<String, ExchangeBackend>`. The first exchange becomes the **primary** (default for routing). Additional exchanges can be added via `add_exchange()`.

All exchanges implement the `Exchange` trait:
- `submit_order()`: submit an order to the exchange
- `cancel_order()`: cancel a single order
- `cancel_all()`: cancel all orders
- `cancel_for_market()`: cancel orders for a specific market
- `drain_fills()`: pull pending fills
- `fetch_positions()`: sync positions from the exchange
- `amend_order()`: amend an order's price and/or size (cancel+resubmit on live, in-place on paper)

### Feed System

The `FeedManager` owns a tokio runtime. Each feed runs as a spawned async task:

| Feed | Transport | Update Model |
|------|-----------|-------------|
| **BinanceWS** | WebSocket | Real-time trade stream |
| **PolymarketBook** | WebSocket | Orderbook snapshots |
| **KalshiBook** | HTTP polling | Orderbook polling |
| **RESTFeed** | HTTP polling | Generic REST endpoint |

Feed data is stored in a shared `DashMap<String, FeedSnapshot>` and read by the Python layer each cycle via `engine.feed_snapshot(name)`.

### Contingent Orders

The `ContingentManager` manages synthetic stop-loss and take-profit orders. These are not sent to the exchange. Instead, the engine monitors triggers each tick cycle and converts them to real `OrderRequest`s when conditions are met.

- **Stop-loss**: triggers when price crosses below (sell) or above (buy) the trigger level
- **Take-profit**: triggers on price target or unrealized PnL threshold
- **OCO linking**: two contingent orders can be linked so that when one triggers, the other is automatically canceled
- **Bracket orders**: entry order + stop-loss + take-profit, all submitted and linked in one call

### Persistence Layer

SQLite with WAL mode provides crash recovery and an audit trail:

- **fills**: append-only journal with `INSERT OR IGNORE` dedup
- **order_events**: order lifecycle log (one row per status change)
- **position_snapshots**: periodic snapshots for fast recovery
- **risk_events**: kill switch activations, violations
- **strategy_runs**: run start/end timestamps

Recovery works by loading the latest position snapshot and replaying fills since that snapshot.

## Horizon Data Flow

```
Pipeline Function → list[Quote]
        ↓
   cancel_market()          ← cancel stale orders
        ↓
   tick() / poll_fills()    ← process fills from exchange
        ↓
   check_contingent_triggers() ← fire stop-loss / take-profit
        ↓
   submit_quotes()          ← route through risk pipeline
        ↓
   Risk Pipeline (8 checks) ← reject or pass
        ↓
   Exchange Backend          ← submit to exchange
        ↓
   OrderManager              ← track order state
        ↓
   PositionTracker           ← update on fill
        ↓
   Database                  ← persist fill + order event
```

## Monitoring Stack

Horizon provides three monitoring layers:

| Layer | Component | Description |
|-------|-----------|-------------|
| **Metrics** | `MetricsServer` | Prometheus `/metrics` endpoint with counters, gauges, and histograms |
| **Alerts** | `AlertManager` | Multi-channel alerts (Discord, Telegram, webhooks, log) with cooldown throttling |
| **Calibration** | `CalibrationTracker` | Tracks prediction accuracy with Brier scores over time |
| **Dashboard** | TUI (Textual) | Real-time terminal dashboard with P&L, positions, orders, risk, fills, feeds |
