# google/tf-quant-finance architecture

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

- Interactive diagram: https://gitdiagram.com/google/tf-quant-finance
- Repository: https://github.com/google/tf-quant-finance

## Overview

##### Project Type and Purpose
- Type: Open-source, modular Python library built on TensorFlow.
- Purpose: Provide three tiers of functionality for quantitative finance:
– **Foundational** (core math, random, optimization)
– **Mid-level** (PDE/ODE solvers, Ito processes, diffusion generators)
– **Pricing** (specific models—Black-Scholes, Hull-White, Heston, SABR, rate-curve builders, calibration)
- Packaging and tooling: Bazel BUILD files, pip packaging via setup.py, CI/CD (ci_build).

##### File Structure
- Top-level directories:
– `tf_quant_finance/` (library code)
– `api_docs/` (generated markdown documentation)
– `tf_quant_finance/examples/` (demos & notebooks)
– `tf_quant_finance/experimental/` (experimental modules & pricing platform framework)
– `ci_build/` (Docker/Cloud Build configs)
– `third_party/sobol_data/` (quasi-random seeds)
- Build tooling: Bazel `BUILD` files peppered in modules; `WORKSPACE`; `setup.py`; `build_pip_pkg.sh`.
- Core dependencies: TensorFlow (>=2.7), TensorFlow Probability, NumPy, attrs, dataclasses.

##### README for Additional Insights
- Project is arranged in three tiers (foundational → mid → pricing).
- Examples & notebooks illustrate usage at each tier.
- Development uses Bazel for builds/tests, pip for distribution.
- CI configured via `ci_build/` Dockerfile and Cloud Build YAML.

##### Main Components & Their Relationships
a. **Core/Foundation Layer**
– Modules: `tf_quant_finance/math`, `tf_quant_finance/utils`, `tf_quant_finance/types`, `tf_quant_finance/datetime`.
– Functions: random number generation, integration, interpolation, root search, dataclass utilities, date conventions.
b. **Mid-Level Layer**
– Modules: `tf_quant_finance/models` (Ito processes, SDE sampling), `tf_quant_finance/rates` (curve builders, swaps analytics), `tf_quant_finance/math/pde`.
– Leverages core for numerical routines and TensorFlow‘s autodiff.
c. **Pricing/High-Level Layer**
– Modules: `tf_quant_finance/black_scholes`, plus experimental subpackages for instruments & platform.
– Provides model-specific pricing, calibrations, payoffs.
d. **Examples & Demos**
– Jupyter notebooks under `tf_quant_finance/examples/jupyter_notebooks`.
– Dockerized microservices for data generation, downloaders, pricers under `tf_quant_finance/examples/demos`.
e. **Documentation**
– Static API docs in `api_docs/`.
f. **Build & CI/CD**
– Bazel build system (`BUILD`, `WORKSPACE`).
– Packaging scripts (`build_pip_pkg.sh`, `setup.py`).
– CI config (`ci_build/Dockerfile`, `ci_build/cloudbuild.yaml`).
g. **External Dependencies & Services**
– TensorFlow, TensorFlow Probability, NumPy.
– GitHub for source; PyPI for distribution; Google Cloud Storage for build status badges.

##### Architectural Patterns & Design Principles
- **Layered Architecture**: clear separation Foundation → Mid-Level → Pricing.
- **Modularization**: each financial model or method lives in its own package/subdirectory with its own BUILD file and tests.
- **Dependency Injection** (via TensorFlow ops and Python imports) to maintain loose coupling.
- **Automated Build/Test**: Bazel orchestrates compilation and unit tests; CI/CD triggers on Git.
- **Extensibility**: Experimental folder for WIP features and pricing platform framework.

