# pmorissette/ffn architecture

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

- Interactive diagram: https://gitdiagram.com/pmorissette/ffn
- Repository: https://github.com/pmorissette/ffn

## Overview

##### Project Type and Purpose
- Project type: Open-source Python library for quantitative finance.
- Purpose: Provide performance measurement, evaluation, and data-transformation utilities on top of Pandas/Numpy/Scipy, plus documentation and CI/CD pipelines.

##### File Structure
- Top-level packages/directories:
– `ffn/` – core library modules: `core.py`, `data.py`, `utils.py`
– `tests/` – unit tests (`test_core.py`, `test_utils.py`) and test data
– `docs/` – Sphinx documentation source, custom theme (`_themes/klink`)
– GitHub workflows (`.github/workflows`) for build, deploy, regression
– Packaging/config: `setup.py`, `pyproject.toml`, `Makefile`, `MANIFEST.in`
- CI/CD: GitHub Actions build, regression, deploy pipelines in YAML.

##### Extract Key Insights from README
- Dependencies: Pandas, Numpy, Scipy, plus graphing libraries.
- Workflow: Users install via pip; project uses Sphinx to generate online docs; CI deploys to PyPI and to GitHub Pages.

##### Main Components & Their Roles
a. Core Library (ffn)
– Sub-modules: `core`, `data`, `utils`
– Exposes public API (e.g., `get`, `to_returns`, `calc_mean_var_weights`)
b. External Dependencies
– Data‐analysis stack: Pandas, Numpy, Scipy, Matplotlib etc.
c. Testing Suite
– Pytest tests in `tests/`
– Test data under `tests/data`
d. Documentation System
– Sphinx project under `docs/`
– Custom theme “klink” under `docs/source/_themes/klink`
– Makefiles to build HTML docs
e. CI/CD Pipeline
– Build & test workflows (`build.yml`, `regression.yml`)
– Deploy workflow (`deploy.yml`) publishes to PyPI (via `setup.py`) and updates docs site
f. Distribution
– PyPI package created from `setup.py`/`pyproject.toml`
– Documentation website hosted (e.g., GitHub Pages)

##### Relationships & Data Flow
- User → installs package from PyPI → invokes ffn API → ffn imports/uses external libs → returns results
- Developer push → GitHub Actions → runs tests on Core Library → on success builds docs → on success publishes package + docs
- Sphinx → reads `docs/source/` + custom theme → outputs HTML docs
- Packaging config → defines package metadata, dependencies

##### Architectural Patterns & Principles
- Modular design: separate modules for core logic (`core.py`), data ingestion (`data.py`), utilities (`utils.py`).
- Layered architecture:
1. Public API layer (ffn)
2. Infrastructure layer (external libs)
3. Supporting systems (tests, docs, CI/CD)
- Convention over configuration for packaging (standard Python project layout).
- Continuous Integration and Delivery using GitHub Actions.

