# fmilthaler/finquant architecture

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

- Interactive diagram: https://gitdiagram.com/fmilthaler/finquant
- Repository: https://github.com/fmilthaler/finquant

## Overview

##### Project Type and Purpose
- FinQuant is an open-source Python library focused on financial portfolio management, analysis, and optimization.
- Its purpose is to provide users with a simple interface (via the Portfolio object and related functions) to download stock data (via quandl/yfinance), compute various financial metrics (e.g., returns, moving averages), and perform portfolio optimisation (using efficient frontier methods and Monte Carlo simulations).

##### Analyzing the File Structure
- Notice a clear separation between:
- Core library code in the "finquant" directory: files like portfolio.py, asset.py, market.py, efficient_frontier.py, returns.py, etc.
- Examples in the "example" directory that demonstrate usage.
- Extensive documentation in "docs".
- Test cases in the "tests" folder.
- CI/CD and build scripts within ".github/workflows", Makefiles, setup.py, and others.
- The modular structure (each financial calculation or functionality is in its own module) indicates the project follows a layered design where the Portfolio module glues the functionality together, calling specialized modules (like moving_average, returns, efficient_frontier) as needed.

##### Insights from the README
- The README clearly outlines the main functionality: portfolio management, different types of returns, moving averages (and Bollinger bands), and portfolio optimization (efficient frontier and Monte Carlo methods).
- The examples show how the user sets up a portfolio – meaning the entry point is primarily the function build_portfolio, which creates and returns an instance of the Portfolio class.
- External dependencies (e.g., numpy, pandas, matplotlib, quandl, yfinance) indicate FinQuant’s integration with financial data sources and plotting libraries.

##### Final Advice
- Be as explicit as possible when breaking the project into components. Do not hesitate to separate even fine-grained modules like asset, stock, or type_utilities if they play a key role.
- Connections with notes on dependency and function (for example: “Portfolio calls returns for computing daily returns”).
- Remember that clear labeling, directional data flow, and visual distinction are paramount.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface (Examples)"
        UI["Example Scripts"]:::ui
    end

    subgraph "Core Library (finquant package)"
        Portfolio["Portfolio Module"]:::core
        Asset["Asset Module"]:::core
        Stock["Stock Module"]:::core
        Market["Market Data Processing"]:::core
        Returns["Returns Computation"]:::core
        MovingAvg["Moving Average Calculations"]:::core
        Opt["Portfolio Optimisation"]:::core
        Quants["Additional Quantitative Methods"]:::core
        Supporting["Supporting Modules"]:::core
        
        Supp1["data_types"]:::support
        Supp2["exceptions"]:::support
        Supp3["minimise_fun"]:::support
        Supp4["type_utilities"]:::support
    end

    subgraph "Data & External Sources"
        Data["Sample Datasets"]:::data
        ExtLib["External Libraries\n(numpy,pandas,matplotlib,quandl,yfinance)"]:::ext
    end

    subgraph "Supporting Infrastructure"
        Docs["Documentation"]:::infra
        Tests["Test Cases"]:::infra
        CI["CI/CD Workflows"]:::ci
        Build["Build/Packaging Scripts"]:::ci
    end

    %% Relationships between components
    UI -->|"invokes"| Portfolio

    Portfolio -->|"calls"| Returns
    Portfolio -->|"calls"| MovingAvg
    Portfolio -->|"integrates"| Opt
    Portfolio -->|"accesses"| Market
    Portfolio -->|"references"| Asset
    Portfolio -->|"references"| Stock
    Portfolio -->|"utilizes"| Quants

    %% Internal supporting modules association
    Supporting --- Supp1
    Supporting --- Supp2
    Supporting --- Supp3
    Supporting --- Supp4

    %% Data flow from external sources
    Market -->|"fetches"| Data
    Returns -->|"computes_with"| ExtLib
    MovingAvg -->|"plots_with"| ExtLib
    Opt -->|"optimizes_with"| ExtLib

    %% Support infrastructure connections
    Portfolio --- Docs
    Portfolio --- Tests
    Portfolio --- CI
    Portfolio --- Build

    Docs --- Tests
    Docs --- CI
    Docs --- Build

    %% Click Events
    click UI "https://github.com/fmilthaler/finquant/tree/master/example/"
    click Portfolio "https://github.com/fmilthaler/finquant/blob/master/finquant/portfolio.py"
    click Asset "https://github.com/fmilthaler/finquant/blob/master/finquant/asset.py"
    click Stock "https://github.com/fmilthaler/finquant/blob/master/finquant/stock.py"
    click Market "https://github.com/fmilthaler/finquant/blob/master/finquant/market.py"
    click Returns "https://github.com/fmilthaler/finquant/blob/master/finquant/returns.py"
    click MovingAvg "https://github.com/fmilthaler/finquant/blob/master/finquant/moving_average.py"
    click Opt "https://github.com/fmilthaler/finquant/blob/master/finquant/efficient_frontier.py"
    click Quants "https://github.com/fmilthaler/finquant/blob/master/finquant/quants.py"
    click Supp1 "https://github.com/fmilthaler/finquant/blob/master/finquant/data_types.py"
    click Supp2 "https://github.com/fmilthaler/finquant/blob/master/finquant/exceptions.py"
    click Supp3 "https://github.com/fmilthaler/finquant/blob/master/finquant/minimise_fun.py"
    click Supp4 "https://github.com/fmilthaler/finquant/blob/master/finquant/type_utilities.py"
    click Data "https://github.com/fmilthaler/finquant/tree/master/data/"
    click Docs "https://github.com/fmilthaler/finquant/tree/master/docs/"
    click Tests "https://github.com/fmilthaler/finquant/tree/master/tests/"
    click CI "https://github.com/fmilthaler/finquant/tree/master/.github/workflows/"
    click Build "https://github.com/fmilthaler/finquant/blob/master/setup.py"

    %% Styles
    classDef ui fill:#c2f0c2,stroke:#333,stroke-width:2px;
    classDef core fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef support fill:#e0e0e0,stroke:#333,stroke-width:2px;
    classDef data fill:#ffdab9,stroke:#333,stroke-width:2px;
    classDef ext fill:#ffe4e1,stroke:#333,stroke-width:2px;
    classDef infra fill:#f5f5dc,stroke:#333,stroke-width:2px;
    classDef ci fill:#fffacd,stroke:#333,stroke-width:2px;
```
