# tapanhaz/fsticker architecture

> Architecture diagram of the GitHub repository tapanhaz/fsticker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tapanhaz/fsticker
- Repository: https://github.com/tapanhaz/fsticker

## Overview

fsticker is a multi-broker market-data feed for Shoonya/NorenWS-compatible WebSockets. A user configures broker credentials, starts a synchronous or asyncio feed, and subscribes instruments; broker sessions reconnect and resubscribe independently while the merge layer produces a deduplicated tick stream. Optional stages build OHLC candles and persist completed candles to TimescaleDB. The graph reflects documented capabilities and source-index references; several implementation relationships are not directly visible in the excerpts, so they are omitted rather than inferred.

Main entry points: [`fsticker/include/merge/sf_feed.hpp`](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/sf_feed.hpp) (Merged feed coordinator), [`fsticker/include/ticker.hpp`](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/ticker.hpp) (Broker ticker), [`fsticker/bridge.hpp`](https://github.com/tapanhaz/fsticker/blob/main/fsticker/bridge.hpp) (Sync feed API), [`fsticker/async_feed.py`](https://github.com/tapanhaz/fsticker/blob/main/fsticker/async_feed.py) (Async feed API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Feed APIs"]
  node_sync_api["Sync feed API<br/>[bridge.hpp]"]
  node_async_api["Async feed API<br/>[async_feed.py]"]
  node_queue["Async event queue"]
end

subgraph group_connections["Broker Connections"]
  node_ticker["Broker ticker<br/>[ticker.hpp]"]
  node_session["WebSocket session<br/>[session.hpp]"]
  node_pinning["IP pinning<br/>[ip_pinning.hpp]"]
  node_backoff["Reconnect backoff<br/>[backoff.hpp]"]
end

subgraph group_merge["Merge Pipeline"]
  node_feed["Merged feed coordinator<br/>[sf_feed.hpp]"]
  node_reconstructor["Tick reconstruction<br/>[reconstructor.hpp]"]
  node_store["Feed store<br/>[feed_store.hpp]"]
  node_tick_types["Tick model<br/>[tick.hpp]"]
end

subgraph group_outputs["Feed Outputs"]
  node_candle["Candle engine<br/>[candle_engine.hpp]"]
  node_timescale["Candle persistence<br/>[timescale_sink.hpp]"]
end

node_user(("Feed consumer"))
node_broker(("Broker WebSockets"))
node_database[("Postgres / TimescaleDB")]

node_user -->|"starts and subscribes"| node_sync_api
node_user -->|"starts and subscribes"| node_async_api
node_sync_api -->|"coordinates feed"| node_feed
node_feed -.->|"manages brokers"| node_ticker
node_ticker -->|"connects and subscribes"| node_broker
node_ticker -->|"uses session"| node_session
node_ticker -->|"backs off retries"| node_backoff
node_session -->|"pins connections"| node_pinning
node_feed -->|"uses reconstruction"| node_reconstructor
node_feed -->|"uses store"| node_store
node_feed -->|"configures candles"| node_candle
node_feed -->|"configures persistence"| node_timescale
node_reconstructor -->|"produces ticks"| node_tick_types
node_store -->|"stores ticks"| node_tick_types
node_candle -->|"consumes ticks"| node_tick_types
node_timescale -->|"persists candles"| node_database
node_feed -.->|"bridges async events"| node_queue
node_queue -.->|"delivers events"| node_async_api
node_sync_api -->|"delivers callbacks"| node_user
node_async_api -->|"delivers callbacks"| node_user

click node_sync_api "https://github.com/tapanhaz/fsticker/blob/main/fsticker/bridge.hpp"
click node_async_api "https://github.com/tapanhaz/fsticker/blob/main/fsticker/async_feed.py"
click node_queue "https://github.com/tapanhaz/fsticker/blob/main/fsticker/async_queue_bridge.hpp"
click node_feed "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/sf_feed.hpp"
click node_ticker "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/ticker.hpp"
click node_session "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/session.hpp"
click node_pinning "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/ip_pinning.hpp"
click node_backoff "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/backoff.hpp"
click node_reconstructor "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/reconstructor.hpp"
click node_store "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/feed_store.hpp"
click node_tick_types "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/tick.hpp"
click node_candle "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/candle_engine.hpp"
click node_timescale "https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/timescale_sink.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_sync_api,node_async_api,node_queue toneBlue
class node_ticker,node_session,node_pinning,node_backoff,node_database toneAmber
class node_feed,node_reconstructor,node_store,node_tick_types toneMint
class node_candle,node_timescale toneRose
class node_user,node_broker toneIndigo
```

## Components

### Feed APIs

- [Sync feed API](https://github.com/tapanhaz/fsticker/blob/main/fsticker/bridge.hpp): `fsticker/bridge.hpp`
- [Async feed API](https://github.com/tapanhaz/fsticker/blob/main/fsticker/async_feed.py): `fsticker/async_feed.py`
- [Async event queue](https://github.com/tapanhaz/fsticker/blob/main/fsticker/async_queue_bridge.hpp): `fsticker/async_queue_bridge.hpp`

### Broker Connections

- [Broker ticker](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/ticker.hpp): `fsticker/include/ticker.hpp`
- [WebSocket session](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/session.hpp): `fsticker/include/session.hpp`
- [IP pinning](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/ip_pinning.hpp): `fsticker/include/ip_pinning.hpp`
- [Reconnect backoff](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/backoff.hpp): `fsticker/include/backoff.hpp`

### Merge Pipeline

- [Merged feed coordinator](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/sf_feed.hpp): `fsticker/include/merge/sf_feed.hpp`
- [Tick reconstruction](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/reconstructor.hpp): `fsticker/include/merge/reconstructor.hpp`
- [Feed store](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/feed_store.hpp): `fsticker/include/merge/feed_store.hpp`
- [Tick model](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/tick.hpp): `fsticker/include/merge/tick.hpp`

### Feed Outputs

- [Candle engine](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/candle_engine.hpp): `fsticker/include/merge/candle_engine.hpp`
- [Candle persistence](https://github.com/tapanhaz/fsticker/blob/main/fsticker/include/merge/timescale_sink.hpp): `fsticker/include/merge/timescale_sink.hpp`

### Other components

- **Feed consumer**
- **Broker WebSockets**
- **Postgres / TimescaleDB**

## Connections

- Feed consumer → Sync feed API: starts and subscribes (evidence: `README.md`)
- Feed consumer → Async feed API: starts and subscribes (evidence: `README.md`)
- Sync feed API → Merged feed coordinator: coordinates feed (evidence: `fsticker/bridge.hpp`)
- Merged feed coordinator → Broker ticker: manages brokers (evidence: `fsticker/include/merge/sf_feed.hpp`)
- Broker ticker → Broker WebSockets: connects and subscribes (evidence: `README.md`)
- Broker ticker → WebSocket session: uses session (evidence: `fsticker/include/ticker.hpp`)
- Broker ticker → Reconnect backoff: backs off retries (evidence: `fsticker/include/ticker.hpp`)
- WebSocket session → IP pinning: pins connections (evidence: `fsticker/include/session.hpp`)
- Merged feed coordinator → Tick reconstruction: uses reconstruction (evidence: `fsticker/include/merge/sf_feed.hpp`)
- Merged feed coordinator → Feed store: uses store (evidence: `fsticker/include/merge/sf_feed.hpp`)
- Merged feed coordinator → Candle engine: configures candles (evidence: `fsticker/include/merge/sf_feed.hpp`)
- Merged feed coordinator → Candle persistence: configures persistence (evidence: `fsticker/include/merge/sf_feed.hpp`)
- Tick reconstruction → Tick model: produces ticks (evidence: `fsticker/include/merge/reconstructor.hpp`)
- Feed store → Tick model: stores ticks (evidence: `fsticker/include/merge/feed_store.hpp`)
- Candle engine → Tick model: consumes ticks (evidence: `fsticker/include/merge/candle_engine.hpp`)
- Candle persistence → Postgres / TimescaleDB: persists candles (evidence: `fsticker/include/merge/timescale_sink.hpp`)
- Merged feed coordinator → Async event queue: bridges async events
- Async event queue → Async feed API: delivers events
- Sync feed API → Feed consumer: delivers callbacks (evidence: `README.md`)
- Async feed API → Feed consumer: delivers callbacks (evidence: `README.md`)
