# areshglad/monte-carlo-portfolio-risk-engine architecture

> Architecture diagram of the GitHub repository areshglad/monte-carlo-portfolio-risk-engine, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/areshglad/monte-carlo-portfolio-risk-engine
- Repository: https://github.com/areshglad/monte-carlo-portfolio-risk-engine

## Overview

1. This repository is a layered portfolio-risk analytics pipeline, centered on dbt SQL models plus a Python Monte Carlo engine. The overall purpose is to turn market price data into risk metrics, simulation outputs, and portfolio optimization results.

2. The architecture is organized in a classic Bronze / Silver / Gold pattern:
   - Bronze: raw market price ingestion and normalization.
   - Silver: intermediate market-statistics transformations.
   - Gold: analytical outputs used for risk reporting and optimization.

3. The Bronze layer is represented by `bronze_market_prices.sql`. This is the raw-data boundary of the system, where market price data is staged before any portfolio analytics are computed. `source.yml` likely defines the upstream source tables used by dbt.

4. The Silver layer consists of:
   - `silver_daily_returns.sql`
   - `silver_rolling_volatility.sql`
   - `silver_correlation_base.sql`
   
   These models derive core statistical inputs from prices: returns, volatility over time windows, and the correlation structure needed for covariance and portfolio risk calculations.

5. The Gold layer contains the business/analytics outputs:
   - `gold_covariance_input.sql`
   - `gold_monte_carlo_inputs.sql`
   - `gold_portfolio_risk_metrics.sql`
   - `gold_var_summary.sql`
   - `gold_simulation_summary.sql`
   - `gold_efficient_frontier.sql`
   
   This is where the model becomes decision-oriented: the system prepares simulation inputs, computes portfolio risk measures, summarizes Monte Carlo results, and derives an efficient frontier.

6. `monte_carlo_engine.py` is the main procedural/runtime component outside dbt. It likely consumes the curated Gold inputs and runs the simulation logic that dbt SQL alone is not suited for, such as iterative random-path generation, portfolio outcome sampling, and VaR/CVaR-style calculations.

7. The data flow appears to be one-way and sequential:
   raw market prices → daily returns / volatility / correlation → covariance and simulation inputs → Monte Carlo simulation and portfolio risk summaries → frontier/risk outputs for analysis and reporting.

8. The repository includes generated or downstream artifacts:
   - `monte_carlo_simulation_results.csv`
   - `monte carlo visuals.pdf`
   
   These indicate that the Python layer produces tabular simulation results and a visual/reporting deliverable, separate from the dbt transformation layer.

9. `dbt_project.yml` is the orchestration boundary for the SQL transformations. It defines the transformation project structure and governs how the Bronze/Silver/Gold models are built in the warehouse or Databricks environment.

10. The README explicitly references Databricks, dbt, Python, Monte Carlo simulation, VaR/CVaR modeling, and efficient frontier optimization. Architecturally, that means the warehouse/lakehouse handles the transformation layers, while Python handles simulation-heavy analytics.

11. A useful way to diagram this repository is as two cooperating subsystems:
   - dbt-managed data preparation and analytics modeling in SQL.
   - Python-based simulation and result generation.
   
   The handoff point is the Gold-layer input tables/files.

12. There are no clear signs of a web UI, API service, or streaming subsystem in the repository. The primary boundary is analytical compute, not application serving.

13. In short, this repo is an offline or batch-oriented risk analytics pipeline: ingest prices, transform them into statistical features, simulate portfolio outcomes, and publish risk/optimization outputs.

Main entry points: [`silver_daily_returns.sql`](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_daily_returns.sql) (Daily returns), [`monte_carlo_engine.py`](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_engine.py) (Monte Carlo), [`monte_carlo_simulation_results.csv`](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_simulation_results.csv) (Results CSV), [`bronze_market_prices.sql`](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/bronze_market_prices.sql) (Market prices)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Orchestration"]
  node_dbt_project["dbt project<br/>dbt config<br/>[dbt_project.yml]"]
  node_source_definitions["Sources<br/>[source.yml]"]
