# blankly-finance/blankly architecture

> Architecture diagram of the GitHub repository blankly-finance/blankly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-02-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/blankly-finance/blankly
- Repository: https://github.com/blankly-finance/blankly

## Overview

##### Main Components
- Core Engine – Represented by the main blankly package (the __init__.py and __main__.py files) that orchestrates running strategies.
- Data Module – Found in blankly/data and its templates. This handles data ingestion and custom event reading (e.g., JsonEventReader).
- Deployment Module – Under blankly/deployment, this module includes CLI, API endpoints, deployment logic, keys management, and UI components.
- Exchange Interfaces – Under blankly/exchanges and its subdirectories (including various interfaces for Alpaca, Binance, Coinbase, FTX, OANDA, etc.). These components abstract the interactions with external markets via REST APIs and websockets.
- Strategy/Model and Frameworks – The blankly/frameworks directory, including submodules for models, strategies, multiprocessing (blankly_bot), and screeners. These are used to define and execute trading strategies along with their state management.
- Order Management – Contained within blankly/exchanges/orders. This is responsible for different order types (limit, market, stop loss, etc.).
- Indicators and Metrics – Provided under blankly/indicators and blankly/metrics to compute technical indicators and portfolio metrics.
- Utilities – Common utilities and exception handling under blankly/utils.
- Testing and Examples – Supporting examples (under examples) and tests (under tests) that illustrate usage scenarios and validate components.

##### Relationships & Interactions
- The core engine integrates with the strategy/model definitions (via frameworks) to determine trading behavior and simulation requirements.
- Strategy/model components depend on data ingestion (data module) to receive market data and on the indicators module to compute signal values.
- The deployment module translates local development into live or paper trading execution, switching between simulation and live environments by directing calls to the appropriate exchange interfaces.
- Exchange interfaces are the adapters handling connections to external exchanges, providing both market data (and potentially orderbook data) and execution channels via their respective REST and websocket integrations.
- Order management acts as an intermediary between strategy commands and exchange API calls.
- Utility classes assist in time scheduling, error management, and overall flow control.

##### Architectural Patterns and Design Principles
- Modular Design: Clear separations between data ingestion, strategy execution, deployment, and exchange abstraction.
- Interface/Abstraction Pattern: The use of abstract base classes in the exchanges directory allows for consistent behavior across different exchange implementations.
- Separation of Concerns: Each main functionality (backtesting, live trading, data management, order handling) is organized into its own module.
- Extensibility: The design easily supports adding new exchanges or trading strategies, as seen by the broad set of interfaces and template files.
- Environment-based Operation: A single line switch within model execution toggles between backtesting and live trading, emphasizing a dynamic configuration between simulation and live environments.

##### Technologies, Frameworks, and Tools
- Python as the core language, with compatibility from Python 3.7 to 3.10.
- CLI and API-based deployments (visible in blankly/deployment).
- Integration with external exchange APIs and websocket feeds.
- Testing with pytest and CI/CD workflows configured in .github/workflows.
- Data handling through custom file readers and event processors (e.g., JsonEventReader).

– Data Module → Strategy Module (data flow for indicators and events)
– Strategy Module → Order Management (trade instructions)
– Order Management → Exchange Interfaces (API calls for orders)
– Deployment Module → Core Engine (CLI/API triggers to initiate live/backtest runs)
- Optionally, include side notes on configuration files and environmental variables that facilitate mode switching.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Components
    deployment["Deployment/CLI"]:::deployment
    dataIn["Data Ingestion & Reader"]:::data
    exchanges["Exchange Interfaces & Managers"]:::exchange
    indicators["Indicators"]:::metrics
    metrics["Metrics"]:::metrics
    utils["Utilities"]:::utility

    %% Frameworks Subgraph
    subgraph "Frameworks"
        %% Model Framework
        subgraph "Model Framework"
            modelCore["Model (Backtesting & Simulation)"]:::core
        end

        %% Strategy Framework
        subgraph "Strategy Framework"
            futuresStrat["Futures Strategy"]:::core
            stratState["Strategy State"]:::core
            orderMod["Order Module"]:::core
        end

        %% Screener Framework
        subgraph "Screener Framework"
            screenerCore["Screener Core"]:::core
            screenerRunner["Screener Runner"]:::core
            screenerState["Screener State"]:::core
        end
    end

    %% Data flows from Data Ingestion to all Framework components
    dataIn -->|"marketData"| modelCore
    dataIn -->|"marketData"| futuresStrat
    dataIn -->|"marketData"| screenerCore

    %% Interactions within Frameworks
    modelCore -->|"simulation"| futuresStrat
    screenerCore -->|"tradeSignal"| futuresStrat

    %% Strategy sends orders to Exchange Interfaces
    orderMod -->|"orderExec"| exchanges

    %% Deployment/CLI initializes and supports exchange interaction
    deployment -->|"initAPI"| exchanges

    %% Indicators and Metrics feed into Screener to enhance decision-making
    indicators -->|"techIndicators"| screenerCore
    metrics -->|"perfMetrics"| screenerRunner

    %% Utility functions support core frameworks
    modelCore ---|"util"| utils
    futuresStrat ---|"util"| utils
    screenerCore ---|"util"| utils

    %% Click Events
    click deployment "https://github.com/blankly-finance/blankly/tree/main/blankly/deployment"
    click dataIn "https://github.com/blankly-finance/blankly/tree/main/blankly/data"
    click exchanges "https://github.com/blankly-finance/blankly/tree/main/blankly/exchanges"
    click modelCore "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/model/model.py"
    click futuresStrat "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/strategy/futures_strategy.py"
    click stratState "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/strategy/strategy_state.py"
    click orderMod "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/strategy/order.py"
    click screenerCore "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/screener/screener.py"
    click screenerRunner "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/screener/screener_runner.py"
    click screenerState "https://github.com/blankly-finance/blankly/blob/main/blankly/frameworks/screener/screener_state.py"
    click indicators "https://github.com/blankly-finance/blankly/tree/main/blankly/indicators"
    click metrics "https://github.com/blankly-finance/blankly/tree/main/blankly/metrics"
    click utils "https://github.com/blankly-finance/blankly/tree/main/blankly/utils"

    %% Styles
    classDef deployment fill:#FAD7A0,stroke:#000,stroke-width:2px;
    classDef data fill:#A2D9CE,stroke:#000,stroke-width:2px;
    classDef exchange fill:#F5B7B1,stroke:#000,stroke-width:2px;
    classDef core fill:#C39BD3,stroke:#000,stroke-width:2px;
    classDef metrics fill:#F7DC6F,stroke:#000,stroke-width:2px;
    classDef utility fill:#D5F5E3,stroke:#000,stroke-width:2px;
```
