# nehcuh/quantbox architecture

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

- Interactive diagram: https://gitdiagram.com/nehcuh/quantbox
- Repository: https://github.com/nehcuh/quantbox

## Overview

##### Main Components
- Data Fetchers: Represented by the “quantbox/fetchers” directory, these modules are responsible for interfacing with external APIs or local data operations. They include base interfaces (base.py), specialized implementations for Tushare and Goldminer, utilities for caching, monitoring, and validation.
- Data Savers: Found in “quantbox/savers” (e.g., data_saver.py), this component handles the persistence layer, storing the fetched financial data into a MongoDB database.
- Graphical User Interface (GUI): The “quantbox/gui” folder contains GUI implementation (main_window.py) built with PyQt5, allowing users to interact with the system visually.
- Command Line Interface (CLI) and Shell: Modules like “quantbox/cli.py” and “quantbox/shell.py” provide command-line tools for executing data operations.
- Core Utilities and Configuration: The “quantbox/util” folder (along with config.py, logger.py, and validators.py) forms the backbone supporting various functionalities – from date handling and exchange code normalization to logging and configuration management.
- Business/Domain Logic: The “biz” directory (e.g., holding_stats.py) is likely used for higher-level domain-specific logic, such as financial statistics and market analysis.
- External Dependencies: MongoDB (possibly running in a Docker container as defined in “docker/qb-base/database.yaml”) and dependencies such as pymongo, pandas, and others.

##### Out the Relationships and Interactions
- External Data Sources (e.g., Tushare & Goldminer APIs) → Data Fetchers: The fetchers interface with external APIs, perform data validation, and offer standardized outputs.
- Data Fetchers → Data Validators: After fetching the raw data, validation modules (including quantbox/validators.py and validation in fetchers) ensure consistency.
- Data Flow to MongoDB: Validated data is then sent to Data Savers (MarketDataSaver in savers) which persist data in MongoDB.
- User Interfaces: Both the CLI (cli.py and shell.py) and GUI (gui/main_window.py) interact with the fetchers and savers to provide operations like fetching trade dates or saving contract data.
- Monitoring and Performance: Within the fetchers (monitoring.py), performance monitors are set to track data retrieval efficiency, which can be represented as a feedback component.
- Configuration: The config.py module and external configuration files (e.g., templates/config.toml, user’s ~/.quantbox/config.toml) are integrated by all components to ensure the system is running with the correct parameters.

