Skip to content

System Overview

This page gives a compact, operator-friendly overview of the fyers-store architecture. For visuals, see docs/visuals/system_overview.md.

flowchart LR
  ROOT["fyers-store"]

  subgraph Store
    STORE_A["lifecycle orchestration"]
    STORE_B["safe helpers"]
  end

  subgraph Adapters
    REST["REST<br/>history + orders"]
    WS["WS<br/>market + order"]
  end

  subgraph Backtrader
    BROKER["Broker"]
    FEED["DataFeed"]
  end

  subgraph Persistence
    CACHE["cache<br/>(history)"]
    STATE["state DB<br/>(runtime)"]
  end

  subgraph Safety
    SAFE_A["no idempotency"]
    SAFE_B["auth expiry"]
    SAFE_C["reconnect backoff"]
  end

  ROOT --> Store
  ROOT --> Adapters
  ROOT --> Backtrader
  ROOT --> Persistence
  ROOT --> Safety

At A Glance

  • Store: lifecycle orchestration + safe helpers.
  • REST adapter: history + order actions.
  • WS adapters: market data + order updates.
  • Broker + DataFeed: Backtrader translation.
  • Persistence: cache (history) + state DB (runtime).

Why It Exists

FYERS has constraints that require explicit safety handling: - No client idempotency keys for orders. - Tokens expire daily and can be invalidated by multi-device logins. - WebSocket sessions can disconnect or stall without obvious errors.

The system is designed to surface these failures early and stop trading safely.

Primary Flows

  • History: Store -> cache (DB-first) -> REST gap fill.
  • Live data: WS -> queue -> DataFeed -> bars.
  • Orders: Broker -> REST -> Order WS -> Broker.
  • Recovery: State DB -> REST reconcile -> WS resume.

Failure Handling (Summary)

  • Auth failure: raise AuthError; stop reconnect storms.
  • Order placement failure: no retry; reconcile first.
  • Reconcile failure: fail fast to avoid stale trading.
  • WS disconnect: bounded backoff + resubscribe.

Safety Gates

  • Live orders require LIVE or allow_live_orders.
  • Cache DB and state DB must remain separate.
  • Unknown order states require manual reconciliation.

Scenario Example

Scenario: A process restarts during market hours. - The Broker reloads state from the runtime DB. - It reconciles with REST snapshots before consuming WS messages. - If reconciliation fails, the broker stops trading and raises a clear error.