# roq-trading/roq-algo architecture

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

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

## Overview

##### Project type and purpose
- From the README and file tree, “roq-algo” is a C++ API and reference implementation for algorithmic and high-frequency trading (HFT).
- It provides:
- Interfaces for trading strategies
- Exchange matching simulation
- Simulation reporting
- Reference implementations (arbitrage, matcher, reporter, simulator, strategy, tools)

##### File structure
- Top-level:
- CMakeLists.txt and cmake/ → build system
- /roq/algo → public headers, subdivided by component (arbitrage, matcher, reporter, simulator, strategy, tools)
- src/roq/algo → implementation matching the include layout
- benchmark/ → performance tests
- test/ → unit/integration tests
- scripts/, conda/ → environment and tooling
- Pattern: modular library with layered components and reference executables under src/roq/algo/main.cpp.

##### README for additional insights
- Emphasis on “interfaces” → clear separation between abstract API and concrete implementations.

##### Elements
- Clear labels for all components (use the same names as the headers: “Simulator”, “Matcher”, etc.)
- Green for support/tools (position tracker, time checker)
- Orange for external interfaces (configs, data feeds, outputs)

##### Detailed capture of essential architecture
- Configuration paths (config files → factory → component)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Interfaces
    subgraph "External Interfaces" 
        direction TB
        MDSource["Market Data Source"]:::external
    end

    %% Factories & Configuration
    subgraph "Configuration & Factories"
        direction TB
        FactoryCore["Central Factory"]:::exec
        FactoryArbitrage["Arbitrage Factory"]:::exec
    end

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        subgraph "Strategy Layer"
            direction TB
            StratConfig["Config"]:::core
            StratFactory["Factory"]:::core
            StratType["Type"]:::core
            StratMeta["Meta"]:::core
        end
        subgraph "Order Management"
            direction TB
            OrderCache["Order Cache & Factory"]:::core
        end
        subgraph "Matching Engine"
            direction TB
            MatcherConfig["Config"]:::core
            MatcherFactory["Factory"]:::core
            MatcherType["Type"]:::core
        end
        subgraph "Simulator"
            direction TB
            SimConfig["Config"]:::core
            SimSource["Source"]:::core
        end
        subgraph "Reporter"
            direction TB
            RepFactory["Factory"]:::core
            RepOutput["OutputType"]:::core
            RepSummary["Summary"]:::core
            RepType["Type"]:::core
        end
    end

    %% Tools
    subgraph "Support Tools"
        direction TB
        ToolMarketData["Market Data Tool"]:::support
        ToolPosition["Position Tracker"]:::support
        ToolTime["Time Checker"]:::support
    end

    %% Executables
    subgraph "Executables & Tests"
        direction TB
        MainExec["Main Executable"]:::exec
        Benchmark["Benchmark Harness"]:::exec
        TestSuite["Test Suite"]:::exec
    end

    %% Connections
    MDSource --> StratConfig
    StratConfig --> StratFactory
    StratFactory --> StratType
    StratType --> OrderCache
    OrderCache --> MatcherFactory
    MatcherFactory --> MatcherType
    MatcherType --> SimSource
    SimSource --> RepFactory
    RepFactory --> RepSummary
    RepSummary --> RepOutput
    StratType --> ToolMarketData
    SimSource --> ToolPosition
    RepFactory --> ToolTime
    FactoryCore --> StratFactory
    FactoryCore --> MatcherFactory
    FactoryCore --> RepFactory
    FactoryArbitrage --> FactoryCore
    MainExec --> FactoryCore
    Benchmark --> MainExec
    TestSuite --> MainExec

    %% Click Events
    click MDSource "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/market_data_source.hpp"
    click StratConfig "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/strategy/config.hpp"
    click StratFactory "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/strategy/factory.hpp"
    click StratType "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/strategy/type.hpp"
    click StratMeta "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/strategy/meta.hpp"
    click OrderCache "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/order_cache.hpp"
    click MatcherConfig "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/matcher/config.hpp"
    click MatcherFactory "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/matcher/factory.hpp"
    click MatcherType "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/matcher/type.hpp"
    click SimConfig "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/simulator/config.hpp"
    click SimSource "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/simulator/source.hpp"
    click RepFactory "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/reporter/factory.hpp"
    click RepOutput "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/reporter/output_type.hpp"
    click RepSummary "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/reporter/summary.hpp"
    click RepType "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/reporter/type.hpp"
    click ToolMarketData "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/tools/market_data.hpp"
    click ToolPosition "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/tools/position_tracker.hpp"
    click ToolTime "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/tools/time_checker.hpp"
    click FactoryCore "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/factory.hpp"
    click FactoryArbitrage "https://github.com/roq-trading/roq-algo/blob/master/include/roq/algo/arbitrage/factory.hpp"
    click MainExec "https://github.com/roq-trading/roq-algo/blob/master/src/roq/algo/main.cpp"
    click Benchmark "https://github.com/roq-trading/roq-algo/blob/master/benchmark/main.cpp"
    click TestSuite "https://github.com/roq-trading/roq-algo/blob/master/test/main.cpp"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef support fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef exec fill:#d7ccc8,stroke:#8d6e63,color:#4e342e
```
