Historical Cache (src/fyers_store/persistence/)

The historical cache provides DB-first access to FYERS history bars. It is designed as a rebuildable cache, not a durable source of truth.

flowchart TD
    STORE["FyersStore.get_history()"]
    CACHE["SQLiteHistoricalCache<br/>(sqlite_cache.py)"]
    DB["SQLite DB (WAL)"]
    REST["REST Adapter history()"]
    FAIL_LOCK["database is locked<br/>retry/backoff"]

    STORE --> CACHE
    CACHE -->|"get_bars"| DB
    CACHE -->|"detect_gaps"| DB
    STORE -->|"fill gaps"| REST
    STORE -->|"upsert_bars"| CACHE
    CACHE -->|"INSERT OR REPLACE"| DB

    DB -.write contention.-> FAIL_LOCK

Market-Aware Gap Detection

flowchart TD
    REQUEST["(symbol,res,start,end)"] --> DETECT["detect_gaps()"]
    DETECT --> CAL["NSE calendar rules<br/>(config/nse_calendar.yaml)"]
    CAL --> FILTER["filter weekends/off-session/holidays"]
    FILTER --> GAPS["remaining gaps fetched via REST"]