##### Minimum Elements
1. Library Module: ffn (with sub-modules)
2. External Data/Computation Dependencies (Pandas, Numpy, etc.)
3. Test Suite (pytest)
4. Documentation Pipeline (Sphinx + theme)
5. CI/CD (GitHub Actions workflows)
6. Packaging & Distribution (setup.py, PyPI)
7. User Interaction (installation, API usage)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Distribution
    User["User"]:::user
    PyPI[("( PyPI )")]:::dist

    %% Core Library Layer
    subgraph "Core Library (ffn)" 
        direction TB
        FfnInit["ffn/__init__.py"]:::library
        Core["core.py"]:::library
        Data["data.py"]:::library
        Utils["utils.py"]:::library
    end

    %% External Dependencies
    External["(Pandas, Numpy, Scipy, Matplotlib)"]:::external

    %% Testing Suite
    subgraph "Testing Suite" 
        direction TB
        TestInit["tests/__init__.py"]:::testing
        TestCore["test_core.py"]:::testing
        TestUtils["test_utils.py"]:::testing
        TestData["test_data.csv"]:::testing
    end

    %% Documentation System
    subgraph "Documentation (Sphinx)" 
        direction TB
        DocMakefile["docs/Makefile"]:::docs
        DocBat["docs/make.bat"]:::docs
        Conf["docs/source/conf.py"]:::docs
        Index["docs/source/index.rst"]:::docs
        FfnRst["docs/source/ffn.rst"]:::docs
        Theme["docs/source/_themes/klink/"]:::docs
    end

    %% CI/CD Pipelines
    subgraph "CI/CD (GitHub Actions)" 
        direction TB
        BuildYml[".github/workflows/build.yml"]:::cicd
        RegYml[".github/workflows/regression.yml"]:::cicd
        DepYml[".github/workflows/deploy.yml"]:::cicd
    end

    %% Packaging & Config
    subgraph "Packaging & Config"
        direction TB
        Setup["setup.py"]:::dist
        PyProject["pyproject.toml"]:::dist
        Manifest["MANIFEST.in"]:::dist
        RootMake["Makefile"]:::dist
        Readme["README.md"]:::docs
        GitIgnore[".gitignore"]:::cicd
        License["LICENSE"]:::cicd
        BugTemp[".github/ISSUE_TEMPLATE/bug_report.md"]:::cicd
        FeatureTemp[".github/ISSUE_TEMPLATE/feature_request.md"]:::cicd
        Dependabot[".github/dependabot.yml"]:::cicd
    end

    %% Flows
    User -->|"installs"| PyPI
    PyPI -->|"provides ffn package"| FfnInit
    FfnInit --> Core
    FfnInit --> Data
    FfnInit --> Utils
    Core -->|"uses"| External
    Data -->|"uses"| External
    Utils -->|"uses"| External

    %% CI/CD flow
    BuildYml -->|"triggers tests"| TestCore
    BuildYml --> TestUtils
    RegYml --> TestCore
    RegYml --> TestUtils
    BuildYml -->|"builds docs"| DocMakefile
    BuildYml --> DocBat
    DepYml -->|"publishes to PyPI"| PyPI
    DepYml -->|"deploys docs"| Theme

    %% Packaging flow
    Setup --> PyPI
    PyProject --> PyPI
    Manifest --> PyPI

    %% Documentation build flow
    DocMakefile --> Conf
    Conf --> Index
    Conf --> FfnRst
    Conf --> Theme

    %% Testing data
    TestCore --> TestData
    TestUtils --> TestData

    %% Click Events
    click FfnInit "https://github.com/pmorissette/ffn/blob/master/ffn/__init__.py"
    click Core "https://github.com/pmorissette/ffn/blob/master/ffn/core.py"
    click Data "https://github.com/pmorissette/ffn/blob/master/ffn/data.py"
    click Utils "https://github.com/pmorissette/ffn/blob/master/ffn/utils.py"

    click TestInit "https://github.com/pmorissette/ffn/blob/master/tests/__init__.py"
    click TestCore "https://github.com/pmorissette/ffn/blob/master/tests/test_core.py"
    click TestUtils "https://github.com/pmorissette/ffn/blob/master/tests/test_utils.py"
    click TestData "https://github.com/pmorissette/ffn/blob/master/tests/data/test_data.csv"

    click DocMakefile "https://github.com/pmorissette/ffn/tree/master/docs/Makefile"
    click DocBat "https://github.com/pmorissette/ffn/blob/master/docs/make.bat"
    click Conf "https://github.com/pmorissette/ffn/blob/master/docs/source/conf.py"
    click Index "https://github.com/pmorissette/ffn/blob/master/docs/source/index.rst"
    click FfnRst "https://github.com/pmorissette/ffn/blob/master/docs/source/ffn.rst"
    click Theme "https://github.com/pmorissette/ffn/tree/master/docs/source/_themes/klink/"

    click BuildYml "https://github.com/pmorissette/ffn/blob/master/.github/workflows/build.yml"
    click RegYml "https://github.com/pmorissette/ffn/blob/master/.github/workflows/regression.yml"
    click DepYml "https://github.com/pmorissette/ffn/blob/master/.github/workflows/deploy.yml"

    click Setup "https://github.com/pmorissette/ffn/blob/master/setup.py"
    click PyProject "https://github.com/pmorissette/ffn/blob/master/pyproject.toml"
    click Manifest "https://github.com/pmorissette/ffn/blob/master/MANIFEST.in"
    click RootMake "https://github.com/pmorissette/ffn/tree/master/Makefile"
    click Readme "https://github.com/pmorissette/ffn/blob/master/README.md"
    click GitIgnore "https://github.com/pmorissette/ffn/blob/master/.gitignore"
    click License "https://github.com/pmorissette/ffn/tree/master/LICENSE"
    click BugTemp "https://github.com/pmorissette/ffn/blob/master/.github/ISSUE_TEMPLATE/bug_report.md"
    click FeatureTemp "https://github.com/pmorissette/ffn/blob/master/.github/ISSUE_TEMPLATE/feature_request.md"
    click Dependabot "https://github.com/pmorissette/ffn/blob/master/.github/dependabot.yml"

    %% Styles
    classDef library fill:#bbdefb,stroke:#1e88e5;
    classDef external fill:#c8e6c9,stroke:#2e7d32;
    classDef testing fill:#ffe0b2,stroke:#ef6c00;
    classDef docs fill:#fff9c4,stroke:#f9a825;
    classDef cicd fill:#e1bee7,stroke:#8e24aa;
    classDef dist fill:#80deea,stroke:#00838f;
    classDef user fill:#cfd8dc,stroke:#455a64;
```
