# idolbinhminhtran/volatility-explorer architecture

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

- Interactive diagram: https://gitdiagram.com/idolbinhminhtran/volatility-explorer
- Repository: https://github.com/idolbinhminhtran/volatility-explorer

## Overview

##### Project Type and Purpose
- VoltaTrade is a full-stack, data-driven web application built in Python with the Shiny for Python framework.
- Its purpose is to ingest historical volatility CSV data, run multiple ML models (including a Graph Attention Network), and present interactive dashboards for volatility prediction, stock screening, portfolio tracking, and model comparison.
- It also integrates with the OpenAI API for AI-powered market insights and explanations.

##### File Structure
- Top-level:
- app.py – entry point launching the Shiny server
- home.py – home/dashboard module
- requirements.txt, .gitignore, .env (for API keys and flags)
- data/ – raw and precomputed CSV data used as the “database.”
- models/ – stored outputs of predictive models (CSV snapshots).
- modules/ – Python modules each encapsulating a feature:
– common_style.py (UI theming)
– home.py (dashboard logic)
– individual_stock.py, model_details.py, portfolio_tracker.py, screener.py, stock_comparison.py (business logic & UI for each view)
– visual_effects.py (animations/UX enhancements)
- src/ and www/ – static assets (images, CSS).

##### README for Additional Insights
- It describes a reactive web UI powered by Shiny, seven ML models, GAT as star performer, AI-powered explanations via OpenAI, and real-time interaction.
- There is no separate microservice; it’s a monolithic Shiny app that reads from CSV files and calls modules.

