# tkfy920/qstock architecture

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

- Interactive diagram: https://gitdiagram.com/tkfy920/qstock
- Repository: https://github.com/tkfy920/qstock

## Overview

##### Project Type and Purpose
- qstock is an open-source Python library designed for financial quantitative research and analysis. Its purpose is to provide a suite of tools for data acquisition from financial markets, visualization (with interactive web-based charts), quantitative backtesting (both vectorized and event-driven), and stock selection analysis.
- Key features include data fetching from public web sources (such as 东方财富网, 同花顺, 新浪财经), financial and macroeconomic data processing, and a robust suite of visualization functions based on libraries like pyecharts.

##### File Structure and Main Components
- At the top level, you see directories representing each major module:
- The “data” directory: Contains modules for retrieving and processing various financial data streams (e.g., fundamental, macro, trade, and news data). Files like fundamental.py, trade.py, and wencai.py show that it gathers information from multiple sources.
- The “plot” directory: Contains visualization routines such as chart_plot.py and data_plot.py, which encapsulate functions for drawing K-line charts, bar charts, heatmaps, and even word clouds.
- The “stock” directory: Focused on stock pool management and selection strategies, including files like stock_pool.py and ths_em_pool.py.
- The “backtest” directory: Provides both vectorized and event-driven backtesting frameworks (notably files like vec_backtest.py, bt_backtest.py, and turtle.py), indicating the two distinct approaches for backtesting.
- The __init__.py files at the root and within each module indicate that these modules are designed to be imported as part of the qstock package.
- Additionally, there are GitHub workflows (.github/workflows/python-publish.yml) for CI/CD, and typical packaging files such as LICENSE and README.md which document usage and deployment instructions.

##### Architectural Principles and Relationships
- The architecture follows a modular design principle, where each major functionality (data access, visualization, stock analysis, and backtesting) is encapsulated in its own package.
- At the center is the qstock package that aggregates these modules so users can seamlessly import and use various functionalities. For example, a user might import qstock and then call qs.get_data(), qs.stock_basics(), or qs.realtime_data() as needed.
- There is a clear separation of concerns:
- The data module is responsible for fetching, cleaning, and preparing raw data from external financial data sources.
- The plot module receives processed data (often in pandas DataFrame formats) and provides visualization outputs—this includes integration with web-based chart rendering libraries (e.g., interactions with pyecharts and instructions about installing node.js and jsdom for web support).
- The stock module deals specifically with stock selection and pool management logic, utilizing both technical indicators and fundamental criteria.
- The backtest module provides two discrete strategies:
· A vectorized backtesting approach using pandas for handling time series.
· An event-driven backtesting approach (as evidenced by file names and function references like “turtle”).
- External dependencies and integration points include:
- Python libraries (pandas, pyecharts, etc.) for data processing and visualization.
- Node.js (and its package jsdom) is required for enhanced web-based visualization components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "qstock Architecture"
        A["Core API (qstock Package)"]:::core
        B["Data Module"]:::module
        C["Plot Module"]:::module
        D["Stock Module"]:::module
        E["Backtest Module"]:::module
    end

    subgraph "External Dependencies"
        Ex1["Data Sources: 东方财富网, 同花顺, 新浪财经"]:::external
        Ex2["Python Libraries: pandas, pyecharts"]:::external
        Ex3["Node.js & jsdom"]:::external
    end

    subgraph "DevOps"
        F["CI/CD Configuration"]:::ci
    end

    Ex1 -->|"fetches"| B
    Ex2 -->|"tools"| B
    Ex2 -->|"visualizes"| C
    Ex3 -->|"supports"| C

    B -->|"provides_data"| D
    B -->|"provides_data"| E
    B -->|"provides_data"| C
    E -->|"backtest_results"| C

    A -->|"aggregates"| B
    A -->|"aggregates"| C
    A -->|"aggregates"| D
    A -->|"aggregates"| E

    F -->|"publishes"| A

    click A "https://github.com/tkfy920/qstock/blob/master/__init__.py"
    click B "https://github.com/tkfy920/qstock/tree/master/data/"
    click C "https://github.com/tkfy920/qstock/tree/master/plot/"
    click D "https://github.com/tkfy920/qstock/tree/master/stock/"
    click E "https://github.com/tkfy920/qstock/tree/master/backtest/"
    click F "https://github.com/tkfy920/qstock/blob/master/.github/workflows/python-publish.yml"

    classDef core fill:#f96,stroke:#333,stroke-width:2px;
    classDef module fill:#bbf,stroke:#333,stroke-width:2px;
    classDef external fill:#cfc,stroke:#333,stroke-width:2px;
    classDef ci fill:#fc9,stroke:#333,stroke-width:2px;
```
