# phamdinhkhanh/vnquant architecture

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

- Interactive diagram: https://gitdiagram.com/phamdinhkhanh/vnquant
- Repository: https://github.com/phamdinhkhanh/vnquant

## Overview

##### Main Components
- Data Module – This component is responsible for data acquisition and processing. Within the vnquant package, the “vnquant/data” subdirectory includes various modules like:
– DataLoader (for downloading price data from sources such as CAFE and VND)
– FinanceLoader (for loading financial, cashflow, and business index reports)
– Additional utility modules for handling data transformation.
- Plot Module – The “vnquant/plot” directory, which contains functions (e.g., vnquant_candle_stick) for rendering advanced stock charts. It interacts with the data objects to produce visual representations using advanced metrics.
- Config Module – The “vnquant/configs” part holds configuration settings that may inform default options, parameters, or constants.
- Logging Module – Found in “vnquant/log”, this component is used to record events and errors, ensuring observability of operations.
- Utility Module – The “vnquant/utils” directory provides helper functions, custom exceptions, and validation logic (such as checking data formats like OHLC/OHLCV).

##### Relationships and Interactions
- The Client/Application Layer: Users (or integrating applications) interact with the vnquant package by importing its modules, configuring DataLoader/FinanceLoader objects, and then calling visualization functions.
- The Data Module interfaces with external financial data sources (CAFE, VND) to download stock data. It outputs structured data (typically as pandas DataFrames) that are then consumed by the Plot Module.
- The Plot Module receives either raw data (DataFrames or symbol strings) and uses the configuration (provided by the Config Module) and logging (via the Log Module) during the visualization process.
- The Utility Module supports both Data and Plot modules by providing common validation and error management functionality.
- The package’s setup and installation process (setup.py, requirements.txt) facilitates integration and dependency management.

##### Architectural Patterns and Design Principles
- Modular Design: Each core functionality (data loading, plotting, configuration, and logging) has its own subcomponent, which promotes separation of concerns.
- Layered Architecture: The system is structured so that lower-level modules (data fetching and processing) are decoupled from higher-level functionality (visualization and user interfacing).
- Extensibility: The existence of different “loader” modules (in vnquant/data/loader) hints at a plug-in style design for accommodating multiple data sources.
- Reusability: Common utilities are abstracted into the “utils” package for use across the system.

##### Relevant Technologies, Frameworks, or Libraries
- Python (core language) with its packaging conventions (setup.py, requirements.txt)
- Pandas (implied by the use of DataFrames for OHLC data)
- Matplotlib (or similar plotting libraries) – although not directly mentioned, it’s likely used within the Plot module.
- Git for version control (as indicated by .gitignore and the provided installation via git clone).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External & Client Layer"
        A1["User / Client"]:::client
        A2["Data Sources (CAFE,VND)"]:::external
    end

    subgraph "vnquant Package"
        subgraph "Data Module"
            D1["Data Module"]:::data
            D2["DataLoader"]:::data
            D3["FinanceLoader"]:::data
            D4["Loader (cafe,proto,vnd)"]:::data
        end
        subgraph "Plot Module"
            P1["Plot Module"]:::plot
            P2["Plot Implementation"]:::plot
            P3["vnquant_candlestick"]:::plot
        end
        subgraph "Supporting Services"
            C1["Config Module"]:::config
            L1["Logging Module"]:::log
            U1["Utility Module"]:::utils
            U2["Utility Functions"]:::utils
            U3["Custom Exceptions"]:::utils
        end
    end

    subgraph "Build & Deployment"
        B1["Setup & Installation (setup.py)"]:::build
    end

    A1 -->|"interacts"| D1
    A1 -->|"interacts"| P1
    A1 -->|"deploys"| B1
    A2 -->|"providesData"| D1

    D1 --> D2
    D1 --> D3
    D1 --> D4

    D2 -->|"feedsData"| P1
    D3 -->|"feedsData"| P1
    D4 -->|"feedsData"| P1

    P1 --> P2
    P1 --> P3

    C1 -->|"configures"| D1
    C1 -->|"configures"| P1

    L1 -->|"logs"| D1
    L1 -->|"logs"| P1

    U1 --> U2
    U1 --> U3
    U1 -->|"supports"| D1
    U1 -->|"supports"| P1

    click D1 "https://github.com/phamdinhkhanh/vnquant/tree/master/vnquant/data"
    click D2 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/data/dataloader.py"
    click D3 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/data/finance.py"
    click D4 "https://github.com/phamdinhkhanh/vnquant/tree/master/vnquant/data/loader"

    click P1 "https://github.com/phamdinhkhanh/vnquant/tree/master/vnquant/plot"
    click P2 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/plot/Plot.py"
    click P3 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/plot/plot.py"

    click C1 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/configs/configs.py"
    click L1 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/log/logging.py"

    click U1 "https://github.com/phamdinhkhanh/vnquant/tree/master/vnquant/utils"
    click U2 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/utils/utils.py"
    click U3 "https://github.com/phamdinhkhanh/vnquant/blob/master/vnquant/utils/exceptions.py"

    classDef client fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef external fill:#aed6f1,stroke:#1f618d,stroke-width:2px;
    classDef data fill:#abebc6,stroke:#1e8449,stroke-width:2px;
    classDef plot fill:#fadbd8,stroke:#922b21,stroke-width:2px;
    classDef config fill:#f5cba7,stroke:#b9770e,stroke-width:2px;
    classDef log fill:#d2dae2,stroke:#636e72,stroke-width:2px;
    classDef utils fill:#d5f5e3,stroke:#27ae60,stroke-width:2px;
    classDef build fill:#d6eaf8,stroke:#2e86c1,stroke-width:2px;
```
