# dcajasn/riskfolio-lib architecture

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

- Interactive diagram: https://gitdiagram.com/dcajasn/riskfolio-lib
- Repository: https://github.com/dcajasn/riskfolio-lib

## Overview

##### Project Type and Purpose
- This is a financial modeling and portfolio optimization library (Riskfolio‐Lib) that provides tools to perform quantitative asset allocation. Its functionalities include different portfolio optimization techniques (mean risk, risk parity, hierarchical clustering portfolios, nested clustered optimization, etc.) with a broad set of risk measures.
- The solution interfaces with mathematical modeling libraries (CVXPY, clarabel), uses Pandas for data management, integrates with external solvers (such as MOSEK and GUROBI), and uses visualization (matplotlib) to create plots and reports.

##### Main Architectural Components by Examining the File Structure
– Core Library Functionality:
- Located primarily in the directory “riskfolio/src” and “riskfolio/external”.
- Key modules include Portfolio.py, RiskFunctions.py, HCPortfolio.py, OwaWeights.py, ConstraintsFunctions.py, and others. These implement the core logic for the optimization methods and risk measure calculations.
- The “riskfolio/external” folder contains C++ modules (for computationally heavy matrix functions and other algorithms) with Python bindings (cpp_functions_bindings.cpp, cppfunctions.py).

– Third-Party Dependencies and Libraries:
- The project relies on standard Python libraries such as NumPy, SciPy, Pandas, matplotlib, and CVXPY.
- It also integrates with external C++ libraries placed in the “lib” directory (e.g., Eigen and Spectra) that underpin many of the numerical routines and accelerate the heavy matrix computations.

– Examples and Tests:
- The “examples” folder contains Jupyter Notebooks and sample Python scripts that demonstrate how to use the library, which may be shown as an “Application Usage / Integration Layer”.
- The “tests” folder provides CSV datasets and testing scripts for validating portfolio construction logic.

– Documentation and Metadata:

##### Relationships and Interactions
- Core modules in “riskfolio/src” interact with each other to build the different portfolio optimization models.
- The “riskfolio/external” layer supplies high-performance routines (often through C++ bindings) that these core modules call when necessary.
- Both core and external modules depend on third-party libraries (e.g., CVXPY for formulating optimization problems; clarabel and external solvers for risk measure calculations; Pandas for data handling).
- The visualization/reporting modules (found in riskfolio/src/PlotFunctions.py, Reports.py) take outputs from optimization routines and generate graphic or Excel-based reports.
- The testing suite validates the outputs from the core modules and ensures correct integration with external libraries.

##### Important Architectural Patterns/Design Concepts
- Layered Architecture: Separate layers for core computations (business logic), external native extensions (C++ libraries), and interfacing/documentation (examples, tests).
- Modularity: Various independent modules for risk measures, constraints, and optimization techniques that interconnect.
- Dependency Injection: The design allows plugging in different optimization solvers (through CVXPY’s abstraction) and different risk measures models.

##### Instructing the Principal Software Engineer
- Data flow from “Input Data” → “Core Modules” → “Solver Abstraction (CVXPY & clarabel)” → “External Libraries (Eigen, Spectra)” → “Output / Visualization”.
- Dependencies of “riskfolio/src” on both “riskfolio/external” and third-party packages.

## Diagram (Mermaid)

```mermaid
graph TD
    A["Input Data (CSV/Excel)"]
    B["Core Modules (riskfolio/src)"]
    H["Visualization & Reporting (PlotFunctions,Reports)"]
    C["External C++ Bindings (riskfolio/external)"]
    D["High-Performance Library: Eigen"]
    E["High-Performance Library: Spectra"]
    F["Third-Party Dependency: requirements.txt"]
    G["Third-Party Dependency: pyproject.toml"]
    I["Examples & Usage (examples)"]
    J["Testing Suite (tests)"]
    K["Documentation (docs)"]

    A -->|"feeds"| B
    B -->|"produces"| H
    B -->|"calls"| C
    C -->|"uses"| D
    C -->|"uses"| E
    B -->|"depends_on"| F
    B -->|"depends_on"| G
    B -->|"integrates_with"| I
    B -->|"validated_by"| J
    B -->|"documented_by"| K

    click B "https://github.com/dcajasn/riskfolio-lib/tree/master/riskfolio/src"
    click C "https://github.com/dcajasn/riskfolio-lib/tree/master/riskfolio/external"
    click F "https://github.com/dcajasn/riskfolio-lib/blob/master/requirements.txt"
    click G "https://github.com/dcajasn/riskfolio-lib/blob/master/pyproject.toml"
    click D "https://github.com/dcajasn/riskfolio-lib/blob/master/lib/eigen-3.4.0"
    click E "https://github.com/dcajasn/riskfolio-lib/blob/master/lib/spectra-1.0.1"
    click I "https://github.com/dcajasn/riskfolio-lib/tree/master/examples"
    click J "https://github.com/dcajasn/riskfolio-lib/tree/master/tests"
    click K "https://github.com/dcajasn/riskfolio-lib/tree/master/docs"

    class A input;
    class B core;
    class C external;
    class F thirdparty;
    class G thirdparty;
    class D highperf;
    class E highperf;
    class I examples;
    class J testing;
    class K docs;
    class H reporting;

    classDef core fill:#AED6F1,stroke:#1F618D,stroke-width:2px;
    classDef external fill:#A9DFBF,stroke:#1E8449,stroke-width:2px;
    classDef thirdparty fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef highperf fill:#F5B7B1,stroke:#943126,stroke-width:2px;
    classDef examples fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;
    classDef testing fill:#FADBD8,stroke:#922B21,stroke-width:2px;
    classDef docs fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef input fill:#FCF3CF,stroke:#B7950B,stroke-width:2px;
    classDef reporting fill:#FDEBD0,stroke:#E67E22,stroke-width:2px;
```
