ADR 0003: Broker Adapter Pattern

Status

Accepted

Context

Alpaca is the MVP broker, but later phases include additional broker support. Execution must stay paper-safe by default and support idempotent reconciliation.

Decision

Broker-specific OAuth, account, order, fill, and capability handling live behind adapter boundaries. The pipeline calls broker adapters with an explicit execution mode and idempotency key.

Consequences

New brokers can be introduced without rewriting strategy, risk, order, journal, or portfolio code. Broker-specific errors remain diagnosable while the pipeline keeps a stable response contract.

Verification

Paper E2E evidence must show an order in the broker account and the same trade in the Journal/audit path. Tests must keep live execution explicitly guarded.