# ntorm1/atlas architecture

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

- Interactive diagram: https://gitdiagram.com/ntorm1/atlas
- Repository: https://github.com/ntorm1/atlas

## Overview

##### Project Type and Purpose
- Atlas is a high-performance, modular algorithmic trading backtesting library written in C++20.
- It exposes a Python API (AtlasPy, built with pybind11) and a Qt-based GUI (AtlasX).
- It is intended for large-scale backtests: ingesting CSV/HDF5 market data, composing strategy ASTs, running simulations, and collecting performance metrics.

##### High-Level Architectural Components
A. Core C++ Runtime (“Atlas”)
- Built as a Visual Studio DLL (Atlas.sln, Atlas.vcxproj).
- Contains the bulk of the logic, organized into “modules/”:
- ast (AST node definitions)
- exchange (data ingestion & exchange view)
- hydra (runtime orchestration)
- model (ML models: LinearRegression, XGBoost, Torch)
- standard (utilities, serialization, stats, time)
- strategy (allocation, meta-strategy, tracing, measurement)
- Public headers in “include/” expose core types and macros.
- Links to external libraries: Eigen, H5CPP, xgboost, unordered_dense, expected.hpp.

B. Python Binding Layer (“AtlasPy”)
- Built as a pybind11 wrapper (AtlasPy/AtlasPy.vcxproj).
- Exposes C++ functionality through Python modules: core (Hydra, Portfolio, Strategy), ast, parser, strategy, logging.
- Test suite under AtlasPy/tests calls into the Python API to drive the backtester.

C. GUI Application (“AtlasX”)
- Qt5/6-based desktop application (AtlasX/).
- Uses QScintilla, Advanced Docking System.
- Implements a graphical strategy editor, tree view of AST, and real-time tracing via the C++ core.

D. Test Harnesses
- AtlasTest: a C++ unit-test project verifying core internals (AST, exchange, modules).
- AtlasPy/tests: Python-level integration tests driving the backtester end-to-end with sample data.