end

subgraph group_bronze["Bronze"]
  node_bronze_market_prices["Market prices<br/>bronze model"]
end

subgraph group_silver["Silver"]
  node_silver_daily_returns["Daily returns<br/>silver model"]
  node_silver_rolling_volatility["Rolling vol<br/>silver model"]
  node_silver_correlation_base["Correlation base<br/>silver model"]
end

subgraph group_gold["Gold"]
  node_gold_covariance_input["Covariance input<br/>gold model"]
  node_gold_monte_carlo_inputs["MC inputs<br/>gold model"]
  node_gold_portfolio_risk_metrics["Risk metrics<br/>gold model"]
  node_gold_var_summary["VaR summary<br/>gold model"]
  node_gold_simulation_summary["Simulation summary<br/>gold model"]
  node_gold_efficient_frontier["Efficient frontier<br/>gold model"]
end

subgraph group_python["Python"]
  node_monte_carlo_engine["Monte Carlo<br/>python runtime"]
end

subgraph group_artifacts["Artifacts"]
  node_simulation_results["Results CSV<br/>generated artifact"]
  node_simulation_report["Visual report<br/>generated artifact"]
end

node_dbt_project -->|"orchestrates"| node_bronze_market_prices
node_source_definitions -->|"feeds"| node_bronze_market_prices
node_bronze_market_prices -->|"transforms to"| node_silver_daily_returns
node_silver_daily_returns -->|"feeds"| node_silver_rolling_volatility
node_silver_daily_returns -->|"feeds"| node_silver_correlation_base
node_silver_rolling_volatility -->|"feeds"| node_gold_covariance_input
node_silver_correlation_base -->|"feeds"| node_gold_covariance_input
node_gold_covariance_input -->|"prepares"| node_gold_monte_carlo_inputs
node_gold_monte_carlo_inputs -->|"consumed by"| node_monte_carlo_engine
node_monte_carlo_engine -->|"produces"| node_simulation_results
node_simulation_results -->|"summarized by"| node_gold_simulation_summary
node_simulation_results -->|"summarized by"| node_gold_var_summary
node_gold_simulation_summary -->|"feeds"| node_gold_portfolio_risk_metrics
node_gold_var_summary -->|"feeds"| node_gold_portfolio_risk_metrics
node_gold_portfolio_risk_metrics -->|"supports"| node_gold_efficient_frontier
node_monte_carlo_engine -->|"produces"| node_simulation_report

