# sookeyy-12/risklens architecture

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

- Interactive diagram: https://gitdiagram.com/sookeyy-12/risklens
- Repository: https://github.com/sookeyy-12/risklens

## Overview

##### Project Type and Purpose
- RiskLens is a full-stack, data-driven Streamlit dashboard for advanced volatility analysis and sector risk assessment.
- The core “engine” is in the `src/` library (data acquisition, volatility models, sector analytics, visualization helpers). The “app” layer (in `app/`) is the Streamlit presentation layer that binds UI components to the core library.

##### File-Structure Analysis
- Top-level directories and files:
- `app/` – Streamlit application: configuration (`config.py`), main entrypoint (`main.py`), UI components (`components/`), and page-level views (`views/`).
- `src/` – Core analytics library: `data_fetcher.py`, volatility methods (`volatility.py`), sector analysis (`sector_analysis.py`), visualization helpers (`visualization.py`), plus utility functions.
- `data/` – Static assets (e.g., `sector_mapping.csv`).
- `scripts/` – Standalone scripts for data fetching, volatility computation, dashboard updates.
- `notebooks/` – Jupyter demos and ad-hoc analyses.
- Launchers (`launch_app.py`, `launch_app.ps1`) and dependency lists (`requirements_streamlit.txt`, `pyproject.toml`).
- `tests/` – Unit tests for core library modules.

##### README Insights
- Describes four Streamlit pages (Home, Heatmap Analysis, Chart Analysis, About Developer).
- Calls out performance features (Streamlit caching, vectorized NumPy/Pandas ops, Plotly interactivity).
- Lists external data source (yfinance) and static sector mapping.

##### Key Architectural Components
a. Data Sources & Ingestion
- External: Yahoo Finance via `yfinance`.
- Internal: `data/sector_mapping.csv`.
- Ingestion layer: `src/data_fetcher.py` (cached with Streamlit TTL).
b. Business Logic / Analytics Layer
- Volatility calculations: `src/volatility.py` (Historical, Parkinson, Garman-Klass, Beta-adjusted).
- Sector analysis and regime detection: `src/sector_analysis.py`.
- Utility routines: `src/utils.py`.
c. Visualization Layer
- Plotly-based functions: `src/visualization.py`.
- Streamlit UI components: `app/components/heatmap.py`, `app/components/charts.py`.
d. Presentation / UI Layer
- Streamlit main app: `app/main.py` (sets up sidebar navigation & page routing).
- Page views: `app/views/home.py`, `heatmap_analysis.py`, `chart_analysis.py`, `about_developer.py`.
- Configuration: `app/config.py` (themes, default parameters).
e. Orchestration & Launch
- Launch scripts: Python and PowerShell entrypoints that invoke Streamlit or call `app/main.py`.
- Scheduled/standalone scripts: `scripts/` directory for batch data updates or re-computations.
f. Testing & Quality
- `tests/` directory for unit tests covering data ingestion, sector logic, volatility models.

##### Relationships & Data Flows
- `data_fetcher` outputs DataFrames → passed to `volatility` and `sector_analysis`.
- Analysis results → Plotly figures via `visualization`.
- Figures and widgets consumed by Streamlit UI components.
- User interactions in UI → trigger data fetch and recompute through caching decorators.
- Scripts in `scripts/` orchestrate core library calls without UI.

##### Architectural Patterns & Principles
- Layered Architecture:
1. Data Layer
2. Business Logic Layer
3. Visualization Layer
4. Presentation Layer
- MVC-like separation: Core library (Model), Streamlit views (View), and `app/main.py` as Controller.
- Caching for performance and rate-limit safety.
- Modular, extensible design—new volatility models or data sources plug into `src/`.