E. Data Sources & Formats
- .csv and .h5 files ingested by ExchangeIO under modules/exchange.
- Contains sample datasets under AtlasPy/tests/files.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core C++ Runtime Layer
    subgraph "Core C++ Runtime" 
        direction TB
        AtlasCoreDLL["Atlas Core DLL"]:::core
        subgraph "Public Headers"
            direction TB
            PH1["AtlasFeature.hpp"]:::core
            PH2["AtlasMacros.hpp"]:::core
            PH3["AtlasPointer.hpp"]:::core
            PH4["AtlasStruct.hpp"]:::core
            PH5["pch.h"]:::core
        end
        subgraph "Modules"
            direction TB
            AST["AST Module"]:::core
            EXCH["Exchange Module"]:::core
            HYDRA["Hydra Module"]:::core
            MODEL["Model Module"]:::core
            STD["Standard Utils Module"]:::core
            STRAT["Strategy Module"]:::core
        end
    end

    %% Python Binding Layer
    subgraph "Python Binding (AtlasPy)" 
        direction TB
        PyProj["AtlasPy.vcxproj"]:::binding
        PyPkg["atlas_py Package"]:::binding
        PySrc["Source Bindings"]:::binding
    end

    %% GUI Layer
    subgraph "GUI Application (AtlasX)"
        direction TB
        GUIProj["AtlasX.vcxproj"]:::ui
        GUIEntry["main.cpp"]:::ui
        GUIInclude["include/"]:::ui
        GUISrc["src/"]:::ui
        GUIExt["external/"]:::ui
        GUIStyles["styles/"]:::ui
    end

    %% Data Sources
    CSV["CSV Files"]:::data
    HDF5["HDF5 Files"]:::data

    %% External Libraries
    subgraph "External Dependencies"
        direction TB
        EIGEN["Eigen"]:::external
        H5CPP["H5CPP"]:::external
        XGB["XGBoost"]:::external
        TORCH["LibTorch"]:::external
        UNORD["unordered_dense.h"]:::external
        EXPECT["expected.hpp"]:::external
    end

    %% Test Suites
    subgraph Tests
        direction TB
        CPPTest["AtlasTest C++ Tests"]:::data
        PyTest["AtlasPy Python Tests"]:::data
    end

    %% Data Flow & Relationships
    CSV -->|ingest| EXCH
    HDF5 -->|ingest| EXCH
    EXCH -->|provides data| HYDRA
    HYDRA -->|builds graph| STRAT
    HYDRA -->|uses| STD
    HYDRA -->|uses| MODEL
    STRAT -->|evaluates| STD
    STRAT -->|traces| AtlasCoreDLL

    PyProj -->|binds to| AtlasCoreDLL
    PyPkg -->|imports| PyProj
    PySrc -->|wraps modules| AST
    PySrc -->|wraps modules| EXCH
    PySrc -->|wraps modules| HYDRA

    GUIProj -->|links to| AtlasCoreDLL
    GUIEntry -->|calls core| AtlasCoreDLL
    GUIInclude -->|defines UI| GUIEntry
    GUISrc -->|implements editor| GUIEntry
    GUIExt -->|provides widgets| GUIEntry
    GUIStyles -->|themes UI| GUIEntry

    CPPTest -->|tests| AST
    CPPTest -->|tests| EXCH
    CPPTest -->|tests| HYDRA
    PyTest -->|tests| PyProj

    %% External deps
    AtlasCoreDLL -->|links| EIGEN
    AtlasCoreDLL -->|links| H5CPP
    AtlasCoreDLL -->|links| XGB
    AtlasCoreDLL -->|links| TORCH
    AtlasCoreDLL -->|includes| UNORD
    AtlasCoreDLL -->|includes| EXPECT

    %% Click Events
    click AtlasCoreDLL "https://github.com/ntorm1/atlas/blob/main/Atlas.sln"
    click PH1 "https://github.com/ntorm1/atlas/blob/main/include/AtlasFeature.hpp"
    click PH2 "https://github.com/ntorm1/atlas/blob/main/include/AtlasMacros.hpp"
    click PH3 "https://github.com/ntorm1/atlas/blob/main/include/AtlasPointer.hpp"
    click PH4 "https://github.com/ntorm1/atlas/blob/main/include/AtlasStruct.hpp"
    click PH5 "https://github.com/ntorm1/atlas/blob/main/include/pch.h"
    click AST "https://github.com/ntorm1/atlas/tree/main/modules/ast"
    click EXCH "https://github.com/ntorm1/atlas/tree/main/modules/exchange"
    click HYDRA "https://github.com/ntorm1/atlas/tree/main/modules/hydra"
    click MODEL "https://github.com/ntorm1/atlas/tree/main/modules/model"
    click STD "https://github.com/ntorm1/atlas/tree/main/modules/standard"
    click STRAT "https://github.com/ntorm1/atlas/tree/main/modules/strategy"
    click PyProj "https://github.com/ntorm1/atlas/blob/main/AtlasPy/AtlasPy.vcxproj"
    click PyPkg "https://github.com/ntorm1/atlas/tree/main/AtlasPy/atlas_py"
    click PySrc "https://github.com/ntorm1/atlas/tree/main/AtlasPy/src"
    click GUIProj "https://github.com/ntorm1/atlas/blob/main/AtlasX/AtlasX.vcxproj"
    click GUIEntry "https://github.com/ntorm1/atlas/blob/main/AtlasX/main.cpp"
    click GUIInclude "https://github.com/ntorm1/atlas/tree/main/AtlasX/include"
    click GUISrc "https://github.com/ntorm1/atlas/tree/main/AtlasX/src"
    click GUIExt "https://github.com/ntorm1/atlas/tree/main/AtlasX/external"
    click GUIStyles "https://github.com/ntorm1/atlas/tree/main/AtlasX/styles"
    click CPPTest "https://github.com/ntorm1/atlas/blob/main/AtlasTest/AtlasTest.vcxproj"
    click PyTest "https://github.com/ntorm1/atlas/tree/main/AtlasPy/tests"
    click CSV "https://github.com/ntorm1/atlas/tree/main/AtlasPy/tests/files"
    click HDF5 "https://github.com/ntorm1/atlas/tree/main/AtlasPy/tests/files"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef binding fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef ui fill:#A9DFBF,stroke:#145A32,color:#0B5345
    classDef external fill:#F2F3F4,stroke:#515A5A,color:#515A5A
    classDef data fill:#FCF3CF,stroke:#7D6608,color:#7D6608
```
