IBKR Four-Container Architecture¶

Overview¶

Phase 8 以降の IBKR lane は、gateway / underlying / spread / trader の 4-container 構成で運用する。

                  ┌──────────────────────┐
                  │   IBeam Gateway      │
                  │   (voyz/ibeam)       │
                  │   :5000 (internal)   │
                  │   :15000 (host)      │
                  └──────┬───────────────┘
                         │ HTTPS
          ┌──────────────┼──────────────────────┐
          ▼              ▼                      ▼
┌──────────────┐ ┌────────────────┐  ┌──────────────────┐
│ Quote Coll.  │ │ Spread Coll.   │  │ Trader           │
│ (underlying) │ │ (option chains)│  │ (order execution)│
│ 60s interval │ │ 120s interval  │  │ 45s scan loop    │
│ SPY/QQQ/IWM  │ │ ATM put spreads│  │ entry/exit/state │
│ → quotes.jsonl│ │ → spread.jsonl│  │ → trade_log.jsonl│
└──────────────┘ └────────────────┘  └──────────────────┘

Containers¶

Container	Responsibility	Runtime cadence	Output
`aegis-lt-ibkr-gateway`	IBeam authentication / Client Portal session bridge	22h recycle window	HTTPS API on `:15000`
`aegis-lt-ibkr-quote-collector`	Underlying bid/ask/last snapshots	60s	`ibkr_underlying_quotes.jsonl`
`aegis-lt-ibkr-spread-collector`	Front-month ATM put spread resolution + leg snapshots + whatIf	120s	`ibkr_spread_quotes.jsonl`
`aegis-lt-ibkr-trader`	Put credit spread trading engine (scan → order → fill → position mgmt)	45s	`state.json` + `trade_log.jsonl`

Compose / Workflow mapping¶

Unit	Compose file	GitHub Actions workflow
Gateway	`aegis_v3/lt-rust-docker/docker-compose.lt-ibkr-gateway.yml`	`.github/workflows/deploy-lt-ibkr-gateway.yml`
Underlying collector	`aegis_v3/lt-rust-docker/docker-compose.lt-ibkr-quote-collector.yml`	`.github/workflows/deploy-lt-ibkr-quote-collector.yml`
Spread collector	`aegis_v3/lt-rust-docker/docker-compose.lt-ibkr-spread-collector.yml`	`.github/workflows/deploy-lt-ibkr-spread-collector.yml`
Trader	`aegis_v3/lt-rust-docker/docker-compose.lt-ibkr-trader.yml`	`.github/workflows/deploy-lt-ibkr-trader.yml`

Network / Ports¶

Gateway は host port 15000 を公開し、Client Portal API を HTTPS で受ける
Container internal listener は 5000
Collectors は host.docker.internal / host-network 到達を前提に gateway へ接続する
Gateway を直接 compose 再作成せず、collector 側だけを差し替えられるのが狙い

Data paths¶

Artifact	Path
Underlying JSONL	`/volume1/aegis/quote_samples_rust/ibkr_underlying_quotes.jsonl`
Spread JSONL	`/volume1/aegis/quote_samples_rust/ibkr_spread_quotes.jsonl`
Trader state	`/volume1/aegis/ibkr_trader/state.json`
Trade log	`/volume1/aegis/ibkr_trader/trade_log.jsonl`
PT / WFT logs	`/volume1/aegis/logs/pt`
Replay / clamp traces	`/volume1/aegis/wft_state/pt_replay_log/`

Why four containers¶

認証寿命と quote cadence を分離し、gateway の再認証が quote loop を巻き込まないようにする
underlying と spread で API shape / retry / latency 特性が異なるため、障害切り分けを分ける
Phase 6.1 の spread hardening を gateway や underlying collector に波及させず deploy できる
trader は注文の発注・ポーリング・キャンセルを行うため、shadow collector とは独立した lifecycle を持つ
trader のデフォルトは --dry-run で安全。live trading は GHA の live_trading input で明示的に有効化