##### Architectural Patterns and Design Principles
- Modular design: Each functionality (fetching, saving, validating, interfacing) is encapsulated in its own module. This ensures flexibility and ease of extension, especially if new data sources are to be integrated.
- Separation of concerns: The system clearly separates the data ingestion, persistence, and presentation layers (CLI/GUI).
- Extensibility: The clear boundaries between modules (especially within “fetchers” and “savers”) allow for new implementations (e.g., additional data sources) without disrupting existing flows.
- Use of external configuration and environment management: Highlighted by the configuration files and Docker setup for MongoDB.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Data Sources
    subgraph "External Data Sources" 
        E1["Tushare API"]:::external
        E2["Goldminer API"]:::external
    end

    %% Data Fetchers Subgraph
    subgraph "Data Fetchers"
        F1["Base Interface"]:::fetcher
        F2["Fetcher Tushare"]:::fetcher
        F3["Fetcher Goldminer"]:::fetcher
        F4["Local Fetcher"]:::fetcher
        F5["Remote Fetcher"]:::fetcher
        F6["Cache"]:::fetcher
        F7["Monitoring"]:::fetcher
        F8["Utils (Fetcher)"]:::fetcher
        F9["Validation (Fetcher)"]:::fetcher
    end

    %% Data Savers
    DS1["Data Saver Module"]:::saver

    %% User Interfaces Subgraph
    subgraph "User Interfaces"
        CLI1["CLI Interface"]:::ui
        CLI2["Shell Interface"]:::ui
        G1["GUI Main Window"]:::ui
    end

    %% Utilities & Configuration Subgraph
    subgraph "Utilities & Configuration"
        U1["Config"]:::util
        U2["Logger"]:::util
        U3["Validators"]:::util
        U4["Date Utils"]:::util
        U5["Exchange Utils"]:::util
        U6["Basic Tools"]:::util
        U7["Tools"]:::util
    end

    %% Business Logic
    B1["Holding Stats"]:::biz

    %% External Dependencies
    subgraph "External Dependencies"
        DB1["MongoDB Database"]:::db
        D1["Docker Mongo Config"]:::dbconf
    end

    %% Connections from External Data Sources to Data Fetchers
    E1 -->|"calls"| F2
    E2 -->|"calls"| F3

    %% Connections from Data Fetchers to Data Saver
    F2 -->|"output"| DS1
    F3 -->|"output"| DS1
    F4 -->|"output"| DS1
    F5 -->|"output"| DS1
    F9 -->|"validated"| DS1

    %% Feedback from Monitoring back to Fetchers
    F7 -->|"feedback"| F2

    %% User Interface interactions triggering fetchers and saver
    CLI1 ---|"triggers"| F1
    CLI1 ---|"commands"| DS1
    CLI2 ---|"triggers"| F1
    CLI2 ---|"commands"| DS1
    G1 ---|"interacts"| F1
    G1 ---|"commands"| DS1

    %% Utilities support to various components
    U1 --- F1
    U1 --- DS1
    U1 --- CLI1
    U1 --- G1
    U2 --- F1
    U2 --- DS1
    U3 --- F9
    U3 --- B1
    U4 --- F1
    U5 --- F1
    U6 --- F1
    U7 --- F1

    %% Data Saver stores data into MongoDB
    DS1 -->|"stores"| DB1
    D1 -->|"configures"| DB1

    %% Business Logic uses data from Data Saver
    DS1 -->|"feeds"| B1

    %% Click Events for Data Fetchers
    click F1 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/base.py"
    click F2 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/fetcher_tushare.py"
    click F3 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/fetcher_goldminer.py"
    click F4 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/local_fetcher.py"
    click F5 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/remote_fetcher.py"
    click F6 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/cache.py"
    click F7 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/monitoring.py"
    click F8 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/utils.py"
    click F9 "https://github.com/nehcuh/quantbox/blob/main/quantbox/fetchers/validation.py"

    %% Click Event for Data Saver
    click DS1 "https://github.com/nehcuh/quantbox/blob/main/quantbox/savers/data_saver.py"

    %% Click Events for User Interfaces
    click G1 "https://github.com/nehcuh/quantbox/blob/main/quantbox/gui/main_window.py"
    click CLI1 "https://github.com/nehcuh/quantbox/blob/main/quantbox/cli.py"
    click CLI2 "https://github.com/nehcuh/quantbox/blob/main/quantbox/shell.py"

    %% Click Events for Core Utilities and Configuration
    click U1 "https://github.com/nehcuh/quantbox/blob/main/quantbox/config.py"
    click U2 "https://github.com/nehcuh/quantbox/blob/main/quantbox/logger.py"
    click U3 "https://github.com/nehcuh/quantbox/blob/main/quantbox/validators.py"
    click U4 "https://github.com/nehcuh/quantbox/blob/main/quantbox/util/date_utils.py"
    click U5 "https://github.com/nehcuh/quantbox/blob/main/quantbox/util/exchange_utils.py"
    click U6 "https://github.com/nehcuh/quantbox/blob/main/quantbox/util/basic.py"
    click U7 "https://github.com/nehcuh/quantbox/blob/main/quantbox/util/tools.py"

    %% Click Event for Business Logic
    click B1 "https://github.com/nehcuh/quantbox/blob/main/biz/holding_stats.py"

    %% Click Event for External Dependency Docker Config
    click D1 "https://github.com/nehcuh/quantbox/blob/main/docker/qb-base/database.yaml"

    %% Styles
    classDef external fill:#d3d3d3,stroke:#333,stroke-width:1px;
    classDef fetcher fill:#add8e6,stroke:#333,stroke-width:1px;
    classDef saver fill:#90ee90,stroke:#333,stroke-width:1px;
    classDef ui fill:#ffb6c1,stroke:#333,stroke-width:1px;
    classDef util fill:#ffd700,stroke:#333,stroke-width:1px;
    classDef biz fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef db fill:#98fb98,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
    classDef dbconf fill:#ffdead,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5;
```