##### Technologies & Frameworks
- Python 3.8+
- Streamlit (UI)
- Plotly (visuals)
- Pandas & NumPy (data processing)
- yfinance (data source)
- Pytest (testing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer" 
        direction TB
        YF["yfinance (External)"]:::data
        CSV["sector_mapping.csv"]:::data
        DF["DataFetcher"]:::core
    end

    %% Core Library Layer
    subgraph "Core Library (Business Logic)" 
        direction TB
        VOL["Volatility Module"]:::core
        SEC["Sector Analysis Module"]:::core
        UTL["Utility Functions"]:::core
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        VIS["Plotly Visualization Helpers"]:::core
    end

    %% Presentation / UI Layer
    subgraph "Presentation / UI Layer"
        direction TB
        MAIN["Streamlit Main (Controller)"]:::ui
        subgraph "UI Components"
            direction TB
            HM["Heatmap Component"]:::ui
            CH["Charts Component"]:::ui
        end
        subgraph "Page Views"
            direction TB
            HOME["Home View"]:::ui
            HVIEW["Heatmap Analysis View"]:::ui
            CVIEW["Chart Analysis View"]:::ui
            AVIEW["About Developer View"]:::ui
        end
    end

    %% Orchestration & Launch
    subgraph "Orchestration & Launch" 
        direction TB
        PYLAUNCH["launch_app.py"]:::orch
        PSLAUNCH["launch_app.ps1"]:::orch
        subgraph "Scripts"
            direction TB
            S1["fetch_data.py"]:::orch
            S2["compute_volatility.py"]:::orch
            S3["update_dashboard.py"]:::orch
        end
        NOTEBOOKS["Jupyter Notebooks"]:::orch
    end

    %% Testing & Quality
    subgraph "Testing & Quality"
        direction TB
        T1["test_data_fetcher.py"]:::orch
        T2["test_sector_analysis.py"]:::orch
        T3["test_sector.py"]:::orch
        T4["test_single_ticker.py"]:::orch
    end

    %% Data Flows
    YF -->|"fetch data"| DF
    CSV -->|"load mapping"| DF
    DF -->|"DataFrame"| VOL
    DF -->|"DataFrame"| SEC
    VOL -->|"results"| VIS
    SEC -->|"results"| VIS
    VIS -->|"figures"| HM
    VIS -->|"figures"| CH
    HM -->|"render"| HVIEW
    CH -->|"render"| CVIEW
    MAIN -->|"route/pages"| HOME
    MAIN -->|"route/pages"| HVIEW
    MAIN -->|"route/pages"| CVIEW
    MAIN -->|"route/pages"| AVIEW
    MAIN -->|"embed components"| HM
    MAIN -->|"embed components"| CH
    USER["User Interaction"]:::ui -->|"interact"| MAIN
    USER -->|"interact"| HM
    USER -->|"interact"| CH
    PYLAUNCH -->|"start UI"| MAIN
    PSLAUNCH -->|"start UI"| MAIN
    S1 -->|"batch fetch"| DF
    S2 -->|"batch compute"| VOL
    S3 -->|"update app"| MAIN
    NOTEBOOKS -->|"import"| VOL
    NOTEBOOKS -->|"import"| SEC
    NOTEBOOKS -->|"import"| UTL

    %% Click Events
    click DF "https://github.com/sookeyy-12/risklens/blob/main/src/data_fetcher.py"
    click CSV "https://github.com/sookeyy-12/risklens/blob/main/data/sector_mapping.csv"
    click VOL "https://github.com/sookeyy-12/risklens/blob/main/src/volatility.py"
    click SEC "https://github.com/sookeyy-12/risklens/blob/main/src/sector_analysis.py"
    click UTL "https://github.com/sookeyy-12/risklens/blob/main/src/utils.py"
    click VIS "https://github.com/sookeyy-12/risklens/blob/main/src/visualization.py"
    click HM "https://github.com/sookeyy-12/risklens/blob/main/app/components/heatmap.py"
    click CH "https://github.com/sookeyy-12/risklens/blob/main/app/components/charts.py"
    click MAIN "https://github.com/sookeyy-12/risklens/blob/main/app/main.py"
    click HOME "https://github.com/sookeyy-12/risklens/blob/main/app/views/home.py"
    click HVIEW "https://github.com/sookeyy-12/risklens/blob/main/app/views/heatmap_analysis.py"
    click CVIEW "https://github.com/sookeyy-12/risklens/blob/main/app/views/chart_analysis.py"
    click AVIEW "https://github.com/sookeyy-12/risklens/blob/main/app/views/about_developer.py"
    click PYLAUNCH "https://github.com/sookeyy-12/risklens/blob/main/launch_app.py"
    click PSLAUNCH "https://github.com/sookeyy-12/risklens/blob/main/launch_app.ps1"
    click S1 "https://github.com/sookeyy-12/risklens/blob/main/scripts/fetch_data.py"
    click S2 "https://github.com/sookeyy-12/risklens/blob/main/scripts/compute_volatility.py"
    click S3 "https://github.com/sookeyy-12/risklens/blob/main/scripts/update_dashboard.py"
    click T1 "https://github.com/sookeyy-12/risklens/blob/main/tests/test_data_fetcher.py"
    click T2 "https://github.com/sookeyy-12/risklens/blob/main/tests/test_sector_analysis.py"
    click T3 "https://github.com/sookeyy-12/risklens/blob/main/tests/test_sector.py"
    click T4 "https://github.com/sookeyy-12/risklens/blob/main/tests/test_single_ticker.py"

    %% Styles
    classDef data fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef ui fill:#ffe5cc,stroke:#333,stroke-width:1px
    classDef orchestration fill:#f2f2f2,stroke:#333,stroke-width:1px
    class USER userIcon
    class NOTEBOOKS orchestration
    class MAIN ui
```
