# vnpy/vnpy_chartwizard architecture

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

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

## Overview

1. **What this repository is**
   - `vnpy_chartwizard` is a VeighNa add-on focused on **K-line / candlestick chart display**.
   - It is not a trading strategy or backend service; it is a **charting module** meant to run inside the VeighNa ecosystem, especially VeighNa Studio.

2. **Primary responsibility**
   - The module shows **historical and live minute-level bars**.
   - The README makes the key constraint explicit: it currently supports **1-minute K-line data only**, and the newest bar is refreshed from **tick-level updates**.

3. **Core architectural split**
   - The codebase is intentionally small and centered around two functional layers:
     - `vnpy_chartwizard/engine.py` for the **domain/runtime logic**
     - `vnpy_chartwizard/ui/widget.py` for the **presentation layer**
   - This separation is the main boundary to draw in an architecture diagram.

4. **Engine layer**
   - `engine.py` is the logical core that likely manages chart data, data updates, and coordination between the host framework and the UI.
   - In diagram terms, this is where incoming market data is transformed into chart-ready bar state.

5. **UI layer**
   - `ui/widget.py` is the user-facing widget that renders the chart and exposes the interactive display.
   - The UI is a separate package subfolder (`vnpy_chartwizard/ui`), reinforcing that rendering concerns are isolated from the engine.

6. **Data flow**
   - The expected flow is:
     - **VeighNa market data feed / host app**
     - -> **ChartWizard engine**
     - -> **UI widget**
     - -> **user view**
   - Historical minute bars populate the chart, then live ticks update the current bar in place.

7. **Integration boundary with VeighNa**
   - The repository depends on the surrounding **VeighNa framework** and is meant to be installed into a compatible VeighNa Studio environment.
   - This means the package behaves like a plugin/module rather than a standalone application with its own independent backend.

8. **Entry point / runnable script**
   - `script/run.py` suggests a local launch or demo entry point for starting the chart wizard outside a full application context.
   - In a diagram, this is the executable path used for manual startup or development testing.

9. **Packaging and distribution**
   - `pyproject.toml` indicates modern Python packaging and installation via `pip`.
   - The README shows both source install and pip install workflows, so distribution is package-based rather than container-based or service-based.

10. **Platform and runtime constraints**
   - The project targets **Python 3.10–3.13** and is advertised as cross-platform: **Windows, Linux, macOS**.
   - That matters architecturally because the UI layer and packaging must remain desktop-friendly and portable.

11. **What is not in scope**
   - There is no evidence here of persistence, database storage, network APIs, order routing, or multi-service orchestration.
   - The module’s scope is narrowly chart visualization and live bar updating.

12. **Repo structure summary for a diagram**
   - Draw this as a small plugin-style package with:
     - a **core engine**
     - a **UI widget**
     - a **script entry point**
     - integration into the **VeighNa host environment**
   - The main external dependency boundary is the **VeighNa framework**, not an external web service or database.

Main entry points: [`vnpy_chartwizard/engine.py`](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/engine.py) (Engine), [`vnpy_chartwizard/__init__.py`](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/__init__.py) (Package Init), [`vnpy_chartwizard/ui/widget.py`](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/widget.py) (Chart Widget), [`vnpy_chartwizard/ui/__init__.py`](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/__init__.py) (UI Package)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_host["VeighNa Host"]
  node_veighna_host["VeighNa Studio<br/>framework host"]
  node_market_feed(("Market Feed<br/>ticks/bars"))
  node_user_view(("Trader View<br/>desktop UI"))
end

subgraph group_chartwizard["ChartWizard Package"]
  node_package_root["Package Init<br/>package boundary<br/>[__init__.py]"]
  node_engine["Engine<br/>chart state core<br/>[engine.py]"]
  node_ui_pkg["UI Package<br/>ui namespace<br/>[__init__.py]"]
  node_widget["Chart Widget<br/>render widget<br/>[widget.py]"]
end

subgraph group_delivery["Delivery"]
  node_run_script["Run Script<br/>launcher<br/>[run.py]"]
  node_pyproject["pyproject<br/>package config<br/>[pyproject.toml]"]
end

node_market_feed -->|"bars/ticks"| node_engine
node_run_script -->|"launches"| node_engine
node_veighna_host -->|"embeds"| node_engine
node_engine -->|"updates"| node_widget
node_widget -->|"renders"| node_user_view
node_pyproject -.->|"installs"| node_package_root
node_package_root -->|"exposes"| node_engine
node_package_root -->|"contains"| node_ui_pkg
node_ui_pkg -->|"contains"| node_widget
node_veighna_host -.->|"publishes"| node_market_feed

click node_run_script "https://github.com/vnpy/vnpy_chartwizard/blob/main/script/run.py"
click node_pyproject "https://github.com/vnpy/vnpy_chartwizard/blob/main/pyproject.toml"
click node_package_root "https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/__init__.py"
click node_engine "https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/engine.py"
click node_ui_pkg "https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/__init__.py"
click node_widget "https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/widget.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_veighna_host,node_market_feed,node_user_view toneBlue
class node_package_root,node_engine,node_ui_pkg,node_widget toneAmber
class node_run_script,node_pyproject toneMint
```

## Components

### VeighNa Host

External framework and runtime environment that supplies market data and embeds the charting plugin.

- **VeighNa Studio**: framework host · Embedding environment for the plugin and source of market data events.
- **Market Feed**: ticks/bars · Historical minute bars and live ticks consumed by the charting engine.
- **Trader View**: desktop UI · Human-facing chart display rendered by the widget.

### ChartWizard Package

Core package boundary for chart state, rendering, and runtime wiring.

- [Package Init](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/__init__.py): package boundary · Top-level package namespace for the add-on. · `vnpy_chartwizard/__init__.py`
- [Engine](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/engine.py): chart state core · Transforms incoming market data into chart-ready bar state and coordinates updates. · `vnpy_chartwizard/engine.py`
- [UI Package](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/__init__.py): ui namespace · Presentation-layer package grouping the chart widget. · `vnpy_chartwizard/ui/__init__.py`
- [Chart Widget](https://github.com/vnpy/vnpy_chartwizard/blob/main/vnpy_chartwizard/ui/widget.py): render widget · Interactive chart renderer that displays historical bars and refreshes the current bar. · `vnpy_chartwizard/ui/widget.py`

### Delivery

Local startup and packaging entry points.

- [Run Script](https://github.com/vnpy/vnpy_chartwizard/blob/main/script/run.py): launcher · Local/manual entry point used to start the chart wizard outside the full host app. · `script/run.py`
- [pyproject](https://github.com/vnpy/vnpy_chartwizard/blob/main/pyproject.toml): package config · Packaging and installation metadata for pip-based distribution. · `pyproject.toml`

## Connections

- Market Feed → Engine: bars/ticks · Incoming market data is normalized into chart state.
- Run Script → Engine: launches · Local launcher starts the core runtime.
- VeighNa Studio → Engine: embeds · Host environment provides the plugin runtime boundary.
- Engine → Chart Widget: updates · Engine pushes chart-ready state to the UI layer.
- Chart Widget → Trader View: renders · Widget presents the chart to the user.
- pyproject → Package Init: installs · Packaging metadata defines how the add-on is distributed and installed.
- Package Init → Engine: exposes · Top-level package exposes the core engine module.
- Package Init → UI Package: contains · Top-level package includes the UI namespace.
- UI Package → Chart Widget: contains · UI package contains the chart widget implementation.
- VeighNa Studio → Market Feed: publishes · Host framework publishes market data consumed by the plugin.