# abdulgh/eigenvalueclipping architecture

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

- Interactive diagram: https://gitdiagram.com/abdulgh/eigenvalueclipping
- Repository: https://github.com/abdulgh/eigenvalueclipping

## Overview

##### Project Type and Purpose
- This is a command-line‐driven, Dockerized C++ application for estimating stock returns & covariances and computing optimal portfolios (Sharpe/min-variance etc.).
- It ingests time series data (from Tiingo or CSV), runs various statistical estimators, and outputs performance metrics and optional plots.

##### Top‐Level Components
a. External Services & Data Sources
- Tiingo REST API (HTTP GET)
- Local CSV files (in `./csv/`)
b. Data Access Layer
- `src/http` module: performs GET requests to Tiingo
- `src/io` module: reads/writes timeseries via mmap or CSV
c. Core Processing Layer
- `src/stats` module subdivided into:
- Return Estimators (historical, uniform, CAPM, James-Stein)
- Covariance Estimators (sample, Marchenko–Pastur clipping)
- Portfolio Optimizer (min-variance, Sharpe max)
d. Utilities
- `src/util` module: CSV parsing, date utilities, download helpers, ticker iteration
- `src/common.h` & `src/run.h`: global config & orchestration
e. User‐Facing Application
- `src/main.cpp`: bootstraps Docker/CMake build, reads config (`.env`), invokes the orchestration
- Optional graphics runner if `SHOW_GFX=ON`
f. Testing & CI
- `test/` folder: unit tests for date utils, I/O, HTTP caching, power-method, integration

##### Infrastructure & Build
- Dockerfile + `.dockerignore`: containerizes the runtime environment, sets up g++/OpenMP
- CMakeLists.txt: defines build targets, flags, and the SHOW_GFX option
- tickers.txt: input list of S&P500 symbols

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Docker Container"
        direction TB
        subgraph "Data Access Layer"
            direction TB
            HTTP["HTTP Client<br/>(libcurl)"]:::http
            IODisk["Disk I/O<br/>(mmap, POSIX)"]:::io
        end
        subgraph "Core Processing Layer"
            direction TB
            subgraph "Stats Module"
                direction TB
                Returns["Return Estimators"]:::stats
                Covars["Covariance Estimators"]:::stats
            end
            Opt["Portfolio Optimization<br/>& Evaluation"]:::stats
        end
        subgraph "Utilities Module"
            direction TB
            UtilsCSV["CSV Parser"]:::util
            UtilsDate["Date Utilities"]:::util
            UtilsDownload["Download Helpers"]:::util
            UtilsTicker["Ticker Iterator"]:::util
        end
        Orch["Orchestrator / Main<br/>(Bootstrap & Run)"]:::core
    end

    TiingoCloud["Tiingo REST API"]:::external
    CSVStore["Local CSV Files"]:::datastore
    CLI["User CLI / Output"]:::external
    GFX["Optional Graphics Runner"]:::external
    Env[".env Config"]:::config
    Tickers["tickers.txt"]:::config
    TestSuite["Testing Suite"]:::test

    TiingoCloud -->|HTTP GET| HTTP
    CSVStore -->|CSV parse| IODisk
    HTTP -->|fresh data| Returns
    HTTP -->|fresh data| Covars
    IODisk -->|timeseries| Returns
    IODisk -->|timeseries| Covars
    Returns -->|returns| Opt
    Covars -->|covariances| Opt
    Returns <-->|utils calls| UtilsCSV
    Returns <-->|utils calls| UtilsDate
    Covars <-->|utils calls| UtilsCSV
    Covars <-->|utils calls| UtilsDate
    Opt <-->|utilities| UtilsDownload
    Opt <-->|utilities| UtilsTicker
    Opt -->|results| Orch
    Orch -->|CLI output| CLI
    Orch -->|SHOW_GFX=ON| GFX
    Orch -->|reads| Env
    Orch -->|reads| Tickers

    TestSuite -.->|validates| Returns
    TestSuite -.->|validates| Covars
    TestSuite -.->|validates| IODisk
    TestSuite -.->|validates| HTTP

    classDef external fill:#D0E1F9,stroke:#1F4E79
    classDef http fill:#F9E79F,stroke:#B7950B
    classDef io fill:#AED6F1,stroke:#21618C
    classDef stats fill:#ABEBC6,stroke:#229954
    classDef util fill:#F5B7B1,stroke:#C0392B
    classDef core fill:#D7BDE2,stroke:#7D3C98
    classDef datastore fill:#FAD7A0,stroke:#B9770E
    classDef test fill:#F2D7D5,stroke:#A93226
    classDef config fill:#E8DAEF,stroke:#76448A

    click HTTP "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/http/get.cpp"
    click HTTP "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/http/get.h"
    click IODisk "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/io/tsio.h"
    click IODisk "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/io/eigenmmap.h"
    click Returns "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/stats/returnEstimation.h"
    click Covars "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/stats/covariance.h"
    click Covars "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/stats/clipping.h"
    click Opt "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/evaluate.h"
    click UtilsCSV "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/util/csv.h"
    click UtilsDate "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/util/dateutils.h"
    click UtilsDownload "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/util/download.h"
    click UtilsTicker "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/util/tickerIterator.h"
    click Orch "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/main.cpp"
    click Orch "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/common.h"
    click Orch "https://github.com/abdulgh/eigenvalueclipping/blob/main/src/run.h"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/dateAndColumn.cpp"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/dateutils.cpp"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/eigenmmap.cpp"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/getCached.cpp"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/integration.cpp"
    click TestSuite "https://github.com/abdulgh/eigenvalueclipping/blob/main/test/powerMethod.cpp"
    click Env "https://github.com/abdulgh/eigenvalueclipping/blob/main/.env"
    click Tickers "https://github.com/abdulgh/eigenvalueclipping/blob/main/tickers.txt"
    click CMakeLists "https://github.com/abdulgh/eigenvalueclipping/blob/main/CMakeLists.txt"
    click Dockerfile "https://github.com/abdulgh/eigenvalueclipping/tree/main/Dockerfile"
    click Dockerignore "https://github.com/abdulgh/eigenvalueclipping/blob/main/.dockerignore"
```
