# raahi-bhushan/trading-algo architecture

> Architecture diagram of the GitHub repository raahi-bhushan/trading-algo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/raahi-bhushan/trading-algo
- Repository: https://github.com/raahi-bhushan/trading-algo

## Overview

##### Project Type and Purpose
- This is an algorithmic trading toolkit (full-stack library/tool) that provides:
- Broker-agnostic core APIs for order management and market data
- Plug-and-play broker integrations (Zerodha, Fyers, etc.)
- A strategy layer where users implement and run trading algorithms (Survivor, Wave)
- Primary use case: fetch live/historical data, run strategies, place/monitor orders through different brokers.

##### File Structure
- Top-Level:
.pyproject.toml, uv.lock, .sample.env, .gitignore → build & env config
README.md, CONTRIBUTING.md → documentation
dispatcher.py, orders.py, logger.py → core routing, order utilities, logging
brokers/ → core interfaces and broker implementations
strategy/ → strategy configurations & code
- brokers/ Substructure:
brokers/core → common enums, errors, gateway interface, schemas
brokers/integrations → concrete drivers for each broker
brokers/auth → multiple authentication schemes (manual, tokens, TOTP)
brokers/net → HTTP client and rate-limiter
brokers/mappings, symbols, registry → lookup tables & plugin registry
- Patterns:
- Plugin/Registry pattern for broker drivers
- Layered architecture: Core API → Integrations → Strategy layer
- Configuration-driven initialization via environment variables

##### README Insights
- Describes supported brokers, setup steps (uv sync), environment config
- Highlights core components: brokers/, dispatcher.py, orders.py, logger.py, strategy/
- Emphasizes strategy invocation and broker gateway usage

