Design Decisions

This page captures the key safety-driven design choices in fyers-store.

Store Orchestrates Adapters

Decision: Adapter lifecycles are owned by the Store. Why: Centralized control makes startup and shutdown deterministic and easier to audit. Safety impact: Prevents partial startups where WS runs without REST or state sync.

Scenario: - A strategy starts before cache is initialized. - Store fails fast and prevents trading with missing history.

Cache Is Not State

Decision: Historical cache and runtime state use separate databases. Why: The cache is rebuildable; state is authoritative for live trading. Safety impact: Prevents cache rebuilds from wiping live order state.

Scenario: - Operator deletes the cache to rebuild it. - Live state remains intact because it is stored separately.

No Retries on place_order

Decision: place_order is single-shot and never auto-retries. Why: FYERS has no client idempotency; retries can create duplicate orders. Safety impact: Unknown state is surfaced for explicit reconciliation.

Scenario: - place_order times out. - Operator checks Order WS + orderbook() before any manual retry.

Fail-Fast Reconciliation

Decision: Reconciliation errors halt trading. Why: Trading on stale positions is riskier than stopping. Safety impact: Operators are forced to fix auth/connectivity before resuming.

Scenario: - REST snapshot fails during reconnect. - Broker halts instead of assuming state is still correct.

Explicit Environment Guard

Decision: Live orders are blocked unless environment is LIVE or allow_live_orders is enabled. Why: Prevents accidental live trading during development or testing. Safety impact: Requires explicit operator intent to go live.

Scenario: - A developer runs a live runner in DEV mode. - The broker blocks live orders with a clear error message.