How idolbinhminhtran/volatility-explorer works
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/)