# yatshunlee/caviar architecture

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

- Interactive diagram: https://gitdiagram.com/yatshunlee/caviar
- Repository: https://github.com/yatshunlee/caviar

## Overview

##### Project type and purpose
- This is a Python‐based research toolkit for value-at-risk (VaR) modeling and backtesting using the CAViaR approach.
- It consists of two core libraries—`caviar` (quantile regression VaR models) and `var_tests` (backtesting routines)—plus supporting modules, example notebooks, documentation, and demo dashboards.

##### File structure
- Top‐level modules:
- `/caviar`: Implements CAViaR models, Bayesian/frequentist quantile regression, utility functions, custom exceptions.
- `/var_tests`: VaR backtest functions (Kupiec, DQ tests, etc.).
- `/backtesting`: Higher-level backtest workflows and driver scripts.
- Demo applications:
- `/dashboard_caviar`: Streamlit dashboard for live demonstration.
- `/dashboard_presentation`: Sample Streamlit script, notebooks, and a `localtunnel` setup for sharing.
- Documentation and examples:
- `/doc`: Markdown docs for each component.
- `/notebook-example`, `/notebook-experiment`, `/notebook-test`: Jupyter notebooks illustrating usage, experiments, and tests.
- Config files: `requirements.txt` (root), `dashboard_presentation/requirements.txt`.

##### Extract additional insights from the README
- Two primary libraries (`caviar`, `var_tests`) form the backend computation layer.
- Dashboards are thin presentation layers that consume the libraries’ APIs.
- Notebooks serve both as user documentation and experimental pipelines.
- The system was designed to allow easy swapping of optimization constraints and initialization strategies.