- Math
- Utils & Types
- Datetime
- third_party/sobol_data
##### Middle row (Mid-Level – blue)
- Models (Ito, Heston, SABR…)
- Rates (curve builders, analytics)
- PDE/ODE Solvers
##### Top row (Pricing – purple)
- Black-Scholes
- Experimental Pricing Platform & Instruments
##### Side blocks
- API Docs (orange) → overlays all modules
##### Tooling/CI (gray)
- Bazel Build
- Packaging (pip wheel)
- CI/CD (Docker, Cloud Build)
##### External (red/cloud)
- TensorFlow, TFP, NumPy
- GitHub, PyPI, GCS (build badges)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Foundation Layer
    subgraph "Foundation Layer"
        math["Core Math Module"]:::foundation
        utils["Utils & Types"]:::foundation
        datetime["Datetime Module"]:::foundation
        sobol["Quasi-Random Sobol Data"]:::foundation
    end

    %% Mid-Level Layer
    subgraph "Mid-Level Layer"
        pde["PDE/ODE Solvers"]:::mid
        models["Ito Process & SDE Sampling"]:::mid
        rates["Rates & Curve Builders"]:::mid
    end

    %% Pricing Layer
    subgraph "Pricing Layer"
        bs["Black-Scholes Pricing"]:::pricing
        exp_platform["Experimental Pricing Platform"]:::pricing
        exp_instruments["Experimental Instruments"]:::pricing
        exp_american["Experimental American Option Pricing"]:::pricing
    end

    %% Examples & Documentation
    subgraph "Examples & Demos"
        demos["Dockerized Demos"]:::examples
        notebooks["Jupyter Notebook Examples"]:::examples
    end
    docs["API Documentation"]:::examples

    %% Tooling & CI/CD
    subgraph "Tooling & CI/CD"
        bazel["Bazel Build System"]:::tooling
        packaging["Pip Packaging"]:::tooling
        cicd["CI/CD Configuration"]:::tooling
    end

    %% External Dependencies & Services
    github["GitHub"]:::external
    pypi["PyPI"]:::external
    gcs["Google Cloud Storage"]:::external
    tfdep["TensorFlow"]:::external
    tfp["TensorFlow Probability"]:::external
    numpy["NumPy"]:::external

    %% Dependencies Arrows
    tfdep -->|">=2.7"| math
    tfp -->|">=0.12.1"| math
    numpy --> math

    math -->|imports| pde
    math -->|imports| models
    math -->|imports| rates
    utils -->|imports| models
    datetime -->|imports| rates
    sobol -->|used by| pde

    pde -->|used by| bs
    models -->|used by| bs
    rates -->|used by| bs

    models -->|extends| exp_platform
    rates -->|extends| exp_platform
    bs -->|base for| exp_instruments
    exp_instruments -->|specializes| exp_american

    demos -->|demonstrates| models
    demos -->|demonstrates| bs
    notebooks -->|illustrates| math
    notebooks -->|illustrates| bs

    docs -->|documents| math
    docs -->|documents| pde
    docs -->|documents| bs

    github -->|push triggers| bazel
    bazel -->|builds/tests| packaging
    packaging -->|publishes| pypi
    bazel -->|runs| cicd
    cicd -->|stores badges| gcs

    %% Click Events
    click math "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/math/"
    click utils "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/utils/"
    click datetime "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/datetime/"
    click sobol "https://github.com/google/tf-quant-finance/tree/master/third_party/sobol_data/"
    click pde "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/math/pde/"
    click models "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/models/"
    click rates "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/rates/"
    click bs "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/black_scholes/"
    click exp_platform "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/experimental/pricing_platform/"
    click exp_instruments "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/experimental/instruments/"
    click exp_american "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/experimental/american_option_pricing/"
    click demos "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/examples/demos/"
    click notebooks "https://github.com/google/tf-quant-finance/tree/master/tf_quant_finance/examples/jupyter_notebooks/"
    click docs "https://github.com/google/tf-quant-finance/tree/master/api_docs/"
    click packaging "https://github.com/google/tf-quant-finance/blob/master/setup.py"
    click cicd "https://github.com/google/tf-quant-finance/tree/master/ci_build/Dockerfile"

    %% Styles
    classDef foundation fill:#e6ffe6,stroke:#0f0
    classDef mid fill:#e6f0ff,stroke:#00f
    classDef pricing fill:#f0e6ff,stroke:#a0f
    classDef examples fill:#fff0e6,stroke:#f60
    classDef tooling fill:#f2f2f2,stroke:#888
    classDef external fill:#ffe6e6,stroke:#f00
```