click node_dbt_project "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/dbt_project.yml"
click node_source_definitions "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/source.yml"
click node_bronze_market_prices "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/bronze_market_prices.sql"
click node_silver_daily_returns "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_daily_returns.sql"
click node_silver_rolling_volatility "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_rolling_volatility.sql"
click node_silver_correlation_base "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_correlation_base.sql"
click node_gold_covariance_input "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_covariance_input.sql"
click node_gold_monte_carlo_inputs "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_monte_carlo_inputs.sql"
click node_gold_portfolio_risk_metrics "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_portfolio_risk_metrics.sql"
click node_gold_var_summary "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_var_summary.sql"
click node_gold_simulation_summary "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_simulation_summary.sql"
click node_gold_efficient_frontier "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_efficient_frontier.sql"
click node_monte_carlo_engine "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_engine.py"
click node_simulation_results "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_simulation_results.csv"
click node_simulation_report "https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte carlo visuals.pdf"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_dbt_project,node_source_definitions toneBlue
class node_bronze_market_prices toneAmber
class node_silver_daily_returns,node_silver_rolling_volatility,node_silver_correlation_base toneMint
class node_gold_covariance_input,node_gold_monte_carlo_inputs,node_gold_portfolio_risk_metrics,node_gold_var_summary,node_gold_simulation_summary,node_gold_efficient_frontier toneRose
class node_monte_carlo_engine toneIndigo
class node_simulation_results,node_simulation_report toneTeal
```

## Components

### Orchestration

dbt project configuration and source definitions that organize the SQL pipeline.

- [dbt project](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/dbt_project.yml): dbt config · Defines the dbt transformation project structure and build behavior. · `dbt_project.yml`
- [Sources](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/source.yml): dbt sources · Declares upstream warehouse tables used by the Bronze layer. · `source.yml`

### Bronze

Raw market price staging and normalization boundary.

- [Market prices](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/bronze_market_prices.sql): bronze model · Stages raw market price data before analytics transformations. · `bronze_market_prices.sql`

### Silver

Intermediate statistical feature models derived from prices.

- [Daily returns](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_daily_returns.sql): silver model · Derives asset return series from normalized price data. · `silver_daily_returns.sql`
- [Rolling vol](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_rolling_volatility.sql): silver model · Computes time-window volatility features from returns. · `silver_rolling_volatility.sql`
- [Correlation base](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/silver_correlation_base.sql): silver model · Builds the correlation structure used for covariance and risk analysis. · `silver_correlation_base.sql`

### Gold

Decision-oriented risk and optimization outputs.

- [Covariance input](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_covariance_input.sql): gold model · Assembles covariance-ready inputs from Silver statistics. · `gold_covariance_input.sql`
- [MC inputs](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_monte_carlo_inputs.sql): gold model · Prepares curated inputs consumed by the Monte Carlo engine. · `gold_monte_carlo_inputs.sql`
- [Risk metrics](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_portfolio_risk_metrics.sql): gold model · Computes portfolio-level risk measures for reporting. · `gold_portfolio_risk_metrics.sql`
- [VaR summary](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_var_summary.sql): gold model · Summarizes value-at-risk outputs from the simulation workflow. · `gold_var_summary.sql`
- [Simulation summary](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_simulation_summary.sql): gold model · Condenses Monte Carlo run results into reporting outputs. · `gold_simulation_summary.sql`
- [Efficient frontier](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/gold_efficient_frontier.sql): gold model · Derives optimization results for portfolio tradeoff analysis. · `gold_efficient_frontier.sql`

### Python

Monte Carlo simulation runtime outside dbt.

- [Monte Carlo](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_engine.py): python runtime · Executes iterative simulation logic and portfolio outcome sampling. · `monte_carlo_engine.py`

### Artifacts

Generated outputs produced by the simulation workflow.

- [Results CSV](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/main/monte_carlo_simulation_results.csv): generated artifact · Tabular simulation output produced by the Python engine. · `monte_carlo_simulation_results.csv`
- [Visual report](https://github.com/areshglad/monte-carlo-portfolio-risk-engine/blob/HEAD/monte%20carlo%20visuals.pdf): generated artifact · PDF visualization/report generated from simulation outputs. · `monte carlo visuals.pdf`

## Connections

- dbt project → Market prices: orchestrates · dbt project builds the Bronze model.
- Sources → Market prices: feeds · Declared upstream sources supply raw price data.
- Market prices → Daily returns: transforms to · Raw prices are converted into daily returns.
- Daily returns → Rolling vol: feeds · Return series is used to compute rolling volatility.
- Daily returns → Correlation base: feeds · Return series contributes to the correlation base.
- Rolling vol → Covariance input: feeds · Volatility features inform covariance-ready inputs.
- Correlation base → Covariance input: feeds · Correlation structure supports covariance assembly.
- Covariance input → MC inputs: prepares · Covariance inputs are curated for simulation.
- MC inputs → Monte Carlo: consumed by · Python simulation consumes Gold-layer inputs.
- Monte Carlo → Results CSV: produces · Engine writes tabular simulation results.
- Results CSV → Simulation summary: summarized by · Simulation outputs are aggregated into summary metrics.
- Results CSV → VaR summary: summarized by · Simulation outputs are used to derive VaR summary.
- Simulation summary → Risk metrics: feeds · Simulation summaries contribute to risk metrics.
- VaR summary → Risk metrics: feeds · VaR summary informs portfolio risk measures.
- Risk metrics → Efficient frontier: supports · Risk metrics support portfolio optimization.
- Monte Carlo → Visual report: produces · Engine generates the visual PDF report.