# antares-acies/portfolio-valuation architecture

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

- Interactive diagram: https://gitdiagram.com/antares-acies/portfolio-valuation
- Repository: https://github.com/antares-acies/portfolio-valuation

## Overview

##### Project type and purpose
- This is a batch-oriented financial data processing tool for portfolio valuation, implemented primarily in Python with experimental C++ modules for performance-critical routines (found under EXP_CPP).
- It ingests a variety of CSV datasets (cashflows, product master, curve repositories, etc.), applies valuation models, and emits parquet/CSV outputs.

##### File structure
- Top level:
- main.py            – entry point that orchestrates the valuation run
- generate_request.py – builds/serializes request payloads
- config.py          – holds configuration (paths, constants)
- helper.py          – utility functions used across modules
- Portfolio_Valuation.py – core orchestration of data read → compute → write
- Valuation_Models.py – financial model implementations
- Data directories (input):
- “Portfolio Valuation Data” and “Read Data Func Data” (and their sample-data counterparts) – grouped CSVs
- Output directory:
- output/Cashflow_Engine_Outputs – generated parquet and CSV results
- EXP_CPP folder:
- three sub-cases (1. POC success, 2. schedule, 3. pybind11) with mixed .cpp, .py, executables – indicates prototype C++ routines, some exposed via pybind11.

##### Components and interactions
a. Data ingestion layer
– File system sources (CSV directories)
– Data-reader functions (in helper.py or dedicated read functions)
b. Core valuation engine
– Portfolio_Valuation.py: orchestrates read → model apply → write
– Valuation_Models.py: contains pricing and cashflow models
c. C++ acceleration (optional/experimental)
– EXP_CPP modules for schedule computation
– Wrapped via build_ext.py & pybind11 for Python calls
d. Request/request-builder
– generate_request.py constructs request objects or payload definitions
e. Configuration/Utilities
– config.py for paths & constants
– helper.py for common utilities (date handling, I/O helpers)
f. Output
– Parquet/CSV writer routines embedded in Portfolio_Valuation or helper
– output folder hierarchy

##### Architectural patterns and design principles
- Modular layering: ingestion → business logic → output
- Separation of concerns: models isolated in Valuation_Models, orchestration in Portfolio_Valuation
- Extensibility point: C++ POC modules can be swapped in via pybind11
- File-based data flow: explicit CSV → in-memory objects → parquet/CSV

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources"
        direction TB
        DS1["Portfolio Valuation Data"]:::io
        DS2["Portfolio Valuation Sample Data"]:::io
        DS3["Read Data Func Data"]:::io
        DS4["Read Data Func Sample Data"]:::io
    end

    %% Configuration & Utilities
    subgraph "Config & Utilities"
        direction TB
        Config["config.py"]:::config
        DataReader["DataReader Utilities"]:::io
    end

    %% Request Builder
    RequestBuilder["generate_request.py"]:::config

    %% Orchestration Layer
    subgraph "Orchestration"
        direction TB
        Main["main.py"]:::process
        Orchestrator["Portfolio_Valuation.py"]:::process
    end

    %% Business Logic
    subgraph "Business Logic"
        direction TB
        Models["Valuation_Models.py"]:::logic
    end

    %% C++ Acceleration Modules
    subgraph "C++ Acceleration (Experimental)"
        direction TB
        BuildExt["build_ext.py"]:::cpp
        subgraph "POC Modules"
            direction TB
            CPP_POC_CPP["payment_schedule.cpp"]:::cpp
            CPP_POC_MAIN["main.py"]:::cpp
        end
        subgraph "Pybind11 Schedule"
            direction TB
            CPP_PB_SCHED_CPP["schedule.cpp"]:::cpp
            CPP_PB_SCHED_MAIN["main.py"]:::cpp
        end
        CPP_LEGACY["schedule.cpp (legacy)"]:::cpp
    end

    %% Output Layer
    Output["output/Cashflow_Engine_Outputs"]:::io

    %% Connections
    DS1 -->|reads CSV| DataReader
    DS2 -->|reads CSV| DataReader
    DS3 -->|reads CSV| DataReader
    DS4 -->|reads CSV| DataReader

    DataReader -->|ingests data| Orchestrator
    Config -->|provides settings| Orchestrator
    RequestBuilder -->|builds payload| Orchestrator

    Main -->|starts batch run| Orchestrator
    Orchestrator -->|executes models| Models
    Orchestrator -->|calls C++ acceleration| BuildExt
    BuildExt -->|builds extensions| CPP_POC_CPP
    BuildExt -->|builds extensions| CPP_POC_MAIN
    BuildExt -->|builds extensions| CPP_PB_SCHED_CPP
    BuildExt -->|builds extensions| CPP_PB_SCHED_MAIN
    BuildExt -->|builds extensions| CPP_LEGACY
    CPP_POC_CPP -->|returns results| Orchestrator
    CPP_POC_MAIN -->|returns results| Orchestrator
    CPP_PB_SCHED_CPP -->|returns results| Orchestrator
    CPP_PB_SCHED_MAIN -->|returns results| Orchestrator
    CPP_LEGACY -->|returns results| Orchestrator

    Orchestrator -->|writes output| Output

    %% Click Events
    click DS1 "https://github.com/antares-acies/portfolio-valuation/tree/main/Portfolio Valuation Data/"
    click DS2 "https://github.com/antares-acies/portfolio-valuation/tree/main/Portfolio Valuation Sample Data/"
    click DS3 "https://github.com/antares-acies/portfolio-valuation/tree/main/Read Data Func Data/"
    click DS4 "https://github.com/antares-acies/portfolio-valuation/tree/main/Read Data Func Sample Data/"
    click DataReader "https://github.com/antares-acies/portfolio-valuation/blob/main/helper.py"
    click Config "https://github.com/antares-acies/portfolio-valuation/blob/main/config.py"
    click RequestBuilder "https://github.com/antares-acies/portfolio-valuation/blob/main/generate_request.py"
    click Main "https://github.com/antares-acies/portfolio-valuation/blob/main/main.py"
    click Orchestrator "https://github.com/antares-acies/portfolio-valuation/blob/main/Portfolio_Valuation.py"
    click Models "https://github.com/antares-acies/portfolio-valuation/blob/main/Valuation_Models.py"
    click BuildExt "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/build_ext.py"
    click CPP_POC_CPP "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/1. POC success/payment_schedule.cpp"
    click CPP_POC_MAIN "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/1. POC success/main.py"
    click CPP_PB_SCHED_CPP "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/3. pybind11/schedule.cpp"
    click CPP_PB_SCHED_MAIN "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/3. pybind11/main.py"
    click CPP_LEGACY "https://github.com/antares-acies/portfolio-valuation/blob/main/EXP_CPP/2. schedule/schedule.cpp"
    click Output "https://github.com/antares-acies/portfolio-valuation/tree/main/output/Cashflow_Engine_Outputs/"

    %% Styles
    classDef io fill:#a8ddb5,stroke:#000,stroke-width:1px
    classDef process fill:#9ecae1,stroke:#000,stroke-width:1px
    classDef config fill:#d9d9d9,stroke:#000,stroke-width:1px
    classDef logic fill:#6baed6,stroke:#000,stroke-width:1px
    classDef cpp fill:#fdae6b,stroke:#000,stroke-width:1px
```