a. Main Components:
1. Strategy Layer (strategy/*.py)
2. Core Library
- BrokerGateway (interface + registry)
- Dispatcher (data routing, queue management)
- Orders module (order creation, tracking)
- Logger
3. Broker Integrations
- Auth module (manual, tokens, TOTP)
- Integrations/fyers, zerodha, fyrodha drivers
- Net layer (HTTP client, rate-limiter, WebSocket hooks)
4. External Services
- Broker REST APIs & WebSockets (Fyers, Zerodha)
5. Config & Data Stores
- Environment (.env)
- Strategy config YAML files
b. Relationships & Interactions:
– Strategy invokes BrokerGateway → selects integration driver via registry
– BrokerGateway uses Auth + Net modules → communicates with Broker API
– Dispatcher >> feeds live/historical data into Strategy
– Orders module submits/cancels orders via BrokerGateway
– Logger tracks all events and errors
c. Architectural Patterns / Principles:
– Dependency Inversion: Strategies depend on abstract BrokerGateway, not concrete APIs
– Plugin Architecture: Dynamic registration of new brokers via registry modules
– Single Responsibility: Separate modules for auth, networking, mapping, strategies
– Config-Driven Behavior: .env for secrets, YAML for strategy parameters
d. Key Technologies / Libraries:
– Python 3.10+ (pyproject.toml)
– uv (Astral’s dependency manager)
– HTTP & WebSocket (brokers/net/http.py)
– YAML parsing for strategy configs
– Environment variable loader via sample .env

##### Elements
– Clear component labels (Strategy, BrokerGateway, Dispatcher, Auth, Net, Drivers, Broker APIs)
- Rectangles for in-process modules (Strategy, Core)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Strategy Layer
    subgraph "Strategy Layer" 
        style Strategy_Layer fill:#f9f,stroke:#333
        Strategy_Survivor["Survivor Strategy"]:::strategy
        Strategy_Wave["Wave Strategy"]:::strategy
        Strategy_Survivor -->|"uses config"| Config_Surv
        Strategy_Wave -->|"uses config"| Config_Wave
    end

    %% Core Library
    subgraph "Core Library"
        style Core_Lib fill:#bbf,stroke:#333
        Dispatcher["Dispatcher"]:::core
        Orders["Orders Module"]:::core
        LoggerCore["Logger"]:::core
        BrokerGateway["BrokerGateway (interface)"]:::core
        InterfaceDefs["Interface Definitions"]:::core
        Enums["Core Enums"]:::core
        Errors["Core Errors"]:::core
        Schemas["Core Schemas"]:::core
        PluginRegistry["Broker Registry (plugin loader)"]:::core
    end

    %% Broker Integrations
    subgraph "Broker Integrations"
        style Integrations fill:#bfb,stroke:#333
        subgraph "Authentication"
            style Auth fill:#dfd,stroke:#333
            Auth_Manual["Manual Auth"]:::integration
            Auth_Tokens["Token Auth"]:::integration
            Auth_TOTP["TOTP Auth"]:::integration
        end
        subgraph "Networking"
            style Net fill:#dfd,stroke:#333
            Net_HTTP["HTTP Client"]:::integration
            Net_Rate["Rate Limiter"]:::integration
        end
        BrokerLogging["Broker Logging Helper"]:::integration
        subgraph "Drivers"
            style Drivers fill:#dfd,stroke:#333
            Driver_Zerodha["Zerodha Driver"]:::integration
            Driver_Fyers["Fyers Driver"]:::integration
            Driver_Fyrodha["Fyrodha Driver"]:::integration
        end
    end

    %% External Services
    subgraph "External Broker APIs"
        style External fill:#fcf,stroke:#333
        API_Zerodha["Zerodha REST/WebSocket"]:::external
        API_Fyers["Fyers REST/WebSocket"]:::external
        API_Fyrodha["Fyrodha REST/WebSocket"]:::external
    end

    %% Config & Data
    subgraph "Config & Data"
        style ConfigLayer fill:#ffd,stroke:#333
        EnvFile[".sample.env"]:::config
        PyProject["pyproject.toml"]:::config
        Config_Surv["survivor.yml"]:::config
        Config_Wave["wave.yml"]:::config
    end

    %% Relationships
    ConfigLayer -->|loads| BrokerGateway
    Strategy_Survivor -->|invokes| BrokerGateway
    Strategy_Wave -->|invokes| BrokerGateway
    Dispatcher -->|feeds data to| Strategy_Survivor
    Dispatcher -->|feeds data to| Strategy_Wave
    Orders -->|submits orders via| BrokerGateway
    BrokerGateway -->|selects driver via| PluginRegistry
    PluginRegistry --> Driver_Zerodha
    PluginRegistry --> Driver_Fyers
    PluginRegistry --> Driver_Fyrodha
    BrokerGateway -->|uses| InterfaceDefs
    BrokerGateway -->|uses| Enums
    BrokerGateway -->|uses| Errors
    BrokerGateway -->|uses| Schemas
    Driver_Zerodha -->|uses| Auth_Manual
    Driver_Zerodha -->|uses| Auth_Tokens
    Driver_Zerodha -->|uses| Auth_TOTP
    Driver_Zerodha -->|uses| Net_HTTP
    Driver_Zerodha -->|uses| Net_Rate
    Driver_Zerodha -->|logs via| BrokerLogging
    Driver_Zerodha -->|calls| API_Zerodha
    Driver_Fyers -->|calls| API_Fyers
    Driver_Fyrodha -->|calls| API_Fyrodha
    Dispatcher -->|logs events to| LoggerCore
    Orders -->|logs events to| LoggerCore
    BrokerGateway -->|logs events to| LoggerCore

    %% Click Events
    click Strategy_Survivor "https://github.com/raahi-bhushan/trading-algo/blob/main/strategy/survivor.py"
    click Strategy_Wave "https://github.com/raahi-bhushan/trading-algo/blob/main/strategy/wave.py"
    click Config_Surv "https://github.com/raahi-bhushan/trading-algo/blob/main/strategy/configs/survivor.yml"
    click Config_Wave "https://github.com/raahi-bhushan/trading-algo/blob/main/strategy/configs/wave.yml"
    click Dispatcher "https://github.com/raahi-bhushan/trading-algo/blob/main/dispatcher.py"
    click Orders "https://github.com/raahi-bhushan/trading-algo/blob/main/orders.py"
    click LoggerCore "https://github.com/raahi-bhushan/trading-algo/blob/main/logger.py"
    click BrokerLogging "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/logging.py"
    click BrokerGateway "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/core/gateway.py"
    click InterfaceDefs "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/core/interface.py"
    click Enums "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/core/enums.py"
    click Errors "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/core/errors.py"
    click Schemas "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/core/schemas.py"
    click PluginRegistry "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/registry.py"
    click Auth_Manual "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/auth/manual.py"
    click Auth_Tokens "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/auth/tokens.py"
    click Auth_TOTP "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/auth/totp.py"
    click Net_HTTP "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/net/http.py"
    click Net_Rate "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/net/ratelimiter.py"
    click Driver_Zerodha "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/integrations/zerodha/driver.py"
    click Driver_Fyers "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/integrations/fyers/driver.py"
    click Driver_Fyrodha "https://github.com/raahi-bhushan/trading-algo/blob/main/brokers/integrations/fyrodha/driver.py"
    click EnvFile "https://github.com/raahi-bhushan/trading-algo/blob/main/.sample.env"
    click PyProject "https://github.com/raahi-bhushan/trading-algo/blob/main/pyproject.toml"

    %% Styles
    classDef strategy fill:#f9f,stroke:#333
    classDef core fill:#bbf,stroke:#333
    classDef integration fill:#bfb,stroke:#333
    classDef external fill:#fcf,stroke:#333
    classDef config fill:#ffd,stroke:#333
```
