# gbeced/basana architecture

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

- Interactive diagram: https://gitdiagram.com/gbeced/basana
- Repository: https://github.com/gbeced/basana

## Overview

##### Main Components Identification

The system should be divided into these major components:

a. Core Framework Layer
- Event Dispatcher System
- WebSocket Management
- Configuration Management
- Data Models (Bars, Events, Pairs)

b. Backtesting Engine
- Exchange Simulation
- Account Management
- Order Management
- Lending/Margin Trading
- Charts/Visualization

c. External Exchange Integration
- Binance Integration
- Bitstamp Integration
- Yahoo Finance Integration
- Common Exchange Components

**┌─ Core Framework Layer ─────────────────────┐**
- Event Dispatcher                           │
- WebSocket Handler                          │
- Configuration Management                   │
- ┬───────────────────────┘

**┌─ Backtesting ─────┼─── External Exchanges ─┐**

- Exchange Sim ◄────┼────► Binance          │
- Account Manager   │    ├ Spot             │
- Order Manager     │    ├ Margin           │
- Lending System    │    └ Cross Margin     │

- Charts/Viz        │    Bitstamp           │
- Spot             │
- Order Book       │
- ┼────────────────────────┘

**┌─ Data Sources ────┼────────────────────────┐**
- CSV Handlers      │                        │
- Trading Signals   │                        │
- Market Data       │                        │
- ┴────────────────────────┘

##### Key Architectural Patterns to Highlight

a. Event-Driven Architecture
- Event flow between components
- Central dispatcher role
- Async communication paths

b. Plugin Architecture
- How external exchanges plug into the core
- Demonstrate common interface implementations
- Extension points

c. Data Flow
- Market data ingestion paths
- Order execution flow
- Backtesting simulation flow

##### Important Implementation Details

- Separation between spot and margin trading
- WebSocket connections for real-time data
- Where configuration management applies
- Points where technical indicators can be plugged in

##### Integration Points

- External exchange APIs
- Data source connectors
- Strategy implementation hooks
- Visualization outputs

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Core Framework Layer
    subgraph Core
        EventDispatcher["Event Dispatcher"]
        WebSocket["WebSocket Handler"]
        Config["Configuration Management"]
        
        subgraph DataModels["Data Models"]
            Bar["Bar Model"]
            Event["Event Model"]
            Pair["Pair Model"]
        end
    end

    %% Backtesting Layer
    subgraph Backtesting
        ExchangeSim["Exchange Simulation"]
        AccountMgr["Account Manager"]
        OrderMgr["Order Manager"]
        LendingSystem["Lending System"]
        Charts["Charts/Visualization"]
    end

    %% External Exchanges Layer
    subgraph Exchanges
        subgraph Binance
            BinanceSpot["Spot Trading"]
            BinanceMargin["Margin Trading"]
            BinanceCrossMargin["Cross Margin"]
        end
        
        subgraph Bitstamp
            BitstampSpot["Spot Trading"]
            BitstampOrderBook["Order Book"]
        end
        
        YahooFinance["Yahoo Finance"]
    end

    %% Data Sources Layer
    subgraph DataSources
        CSVHandler["CSV Handler"]
        TradingSignals["Trading Signals"]
    end

    %% Relationships
    EventDispatcher --> WebSocket
    EventDispatcher --> DataModels
    Config --> Core
    
    EventDispatcher --> ExchangeSim
    ExchangeSim --> AccountMgr
    ExchangeSim --> OrderMgr
    ExchangeSim --> LendingSystem
    OrderMgr --> Charts
    
    WebSocket --> Binance
    WebSocket --> Bitstamp
    
    CSVHandler --> EventDispatcher
    TradingSignals --> EventDispatcher

    %% Click Events
    click EventDispatcher "https://github.com/gbeced/basana/blob/develop/basana/core/dispatcher.py"
    click WebSocket "https://github.com/gbeced/basana/blob/develop/basana/core/websockets.py"
    click Config "https://github.com/gbeced/basana/blob/develop/basana/core/config.py"
    click Bar "https://github.com/gbeced/basana/blob/develop/basana/core/bar.py"
    click Event "https://github.com/gbeced/basana/blob/develop/basana/core/event.py"
    click Pair "https://github.com/gbeced/basana/blob/develop/basana/core/pair.py"
    click ExchangeSim "https://github.com/gbeced/basana/blob/develop/basana/backtesting/exchange.py"
    click AccountMgr "https://github.com/gbeced/basana/blob/develop/basana/backtesting/account_balances.py"
    click OrderMgr "https://github.com/gbeced/basana/blob/develop/basana/backtesting/order_mgr.py"
    click LendingSystem "https://github.com/gbeced/basana/tree/develop/basana/backtesting/lending/"
    click Charts "https://github.com/gbeced/basana/blob/develop/basana/backtesting/charts.py"
    click BinanceSpot "https://github.com/gbeced/basana/blob/develop/basana/external/binance/spot.py"
    click BinanceMargin "https://github.com/gbeced/basana/blob/develop/basana/external/binance/margin.py"
    click BinanceCrossMargin "https://github.com/gbeced/basana/blob/develop/basana/external/binance/cross_margin.py"
    click BitstampSpot "https://github.com/gbeced/basana/blob/develop/basana/external/bitstamp/exchange.py"
    click BitstampOrderBook "https://github.com/gbeced/basana/blob/develop/basana/external/bitstamp/order_book.py"
    click YahooFinance "https://github.com/gbeced/basana/tree/develop/basana/external/yahoo/"
    click CSVHandler "https://github.com/gbeced/basana/blob/develop/basana/core/event_sources/csv.py"
    click TradingSignals "https://github.com/gbeced/basana/blob/develop/basana/core/event_sources/trading_signal.py"

    %% Styling
    classDef core fill:#a8d1ff,stroke:#333,stroke-width:2px
    classDef backtesting fill:#ffd7a8,stroke:#333,stroke-width:2px
    classDef exchange fill:#a8ffc9,stroke:#333,stroke-width:2px
    classDef datasource fill:#e6e6e6,stroke:#333,stroke-width:2px

    class EventDispatcher,WebSocket,Config,DataModels,Bar,Event,Pair core
    class ExchangeSim,AccountMgr,OrderMgr,LendingSystem,Charts backtesting
    class BinanceSpot,BinanceMargin,BinanceCrossMargin,BitstampSpot,BitstampOrderBook,YahooFinance exchange
    class CSVHandler,TradingSignals datasource
```
