# cristianleoo/montecarlo-portfolio-management architecture

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

- Interactive diagram: https://gitdiagram.com/cristianleoo/montecarlo-portfolio-management
- Repository: https://github.com/cristianleoo/montecarlo-portfolio-management

## Overview

##### File structure
- Top-level:
- app.py        → Streamlit entry point (UI layer)
- config.py     → global configuration (constants, API keys, default parameters)
- setup.py, requirements.txt, LICENSE, .gitignore
- package “portfolio_management/”:
- data/         → DataLoader (fetching historical prices from external market data API)
- monte_carlo/  → simulation engine (runs Monte Carlo trials)
- portfolio/    → domain objects (Portfolio) and optimizer (Sharpe‐maximizer, balanced)
- utils/        → helper routines (e.g. date validation, formatting)
- tests/: unit tests for each module
- screenshots/: sample UIs for reference

##### Inspect README for insights
- Describes UI workflow: ticker selection → weight input or dollar amounts → optional optimization → set simulation parameters → run Monte Carlo → interactive Plotly charts.
- Technology stack: Python 3.7+, Streamlit, Plotly, pandas/numpy.

##### Main components & relationships
a. Components:
- Streamlit UI (app.py)
- Configuration (config.py)
- DataLoader service
- Portfolio domain + Optimizer
- Monte Carlo Simulation engine
- Utilities
- External Market Data API
- Plotly rendering library
b. Interactions:
1. User interacts with Streamlit UI.
2. UI reads config, passes user inputs to DataLoader and Portfolio modules.
3. DataLoader fetches historical prices from external API.
4. Portfolio module builds a portfolio object; optionally calls Optimizer.
5. Simulation engine runs trials on portfolio object.
6. Results are returned to UI, formatted by utils, visualized via Plotly.
c. Architectural patterns:
- Layered architecture (UI → service/domain → data → external API)
- Separation of concerns: data access, business logic, presentation
d. Key technologies:
- Streamlit (UI layer)
- pandas & numpy (data manipulation)
- Plotly (visualization)
- Python package structure for modularity

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        App["Streamlit UI"]:::ui
        Plotly["Plotly Rendering Library"]:::ui
    end

    %% Service/Domain Layer
    subgraph "Service/Domain Layer"
        Portfolio["Portfolio Domain Object"]:::service
        Optimizer["Portfolio Optimizer"]:::service
        Simulation["Monte Carlo Simulation Engine"]:::service
        Utils["Utility Helpers"]:::service
        Main["Application Entry Point"]:::service
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        DataLoader["DataLoader Service"]:::data
    end

    %% External Services
    ExternalAPI["External Market Data API"]:::external
    Config["Configuration"]:::external

    %% Relationships
    Config -->|provides parameters| App
    Config -->|provides defaults| Portfolio
    Config -->|provides defaults| Optimizer
    Config -->|provides defaults| Simulation

    App -->|requests data| DataLoader
    DataLoader -->|fetch historical prices| ExternalAPI
    ExternalAPI -->|returns data| DataLoader
    App -->|builds portfolio| Portfolio
    Portfolio -->|optional optimization| Optimizer
    App -->|runs simulation| Simulation
    Simulation -->|returns results| App
    App -->|renders charts| Plotly
    App -->|formats data| Utils
    DataLoader -->|uses| Utils
    Portfolio -->|uses| Utils
    Simulation -->|uses| Utils

    %% Click Events
    click App "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/app.py"
    click Config "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/config.py"
    click DataLoader "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/data/data_loader.py"
    click Portfolio "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/portfolio/portfolio.py"
    click Optimizer "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/portfolio/optimizer.py"
    click Simulation "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/monte_carlo/simulation.py"
    click Utils "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/utils/helpers.py"
    click Main "https://github.com/cristianleoo/montecarlo-portfolio-management/blob/main/portfolio_management/main.py"

    %% Styles
    classDef ui fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef service fill:#E6F4EA,stroke:#22863A,color:#22863A;
    classDef data fill:#FFF5B1,stroke:#D29922,color:#D29922;
    classDef external fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
