# coding-kitties/investing-algorithm-framework architecture

> Architecture diagram of the GitHub repository coding-kitties/investing-algorithm-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/coding-kitties/investing-algorithm-framework
- Repository: https://github.com/coding-kitties/investing-algorithm-framework

## Overview

##### Main components
- Application/Entry Point: Include elements like the “create_app” script and the overall application orchestrator found in investing_algorithm_framework/app. This component handles initialization, configuration, and running of algorithms.
- Domain Layer: Represent the core business logic. This includes the models (orders, portfolios, trades, positions, strategies, etc.) and domain services that define trading, backtesting, performance metrics, and configuration (see directories such as investing_algorithm_framework/domain/models and domain/services).
- Data Sources and Market Integration: Show the market data source integrations (OHLCV and ticker data providers via ccxt, CSV, Pandas/Polars integration), abstracted by market service components. These are crucial for obtaining real-time and historical market data.
- Infrastructure Layer: Add components for persistence and external integration. This includes:
- Database persistence (via sqlite and SQLAlchemy in infrastructure/database).
- Repositories for orders, portfolios, positions, and trades in infrastructure/repositories.
- External integrations (exchange interfaces via ccxt, upcoming support for Azure Functions, AWS Lambda, etc.).
- API & Web Layer: Show the web API and controllers (located under app/web/controllers) that expose RESTful endpoints for managing the bot, submitting orders, retrieving portfolio snapshots, and evaluating backtests.
- Command Line Interface (CLI): Represent how the CLI utilities (in investing_algorithm_framework/cli) are used for tasks like initialization, deployment, and backtesting.
- Testing/Examples: Although not part of production, include a note about how examples and tests are organized. These help illustrate usage scenarios and serve as integration tests to validate the architecture.

##### Relationships and interactions
- The Application Layer (created through create_app and orchestrated by app.py) initializes the system and wires up the domain, services, and infrastructure.
- The Domain components (models and service logic) encapsulate the business rules and data structures and interact with persistence repositories for saving orders, positions, etc.
- The Infrastructure layer acts as a bridge by implementing concrete repository classes and adapters that connect domain objects to external systems (like databases or market data sources).
- The API and CLI layers expose entry points which ultimately invoke domain logic and service operations.
- Market Data Sources provide data to strategies in a periodic or event-driven manner – the strategies (decorated and registered within the algorithm component) leverage data from both live feeds and backtest datasets.
- External integrations appear as dependencies such as ccxt for exchange connectivity, and planned integrations (Azure Functions, AWS Lambda) for different deployment modes.

##### Architectural patterns and design principles
- Layered Architecture: Separate components into presentation (web API/CLI), application, domain (business model, strategy definitions), and infrastructure (repositories, external services) layers.
- Separation of Concerns: Distinct directories (app, domain, infrastructure, services, cli) emphasize clear boundaries so that trading logic does not mix with persistence or external integrations.
- Extensibility: The framework’s design (with pluggable data providers, market credentials, and strategy registration via decorators) supports adding or replacing components without changing core logic.
- Testability: A rich set of unit and integration tests (in the tests directory) demonstrates the importance of ensuring that each component is independently verifiable.

##### Technologies, frameworks, and libraries
- Python 3.9+ as the core language.
- ccxt for exchange connectivity.
- SQLite (using SQLAlchemy for ORM) for persistence.
- Polars and Pandas for data processing.
- CLI and possibly Flask/FastAPI (or similar) for the web API (judging by the “controllers” in app/web).
- Environment configuration handled via dotenv.

- Areas that are planned or under development (for instance, built-in WebUI, Telegram integration, AWS Lambda support).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        WebControllers["Web API Controllers"]:::presentation
        WebApp["Web API Initialization"]:::presentation
        CLI["Command Line Tools"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        CreateApp["Application Initialization (create_app)"]:::application
        AppOrchestrator["Application Orchestrator (app.py)"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        DomainModels["Domain Models (Orders, Portfolios, Trades)"]:::domain
        DomainServices["Domain Services (Trading Logic)"]:::domain
    end

    %% Market Data Integration
    subgraph "Market Data Integration"
        MarketIntegration["Market Data Sources (OHLCV, Ticker)"]:::data
        MarketDataService["Market Data Service"]:::data
    end

    %% Services Layer
    subgraph "Services Layer"
        BacktestService["Backtesting Service"]:::services
        OrderService["Order Execution Service"]:::services
        PortfolioService["Portfolio Sync Service"]:::services
        TradeService["Trade Service"]:::services
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        SQLAlchemyDB["Persistence (SQLAlchemy & SQLite)"]:::infrastructure
        Repositories["Repositories (Orders, Portfolios, Positions, Trades)"]:::infrastructure
    end

    %% Connections from Presentation to Application
    WebControllers -->|"triggers"| CreateApp
    CLI -->|"triggers"| CreateApp
    WebApp -->|"configures"| CreateApp

    %% Application Layer wires to Domain and Services
    CreateApp -->|"initializes"| DomainModels
    CreateApp -->|"initializes"| DomainServices
    CreateApp -->|"initializes"| BacktestService
    CreateApp -->|"initializes"| OrderService
    CreateApp -->|"initializes"| PortfolioService
    CreateApp -->|"initializes"| TradeService

    %% Domain connections
    DomainModels -->|"persists to"| SQLAlchemyDB
    DomainModels -->|"persists to"| Repositories
    DomainServices -->|"uses"| MarketDataService

    %% Market Data Integration connections
    MarketDataService -->|"fetches from"| MarketIntegration

    %% Services to Infrastructure
    BacktestService -->|"stores results in"| SQLAlchemyDB
    OrderService -->|"updates"| Repositories
    PortfolioService -->|"updates"| Repositories
    TradeService -->|"updates"| Repositories

    %% Class Definitions (Colors)
    classDef presentation fill:#f9e79f,stroke:#333,stroke-width:1px;
    classDef application fill:#f7dc6f,stroke:#333,stroke-width:1px;
    classDef domain fill:#a9dfbf,stroke:#333,stroke-width:1px;
    classDef services fill:#aed6f1,stroke:#333,stroke-width:1px;
    classDef infrastructure fill:#d2b4de,stroke:#333,stroke-width:1px;
    classDef data fill:#f5b7b1,stroke:#333,stroke-width:1px;

    %% Click Events for Application Layer
    click CreateApp "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/create_app.py"
    click AppOrchestrator "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/app/app.py"

    %% Click Events for Domain Layer
    click DomainModels "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/domain/models"
    click DomainServices "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/domain/services"

    %% Click Events for Market Data Integration
    click MarketIntegration "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/infrastructure/models/market_data_sources"
    click MarketDataService "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/domain/services/market_data_sources.py"

    %% Click Events for Infrastructure Layer
    click SQLAlchemyDB "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/infrastructure/database/sql_alchemy.py"
    click Repositories "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/infrastructure/repositories"

    %% Click Events for Services Layer
    click BacktestService "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/services/backtesting/backtest_service.py"
    click OrderService "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/services/order_service"
    click PortfolioService "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/services/portfolios"
    click TradeService "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/services/trade_service"

    %% Click Events for API & Web Layer
    click WebControllers "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/app/web/controllers"
    click WebApp "https://github.com/coding-kitties/investing-algorithm-framework/blob/main/investing_algorithm_framework/app/web/create_app.py"

    %% Click Event for CLI
    click CLI "https://github.com/coding-kitties/investing-algorithm-framework/tree/main/investing_algorithm_framework/cli"
```