a. Main components
- Data Source (CSV files, live market feed)
- Preprocessing Layer (data cleaning/transformation modules or notebooks)
- CAViaR Modeling Engine (`caviar` library)
- VaR Backtesting Engine (`var_tests` + `/backtesting` module)
- Demo Dashboards (`dashboard_caviar`, `dashboard_presentation`)
- Documentation & Notebooks (side-by-side experimental environment)
b. Component interactions
- Data Source → Preprocessing → CAViaR Engine → VaR Forecasts
- VaR Forecasts → Backtesting Engine → Backtest Reports
- Modeling & Backtesting APIs → Dashboards → End User (web UI)
- Notebooks invoke Modeling & Backtesting libraries for ad-hoc analysis
c. Key architectural patterns
- Layered architecture (data → computation → presentation)
- Clear separation of concerns: modeling vs. backtesting vs. presentation vs. docs
- Modular Python packaging for easy reuse and extension
d. Core technologies
- Python 3.x, NumPy, Pandas, SciPy, statsmodels
- Streamlit for interactive dashboards
- Jupyter Notebooks for examples and experiments
- localtunnel (for demo sharing)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DataSource[("Sample Data Source\npoc/dataCAViaR.txt")]:::data
        click DataSource "https://github.com/yatshunlee/caviar/blob/main/poc/dataCAViaR.txt"
        Replicate["replicate_result.ipynb"]:::docs
        click Replicate "https://github.com/yatshunlee/caviar/blob/main/poc/replicate_result.ipynb"
    end

    %% Preprocessing
    Preprocessing["Preprocessing Module"]:::backend

    %% Modeling Engine
    subgraph "CAViaR Modeling Engine (caviar)" 
        direction TB
        CM1["_caviar_model.py"]:::backend
        click CM1 "https://github.com/yatshunlee/caviar/blob/main/caviar/_caviar_model.py"
        CM2["_caviar_function.py"]:::backend
        click CM2 "https://github.com/yatshunlee/caviar/blob/main/caviar/_caviar_function.py"
        CM3["_arch_model.py"]:::backend
        click CM3 "https://github.com/yatshunlee/caviar/blob/main/caviar/_arch_model.py"
        CM4["_bayesian.py"]:::backend
        click CM4 "https://github.com/yatshunlee/caviar/blob/main/caviar/_bayesian.py"
        CM5["_frequentist.py"]:::backend
        click CM5 "https://github.com/yatshunlee/caviar/blob/main/caviar/_frequentist.py"
        CM6["_quantreg.py"]:::backend
        click CM6 "https://github.com/yatshunlee/caviar/blob/main/caviar/_quantreg.py"
        CM7["_utils.py"]:::backend
        click CM7 "https://github.com/yatshunlee/caviar/blob/main/caviar/_utils.py"
        CM8["_exceptions.py"]:::backend
        click CM8 "https://github.com/yatshunlee/caviar/blob/main/caviar/_exceptions.py"
    end

    %% Backtesting Engine
    subgraph "VaR Backtesting Engine (var_tests)" 
        direction TB
        VT1["_test.py"]:::backend
        click VT1 "https://github.com/yatshunlee/caviar/blob/main/var_tests/_test.py"
    end

    %% High-Level Backtesting Workflows
    subgraph "Backtesting Workflows (backtesting)"
        direction TB
        BW1["_backtest.py"]:::backend
        click BW1 "https://github.com/yatshunlee/caviar/blob/main/backtesting/_backtest.py"
        BW2["__init__.py"]:::backend
        click BW2 "https://github.com/yatshunlee/caviar/blob/main/backtesting/__init__.py"
        BW3["README.md"]:::docs
        click BW3 "https://github.com/yatshunlee/caviar/blob/main/backtesting/README.md"
    end

    %% Modeling to Backtesting Flow
    DataSource --> Preprocessing --> CM1
    CM1 --> CM2
    CM8 --> VT1
    CM1 -->|"VaR Forecasts"| VT1
    VT1 --> BW1

    %% Dashboards
    subgraph "Demo Dashboards"
        direction TB
        DC["dashboard.py"]:::presentation
        click DC "https://github.com/yatshunlee/caviar/blob/main/dashboard_caviar/dashboard.py"
        DP1["steamlit_sample.py"]:::presentation
        click DP1 "https://github.com/yatshunlee/caviar/blob/main/dashboard_presentation/steamlit_sample.py"
        DP2["localtunnel.ipynb"]:::docs
        click DP2 "https://github.com/yatshunlee/caviar/blob/main/dashboard_presentation/localtunnel.ipynb"
        DP3["requirements.txt"]:::backend
        click DP3 "https://github.com/yatshunlee/caviar/blob/main/dashboard_presentation/requirements.txt"
        DP4["README.md"]:::docs
        click DP4 "https://github.com/yatshunlee/caviar/blob/main/dashboard_presentation/README.md"
    end

    %% Documentation
    subgraph "Documentation (doc)"
        direction TB
        D1["caviar.md"]:::docs
        click D1 "https://github.com/yatshunlee/caviar/blob/main/doc/caviar.md"
        D2["vartest.md"]:::docs
        click D2 "https://github.com/yatshunlee/caviar/blob/main/doc/vartest.md"
        D3["backtesting.md"]:::docs
        click D3 "https://github.com/yatshunlee/caviar/blob/main/doc/backtesting.md"
        D4["dashboard.md"]:::docs
        click D4 "https://github.com/yatshunlee/caviar/blob/main/doc/dashboard.md"
        D5["README.md"]:::docs
        click D5 "https://github.com/yatshunlee/caviar/blob/main/doc/README.md"
    end

    %% Notebooks
    subgraph "Notebooks"
        direction TB
        subgraph "Example Notebooks"
            direction TB
            N1["example-garch.ipynb"]:::docs
            click N1 "https://github.com/yatshunlee/caviar/blob/main/notebook-example/example-garch.ipynb"
            N2["example-mle.ipynb"]:::docs
            click N2 "https://github.com/yatshunlee/caviar/blob/main/notebook-example/example-mle.ipynb"
            N3["example-rq.ipynb"]:::docs
            click N3 "https://github.com/yatshunlee/caviar/blob/main/notebook-example/example-rq.ipynb"
        end
        subgraph "Experiment Notebooks"
            direction TB
            E1["random_seed_analysis_RQ_MLE.ipynb"]:::docs
            click E1 "https://github.com/yatshunlee/caviar/blob/main/notebook-experiment/random_seed_analysis_RQ_MLE.ipynb"
            E2["random_seed_experiment_best_start_random_start.ipynb"]:::docs
            click E2 "https://github.com/yatshunlee/caviar/blob/main/notebook-experiment/random_seed_experiment_best_start_random_start.ipynb"
        end
        subgraph "Test Notebooks"
            direction TB
            T1["kupiec_pof_test.ipynb"]:::docs
            click T1 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/kupiec_pof_test.ipynb"
            T2["chi2_standard_normal.ipynb"]:::docs
            click T2 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/chi2_standard_normal.ipynb"
            T3["traffic_light_test.ipynb"]:::docs
            click T3 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/traffic_light_test.ipynb"
            T4["implementation.ipynb"]:::docs
            click T4 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/implementation.ipynb"
            T5["gradient_descent_fail.ipynb"]:::docs
            click T5 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/gradient_descent_fail.ipynb"
            T6["trading_strategy.ipynb"]:::docs
            click T6 "https://github.com/yatshunlee/caviar/blob/main/notebook-test/trading_strategy.ipynb"
        end
    end

    %% Dashboard interactions
    CM1 --> DC
    VT1 --> DC
    CM1 --> DP1
    VT1 --> DP1

    %% Notebooks interactions
    N1 --> CM1
    E1 --> CM1
    T1 --> VT1

    %% Styles
    classDef data fill:#9f6,stroke:#333,stroke-width:1px;
    classDef backend fill:#6cf,stroke:#333,stroke-width:1px;
    classDef presentation fill:#fc6,stroke:#333,stroke-width:1px;
    classDef docs fill:#ccc,stroke:#333,stroke-width:1px;
```
