# vnpy/vnpy_ctastrategy architecture

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

- Interactive diagram: https://gitdiagram.com/vnpy/vnpy_ctastrategy
- Repository: https://github.com/vnpy/vnpy_ctastrategy

## Overview

##### Project type and purpose
- This is a Python-based plugin module (“vnpy_ctastrategy”) for the VeighNa quant-trading framework, focused on CTA (Commodity Trading Advisor) strategies.
- Its functions span code development, historical backtesting, parameter optimization, and live automated trading of single-instrument CTA strategies.

##### File structure
- Top-level config & meta:
- pyproject.toml (packaging/build)
- README.md, LICENSE, CHANGELOG, GitHub workflow (CI)
- Core package “vnpy_ctastrategy”:
- base.py (strategy interfaces & data models)
- engine.py (runtime engine / scheduler)
- backtesting.py (historical simulation engine)
- template.py (boilerplate code generator)
- ui/ (widgets for parameter input & session rollover)
- locale/ (i18n resources & build hooks)
- strategies/ (concrete strategy implementations)
- Patterns: plugin architecture, observer/event callbacks, MVC elements in UI, separation of engine vs. strategy logic.

##### README
- Confirms full lifecycle: code → backtest → optimize → live trade
- Targets VeighNa Studio v4.0+
- Installs via pip; no external microservices

##### Components
a. Main components
- VeighNa Studio Host (core framework)
- CTA-Strategy Plugin Loader
- Strategy Engine
- Backtesting Module
- Strategy Implementations (strategies/*.py)
- UI Layer (widgets & rollover panels)
- Parameter Optimizer (optional)
- Localization Module
- External Data & Trading APIs (market data feed, order gateway)
b. Relationships & interactions
1. Host loads plugin via entry points defined in pyproject.toml
2. Engine dispatches market events (ticks/bars) to active Strategy instances
3. Strategies emit orders → Engine routes to API
4. Backtesting module injects historical data → Engine & Strategies for simulation
5. UI widgets bind to Engine/Strategy models for user input & real-time metrics
6. Locale loader internationalizes UI strings
c. Architectural patterns & principles
- Plugin architecture: decoupled module loaded at runtime
- Observer/Event Bus: engine raises events (on_tick, on_bar, on_order)
- Strategy Base Class: enforces lifecycle methods (init, start, stop, on_x)
- MVC for UI: widgets observe model (engine/strategy state)
- Single Responsibility: backtesting separated from live engine
d. Key technologies/libraries
- Python 3.10–3.13
- VN.py (VeighNa) core APIs for market data and order routing
- gettext for localization
- pytest or built-in tests (if present)

##### Detailed capture of essential architecture
- Event loop in engine.py driving both live and simulation modes
- Locale build hook feeding into UI strings
- Where template.py can generate new strategy stubs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Entities
    Host["VeighNa Studio Host"]:::external

    %% Plugin Boundary
    subgraph "Plugin Loader"
        Loader["CTA-Strategy Plugin Loader"]:::core
    end

    %% Core Plugin Components
    subgraph "vnpy_ctastrategy Package"
        direction TB
        Base["Strategy Base Class"]:::core
        Engine["Strategy Engine"]:::core
        Backtest["Backtesting Module"]:::core
        Template["Template Generator"]:::core
        subgraph "Strategy Implementations" 
            direction TB
            ATR["ATR RSI Strategy"]:::core
            BOLL["Boll Channel Strategy"]:::core
            DMA["Double MA Strategy"]:::core
            DUAL["Dual Thrust Strategy"]:::core
            KELT["King Keltner Strategy"]:::core
            MS["Multi Signal Strategy"]:::core
            MTF["Multi Timeframe Strategy"]:::core
            TURTLE["Turtle Signal Strategy"]:::core
            TEST["Test Strategy"]:::core
        end
        subgraph "UI Layer"
            direction TB
            Widget["widget.py"]:::ui
            Rollover["rollover.py"]:::ui
        end
        subgraph "Localization Module"
            direction TB
            Hook["build_hook.py"]:::core
            POT["vnpy_ctastrategy.pot"]:::core
            PO["en/LC_MESSAGES/vnpy_ctastrategy.po"]:::core
            GenMO["generate_mo.bat"]:::core
            GenPOT["generate_pot.bat"]:::core
        end
        Optimizer["Parameter Optimizer"]:::optional
    end

    %% External Systems
    Market["Market Data Feed"]:::external
    Gateway["Order Gateway"]:::external

    %% Connections
    Host -->|loads via entry points| Loader
    Loader -->|imports| Base
    Loader -->|starts| Engine
    Engine -->|dispatches events| Base
    Engine -->|schedules| Template
    Backtest -->|injects historical data| Engine
    Engine -->|routes orders| Gateway
    Market -->|live ticks/bars| Engine
    Base -->|inheritance| ATR & BOLL & DMA & DUAL & KELT & MS & MTF & TURTLE & TEST
    ATR & BOLL & DMA & DUAL & KELT & MS & MTF & TURTLE & TEST -->|emit orders| Engine
    Widget -->|binds models| Engine
    Widget -->|binds models| Base
    Rollover -->|session rollover| Engine
    Hook -->|internationalizes| Widget & Rollover
    Optimizer -. optional .-> Backtest

    %% Click Events
    click Loader "https://github.com/vnpy/vnpy_ctastrategy/blob/main/pyproject.toml"
    click Base "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/base.py"
    click Engine "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/engine.py"
    click Backtest "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/backtesting.py"
    click Template "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/template.py"
    click ATR "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/atr_rsi_strategy.py"
    click BOLL "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/boll_channel_strategy.py"
    click DMA "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/double_ma_strategy.py"
    click DUAL "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/dual_thrust_strategy.py"
    click KELT "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/king_keltner_strategy.py"
    click MS "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/multi_signal_strategy.py"
    click MTF "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/multi_timeframe_strategy.py"
    click TURTLE "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/turtle_signal_strategy.py"
    click TEST "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/strategies/test_strategy.py"
    click Widget "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/ui/widget.py"
    click Rollover "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/ui/rollover.py"
    click Hook "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/locale/build_hook.py"
    click POT "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/locale/vnpy_ctastrategy.pot"
    click PO "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/locale/en/LC_MESSAGES/vnpy_ctastrategy.po"
    click GenMO "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/locale/generate_mo.bat"
    click GenPOT "https://github.com/vnpy/vnpy_ctastrategy/blob/main/vnpy_ctastrategy/locale/generate_pot.bat"
    click Loader "https://github.com/vnpy/vnpy_ctastrategy/blob/main/pyproject.toml"
    click CI "https://github.com/vnpy/vnpy_ctastrategy/blob/main/.github/workflows/pythonapp.yml"

    %% Styles
    classDef core fill:#d0e6f8,stroke:#0366d6,stroke-width:1px;
    classDef external fill:#e2f0d9,stroke:#22863a,stroke-width:1px;
    classDef ui fill:#ffe4b5,stroke:#d97706,stroke-width:1px;
    classDef optional stroke-dasharray: 5 5,fill:#f0f0f0,stroke:#6a737d,stroke-width:1px;
```
