# System Guide

## Current architecture

The system now has one trading engine and a small number of thin runners.

```text
                      StrategyEngine
                    (src/core/strategy.ts)
                            |
        -------------------------------------------------
        |                       |                       |
      replay                  demo                    live
  recorded data +        live data + real       live data + real
  emulated chase fills   demo API fills         live API fills
```

## Single source of truth

`src/core/strategy.ts` owns:

- signal computation
- volatility/range gating
- entry decision logic
- exit logic
- conviction sizing
- cooldown / streak state
- capital / fee / pnl tracking
- chase-limit emulation helpers

## Runners

### Replay runner
File: `src/runners/replay.ts`

This is now **replay-only**.

Usage:
```bash
txocap-replay data/sessions/<session-dir>
```

It injects:
- recorded trades
- recorded orderbook snapshots

It executes fills with:
- emulated maker chase limits against recorded orderbook data

### Demo benchmark runner
File: `src/runners/demo-benchmark.ts`

Usage:
```bash
txocap-demo-benchmark
```

It injects:
- live multi-venue flow data
- live Bybit orderbook data

It executes fills with:
- real maker chase limit orders on Bybit demo

It also publishes IPC so the dashboard can attach.

### Dashboard
File: `src/runners/dashboard.ts`

Usage:
```bash
txocap-dashboard
```

The dashboard is a pure IPC consumer. It renders:
- `trade`
- `signal`
- `engine_state`

It does not run any separate strategy logic.

## IPC contract

Socket:
- `.run/tape.sock`

Messages used by the dashboard:
- `trade` — normalized trade stream
- `signal` — tape signal snapshots for market context
- `engine_state` — StrategyEngine/account/position state

## Modes

The only meaningful modes are:

- `replay`
- `demo`
- `live`

There is no supported separate `sim` runtime anymore.

## Fill model

### Replay
Maker chase is emulated against recorded orderbook snapshots:

1. post at bid/ask
2. wait 3 seconds
3. if opposing side crosses our level, fill at our limit
4. otherwise cancel/reprice
5. retry up to 3 times

### Demo
Same intent, but real orders are sent to Bybit demo.

### Live
Reserved for the same intent against Bybit live.

## Current production-style profile

Profile: `PROFILES.MAKER_OPT`

Key gates:
- `rv >= 5`
- `rv <= 7`
- maker fees
- chase limit entries
- conviction sizing
- max hold 120s

## Current realistic replay result

Aggregate across recorded sessions:
- **MAKER_OPT:** +$109.81
- **Trades:** 21
- **Win rate:** 85.7%
- **Max DD:** 1.88%

This uses realistic orderbook-based chase fill emulation, not the old optimistic bar-touch fill assumption.

## Relevant commands

```bash
txocap-dashboard
txocap-replay data/sessions/<session-dir>
node dist/research/compare-profiles.js
txocap-demo-benchmark
txocap-account-check
txocap-demo-fund USDT:10000 BTC:1
txocap-order-place --side Buy --qty 0.001 --category linear --symbol BTCUSDT
```

## What was removed

No longer part of the active runtime model:

- old stream runtime
- old tape server runtime
- old paper-trade dashboard path
- old actionables-based trading path
- old `SimAccount`