# abtonmoy/vault-investment architecture

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

- Interactive diagram: https://gitdiagram.com/abtonmoy/vault-investment
- Repository: https://github.com/abtonmoy/vault-investment

## Overview

##### Project Type and Purpose
- This is a single‐page web application built with Streamlit, focused on portfolio tracking, optimization, and risk analysis.
- Users upload brokerage CSV/PDF files, view visualizations, run Modern Portfolio Theory optimizations, and analyze risk metrics using historical market data from yfinance.

##### File Structure Analysis
- Top Level
- app.py – Entry point, orchestrates the Streamlit UI.
- assets/ – Static images for documentation or UI.
- requirements.txt, LICENSE, README.md, .gitignore, .devcontainer – Supporting files.
- core/
- data_fetcher.py – Fetches historical price data via yfinance.
- robinhood_parser.py – Parses broker‐specific CSV/PDF.
- portfolio_optimizer.py – Implements optimization algorithms (Sharpe maximization, min volatility).
- interfaces/
- investment_tracker.py – UI tabs/components for data upload and portfolio overview.
- portfolio_optimizer_interface.py – UI for selecting optimization strategies.
- risk_analysis_interface.py – UI for displaying risk metrics and charts.
- utils/
- portfolio_charts.py, equity_vis.py – Rendering charts (Sankey, scatter, drawdown).
- risk_analysis.py, risk_beta_analysis.py – Statistical computations (VaR, beta).
- helpers.py, theme.py – Shared helpers and styling.

##### Key Architectural Patterns
- Layered (Presentation → Business Logic → Utilities/Data)
- Modular separation ensures UI code in interfaces/ calls business logic in core/, which in turn uses utils/ for computations and charting.
- External Integration: yfinance (market data), fuzzywuzzy/pdfplumber (optional parsing).

##### Main Components
a. Presentation Layer
- Streamlit App (app.py)
- UI Modules (interfaces/*.py)
b. Business Logic Layer
- Data Fetcher (core/data_fetcher.py)
- Parser (core/robinhood_parser.py)
- Optimizer (core/portfolio_optimizer.py)
c. Utility Services
- Charting & Visualization (utils/portfolio_charts.py, utils/equity_vis.py)
- Risk Calculators (utils/risk_analysis.py, utils/risk_beta_analysis.py)
- Helpers & Theme (utils/helpers.py, utils/theme.py)
d. External Services
- yfinance API (historical price data)
- File System (CSV/PDF uploads)
e. Data Flow & Storage
- Uploaded Files → Parser → Pandas DataFrame
- DataFrame → Fetcher → Merged price & transaction data
- Data → Optimizer & Risk Modules → Results → UI Components

##### Relationships and Interactions
- UI triggers file upload → core.robinhood_parser parses → returns DataFrame.
- UI requests historical prices → core.data_fetcher calls yfinance → DataFrame.
- Parsed + price data passed to portfolio_optimizer → returns allocation/results.
- Risk interface invokes utils.risk_analysis → computes VaR, Sharpe, drawdown.
- Chart utilities invoked by UI modules to render visualizations.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        SP["Streamlit App (app.py)"]:::presentation
        IT["Investment Tracker UI"]:::presentation
        PO_UI["Portfolio Optimizer UI"]:::presentation
        RA_UI["Risk Analysis UI"]:::presentation
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        PF["Brokerage File Parser"]:::business
        DF["Historical Data Fetcher"]:::business
        PO["Portfolio Optimizer"]:::business
    end

    %% Utility Services
    subgraph "Utility Services"
        PC["Charting & Visualization"]:::utility
        EV["Equity Time-Series Visualization"]:::utility
        RA["General Risk Metrics"]:::utility
        RBI["Beta & Correlation Analysis"]:::utility
        HLP["Helper Functions"]:::utility
        TH["Theme & Styling"]:::utility
    end

    %% External Services
    subgraph "External Services"
        FS["File System (CSV/PDF)"]:::external
        YF["yfinance API"]:::external
    end

    %% Configuration & Documentation
    subgraph "Configuration & Docs"
        AS["Static Assets"]:::config
        CFG["Streamlit Config"]:::config
        DC["Dev Container"]:::config
        REQ["Dependencies List"]:::config
        DOC["Project Documentation"]:::config
    end

    %% Data Flows & Interactions
    SP --> IT
    SP --> PO_UI
    SP --> RA_UI

    IT -->|upload file| PF
    PF -->|DataFrame| IT

    IT -->|request prices| DF
    DF -->|Price DataFrame| IT
    DF -->|fetch from| YF

    IT -->|init optimize| PO
    PO -->|allocation results| PO_UI

    RA_UI -->|compute risk| RA
    RA -->|metrics| RA_UI
    RA_UI -->|compute beta| RBI
    RBI -->|beta results| RA_UI

    IT --> PC
    PO_UI --> PC
    RA_UI --> PC
    IT --> EV
    PO_UI --> EV

    IT --> HLP
    PO_UI --> HLP
    RA_UI --> HLP

    SP --> TH
    IT --> TH
    PO_UI --> TH
    RA_UI --> TH

    PF --> FS

    %% Click Events
    click SP "https://github.com/abtonmoy/vault-investment/blob/main/app.py"
    click IT "https://github.com/abtonmoy/vault-investment/blob/main/interfaces/investment_tracker.py"
    click PO_UI "https://github.com/abtonmoy/vault-investment/blob/main/interfaces/portfolio_optimizer_interface.py"
    click RA_UI "https://github.com/abtonmoy/vault-investment/blob/main/interfaces/risk_analysis_interface.py"
    click PF "https://github.com/abtonmoy/vault-investment/blob/main/core/robinhood_parser.py"
    click DF "https://github.com/abtonmoy/vault-investment/blob/main/core/data_fetcher.py"
    click PO "https://github.com/abtonmoy/vault-investment/blob/main/core/portfolio_optimizer.py"
    click PC "https://github.com/abtonmoy/vault-investment/blob/main/utils/portfolio_charts.py"
    click EV "https://github.com/abtonmoy/vault-investment/blob/main/utils/equity_vis.py"
    click RA "https://github.com/abtonmoy/vault-investment/blob/main/utils/risk_analysis.py"
    click RBI "https://github.com/abtonmoy/vault-investment/blob/main/utils/risk_beta_analysis.py"
    click HLP "https://github.com/abtonmoy/vault-investment/blob/main/utils/helpers.py"
    click TH "https://github.com/abtonmoy/vault-investment/blob/main/utils/theme.py"
    click AS "https://github.com/abtonmoy/vault-investment/tree/main/assets/"
    click CFG "https://github.com/abtonmoy/vault-investment/blob/main/.streamlit/config.toml"
    click DC "https://github.com/abtonmoy/vault-investment/blob/main/.devcontainer/devcontainer.json"
    click REQ "https://github.com/abtonmoy/vault-investment/blob/main/requirements.txt"
    click DOC "https://github.com/abtonmoy/vault-investment/blob/main/README.md"

    %% Styling
    classDef presentation fill:#ade8f4,stroke:#023047,color:#000;
    classDef business fill:#c2f970,stroke:#2d6a4f,color:#000;
    classDef utility fill:#ffb703,stroke:#fb8500,color:#000;
    classDef external fill:#d3d3d3,stroke:#777,color:#000;
    classDef config fill:#bdb2ff,stroke:#5e548e,color:#000;
```