a. Main Components
1. User Browser (Front-end) – renders UI, sends events (clicks, selections).
2. Shiny Server (Back-end) – app.py + home.py orchestrate the reactive pipeline.
3. Module Layer – business logic controllers in modules/*.
4. Data Layer – CSV files in data/ and models/ directories.
5. External Service – OpenAI API for AI explanations.

b. Relationships and Interactions
- Browser ↔ Shiny Server via HTTP/websocket (reactive calls).
- Shiny Server → Module Layer: dispatches user requests to modules.
- Modules → Data Layer: read historical and model CSVs for analytics.
- Modules → External Service: call OpenAI API for insights.
- Shiny Server → Asset Server: serve CSS and images to the browser.

c. Architectural Patterns & Design Principles
- MVC-style:
– View: UI definitions within modules and Shiny render functions.
– Controller: modules/*.py handle business logic and data retrieval.
– Model: CSV files as flat-file storage for both raw data and model outputs.
- Modular design: each feature is encapsulated in its own Python module.
- Reactive programming: Shiny’s event-driven, dataflow-oriented architecture.
- Separation of concerns: styling (common_style.py, CSS) is separated from data logic.

d. Key Technologies & Frameworks
- Python 3.8+, Shiny for Python (shiny module)
- Pandas for data I/O & processing
- Graph Attention Network (GAT) and other ML model artifacts read from models/
- OpenAI Python SDK for AI insights
- Static assets (CSS in www/, images in src/)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Front-end
    Browser["User Browser"]:::frontend

    %% Back-end
    Shiny["Shiny Server"]:::backend

    %% Module Layer
    ModuleLayer["Module Layer"]:::backend
    subgraph "Module Layer"
        CS["common_style.py"]:::backend
        HM["home.py"]:::backend
        IS["individual_stock.py"]:::backend
        MD["model_details.py"]:::backend
        PT["portfolio_tracker.py"]:::backend
        SC["screener.py"]:::backend
        SP["stock_comparison.py"]:::backend
        VE["visual_effects.py"]:::backend
    end

    %% Data Layer
    DataLayer["Data Layer"]:::data
    subgraph "Raw CSV Data (data/)"
        HA["high_attention_pairs.csv"]:::data
        MS["metrics_summary.csv"]:::data
        ME["mini_all_explanations.csv"]:::data
        PR["predicted_realized_vol.csv"]:::data
        VD["vol_df.csv"]:::data
    end
    subgraph "Model Outputs (models/)"
        EWMA["EWMA_predictions.csv"]:::data
        GAT["GAT_prediction_panel.csv"]:::data
        GB["Gradient_Boosting_predictions.csv"]:::data
        HAR["HAR_RV_predictions.csv"]:::data
        LAG1["LAG1_predictions.csv"]:::data
        LIN["Linear_predictions.csv"]:::data
        PCA["PCA_Linear_predictions.csv"]:::data
        RF["Random_Forest_predictions.csv"]:::data
        ARV["actual_rv.csv"]:::data
        MMS["model_metrics_summary.csv"]:::data
    end

    %% External Service
    ExternalAPI["OpenAI API"]:::external

    %% Static Asset Server
    AssetServer["Static Asset Server"]:::assets
    subgraph "Assets"
        CSS["styles.css"]:::assets
        IMG["src/"]:::assets
    end

    %% Relationships
    Browser -->|"UI events (HTTP/WebSocket)"| Shiny
    Shiny -->|"dispatch request"| ModuleLayer
    ModuleLayer -->|"read CSV"| HA
    ModuleLayer -->|"read CSV"| MS
    ModuleLayer -->|"read CSV"| ME
    ModuleLayer -->|"read CSV"| PR
    ModuleLayer -->|"read CSV"| VD
    ModuleLayer -->|"read CSV"| EWMA
    ModuleLayer -->|"read CSV"| GAT
    ModuleLayer -->|"read CSV"| GB
    ModuleLayer -->|"read CSV"| HAR
    ModuleLayer -->|"read CSV"| LAG1
    ModuleLayer -->|"read CSV"| LIN
    ModuleLayer -->|"read CSV"| PCA
    ModuleLayer -->|"read CSV"| RF
    ModuleLayer -->|"read CSV"| ARV
    ModuleLayer -->|"read CSV"| MMS
    ModuleLayer -->|"API request"| ExternalAPI
    Shiny -->|"serve assets"| AssetServer
    AssetServer -->|"CSS & images"| Browser

    %% Click Events
    click Browser "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/www/styles.css"
    click Browser "https://github.com/idolbinhminhtran/volatility-explorer/tree/main/src/"
    click Shiny "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/app.py"
    click Shiny "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/home.py"
    click CS "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/common_style.py"
    click HM "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/home.py"
    click IS "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/individual_stock.py"
    click MD "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/model_details.py"
    click PT "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/portfolio_tracker.py"
    click SC "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/screener.py"
    click SP "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/stock_comparison.py"
    click VE "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/modules/visual_effects.py"
    click HA "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/data/high_attention_pairs.csv"
    click MS "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/data/metrics_summary.csv"
    click ME "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/data/mini_all_explanations.csv"
    click PR "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/data/predicted_realized_vol.csv"
    click VD "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/data/vol_df.csv"
    click EWMA "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/EWMA_predictions.csv"
    click GAT "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/GAT_prediction_panel.csv"
    click GB "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/Gradient_Boosting_predictions.csv"
    click HAR "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/HAR_RV_predictions.csv"
    click LAG1 "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/LAG1_predictions.csv"
    click LIN "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/Linear_predictions.csv"
    click PCA "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/PCA_Linear_predictions.csv"
    click RF "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/Random_Forest_predictions.csv"
    click ARV "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/actual_rv.csv"
    click MMS "https://github.com/idolbinhminhtran/volatility-explorer/blob/main/models/model_metrics_summary.csv"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366D6,color:#0366D6
    classDef backend fill:#E6FFEA,stroke:#28A745,color:#28A745
    classDef data fill:#FFF4E6,stroke:#FF9F1C,color:#FF9F1C
    classDef external fill:#F3E8FF,stroke:#8A2BE2,color:#8A2BE2
    classDef assets fill:#F0F0F0,stroke:#666666,color:#333333
```
