# grevix/kuwala architecture

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

- Interactive diagram: https://gitdiagram.com/grevix/kuwala
- Repository: https://github.com/grevix/kuwala

## Overview

Kuwala is a quantitative options and volatility research library. A principal workflow fetches market data through provider adapters, cleans and models option chains, derives implied volatility and surfaces, then supports pricing, arbitrage checks, and research signals. Separate capabilities include curve and forward construction, microstructure analysis, partitioned storage, backtesting, and leakage-aware validation. Numerical kernels are implemented in Python with an optional Rust core, alongside documented C++, Scala, and Julia engines. Unsampled modules are included where README or the source index establishes their roles; their internal call paths are not inferred.

Main entry points: [`kuwala/data/pipeline.py`](https://github.com/grevix/kuwala/blob/main/kuwala/data/pipeline.py) (Data pipeline), [`kuwala/volatility/surface.py`](https://github.com/grevix/kuwala/blob/main/kuwala/volatility/surface.py) (Volatility surface), [`kuwala/data/models.py`](https://github.com/grevix/kuwala/blob/main/kuwala/data/models.py) (Option data models), [`kuwala_core/src/lib.rs`](https://github.com/grevix/kuwala/blob/main/kuwala_core/src/lib.rs) (Rust numerical core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_market["Market Data"]
  node_pipeline["Data pipeline<br/>[pipeline.py]"]
  node_yahoo["Yahoo adapter<br/>[yahoo.py]"]
  node_fred["FRED adapter<br/>[fred.py]"]
  node_other_adapters["Other adapters"]
  node_models["Option data models<br/>[models.py]"]
  node_curves["Yield curves<br/>[curves.py]"]
  node_forwards["Forward curves<br/>[forward.py]"]
  node_microstructure["Microstructure<br/>[microstructure.py]"]
  node_store[("Parquet lakehouse<br/>[store.py]")]
end

subgraph group_quant["Pricing &amp; Volatility"]
  node_pricing["Black pricing<br/>[black_scholes.py]"]
  node_greeks["Option Greeks<br/>[greeks.py]"]
  node_iv["IV inversion<br/>[iv.py]"]
  node_ssvi["SSVI fitting<br/>[ssvi.py]"]
  node_surface["Volatility surface<br/>[surface.py]"]
  node_localvol["Local volatility<br/>[local_vol.py]"]
  node_diagnostics["Arbitrage diagnostics<br/>[arbitrage.py]"]
  node_diagnostic_report["Diagnostic reports<br/>[report.py]"]
end

subgraph group_research["Signals &amp; Research"]
  node_signals["Signals &amp; indicators"]
  node_validation["Signal validation<br/>[validation.py]"]
  node_backtest["Backtesting"]
end

subgraph group_engines["Numerical Engines"]
  node_rust["Rust numerical core<br/>[lib.rs]"]
  node_rust_pricing["Rust pricing kernels<br/>[pricing.rs]"]
  node_rust_greeks["Rust Greeks<br/>[greeks.rs]"]
  node_cpp_pricing["C++ pricing<br/>[pricing.hpp]"]
  node_cpp_greeks["C++ Greeks<br/>[greeks.hpp]"]
  node_scala_pricing["Scala pricing<br/>[BlackScholes.scala]"]
  node_scala_greeks["Scala Greeks<br/>[Greeks.scala]"]
  node_arrow["Arrow bridge<br/>[ArrowBridge.scala]"]
end

node_researcher(("Quant researcher"))
node_market_sources(("Market sources"))

node_researcher -.->|"requests data"| node_pipeline
node_pipeline -->|"dispatches"| node_yahoo
node_pipeline -->|"dispatches"| node_fred
node_pipeline -->|"dispatches"| node_other_adapters
node_pipeline -->|"uses models"| node_models
node_yahoo -->|"fetches quotes"| node_market_sources
node_fred -.->|"fetches data"| node_market_sources
node_pipeline -.->|"stores data"| node_store
node_pipeline -.->|"extracts IV"| node_iv
node_models -.->|"supports curves"| node_curves
node_models -.->|"supports forwards"| node_forwards
node_market_sources -.->|"provides ticks"| node_microstructure
node_researcher -.->|"researches options"| node_pricing
node_pricing -->|"uses optional core"| node_rust
node_greeks -->|"uses optional core"| node_rust
node_iv -->|"reprices options"| node_pricing
node_surface -->|"consumes data"| node_models
node_surface -->|"uses inversion"| node_iv
node_surface -->|"uses calibration"| node_ssvi
node_surface -->|"extracts local vol"| node_localvol
node_surface -->|"checks arbitrage"| node_diagnostics
node_surface -->|"calculates Greeks"| node_greeks
node_diagnostics -->|"builds reports"| node_diagnostic_report
node_researcher -.->|"develops signals"| node_signals
node_signals -.->|"validates signals"| node_validation
node_signals -.->|"tests strategies"| node_backtest
node_rust -->|"exports kernels"| node_rust_pricing
node_rust -->|"exports kernels"| node_rust_greeks
node_rust_greeks -->|"calls pricing"| node_rust_pricing
node_scala_greeks -->|"uses pricing"| node_scala_pricing
node_arrow -.->|"maps quotes"| node_models

click node_pipeline "https://github.com/grevix/kuwala/blob/main/kuwala/data/pipeline.py"
click node_yahoo "https://github.com/grevix/kuwala/blob/main/kuwala/data/adapters/yahoo.py"
click node_fred "https://github.com/grevix/kuwala/blob/main/kuwala/data/adapters/fred.py"
click node_other_adapters "https://github.com/grevix/kuwala/tree/main/kuwala/data/adapters"
click node_models "https://github.com/grevix/kuwala/blob/main/kuwala/data/models.py"
click node_curves "https://github.com/grevix/kuwala/blob/main/kuwala/data/curves.py"
click node_forwards "https://github.com/grevix/kuwala/blob/main/kuwala/data/forward.py"
click node_microstructure "https://github.com/grevix/kuwala/blob/main/kuwala/data/microstructure.py"
click node_store "https://github.com/grevix/kuwala/blob/main/kuwala/data/store.py"
click node_pricing "https://github.com/grevix/kuwala/blob/main/kuwala/pricing/black_scholes.py"
click node_greeks "https://github.com/grevix/kuwala/blob/main/kuwala/pricing/greeks.py"
click node_iv "https://github.com/grevix/kuwala/blob/main/kuwala/volatility/iv.py"
click node_ssvi "https://github.com/grevix/kuwala/blob/main/kuwala/volatility/ssvi.py"
click node_surface "https://github.com/grevix/kuwala/blob/main/kuwala/volatility/surface.py"
click node_localvol "https://github.com/grevix/kuwala/blob/main/kuwala/volatility/local_vol.py"
click node_diagnostics "https://github.com/grevix/kuwala/blob/main/kuwala/diagnostics/arbitrage.py"
click node_diagnostic_report "https://github.com/grevix/kuwala/blob/main/kuwala/diagnostics/report.py"
click node_signals "https://github.com/grevix/kuwala/tree/main/kuwala/signals"
click node_validation "https://github.com/grevix/kuwala/blob/main/kuwala/signals/validation.py"
click node_backtest "https://github.com/grevix/kuwala/tree/main/kuwala/backtest"
click node_rust "https://github.com/grevix/kuwala/blob/main/kuwala_core/src/lib.rs"
click node_rust_pricing "https://github.com/grevix/kuwala/blob/main/kuwala_core/src/pricing.rs"
click node_rust_greeks "https://github.com/grevix/kuwala/blob/main/kuwala_core/src/greeks.rs"
click node_cpp_pricing "https://github.com/grevix/kuwala/blob/main/kuwala_cpp/include/kuwala_cpp/pricing.hpp"
click node_cpp_greeks "https://github.com/grevix/kuwala/blob/main/kuwala_cpp/include/kuwala_cpp/greeks.hpp"
click node_scala_pricing "https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/pricing/BlackScholes.scala"
click node_scala_greeks "https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/pricing/Greeks.scala"
click node_arrow "https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/arrow/ArrowBridge.scala"

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_pipeline,node_yahoo,node_fred,node_other_adapters,node_models,node_curves,node_forwards,node_microstructure,node_store toneBlue
class node_pricing,node_greeks,node_iv,node_ssvi,node_surface,node_localvol,node_diagnostics,node_diagnostic_report toneAmber
class node_signals,node_validation,node_backtest toneMint
class node_rust,node_rust_pricing,node_rust_greeks,node_cpp_pricing,node_cpp_greeks,node_scala_pricing,node_scala_greeks,node_arrow toneRose
class node_researcher,node_market_sources toneIndigo
```

## Components

### Market Data

- [Data pipeline](https://github.com/grevix/kuwala/blob/main/kuwala/data/pipeline.py): `kuwala/data/pipeline.py`
- [Yahoo adapter](https://github.com/grevix/kuwala/blob/main/kuwala/data/adapters/yahoo.py): `kuwala/data/adapters/yahoo.py`
- [FRED adapter](https://github.com/grevix/kuwala/blob/main/kuwala/data/adapters/fred.py): `kuwala/data/adapters/fred.py`
- [Other adapters](https://github.com/grevix/kuwala/tree/main/kuwala/data/adapters): `kuwala/data/adapters`
- [Option data models](https://github.com/grevix/kuwala/blob/main/kuwala/data/models.py): `kuwala/data/models.py`
- [Yield curves](https://github.com/grevix/kuwala/blob/main/kuwala/data/curves.py): `kuwala/data/curves.py`
- [Forward curves](https://github.com/grevix/kuwala/blob/main/kuwala/data/forward.py): `kuwala/data/forward.py`
- [Microstructure](https://github.com/grevix/kuwala/blob/main/kuwala/data/microstructure.py): `kuwala/data/microstructure.py`
- [Parquet lakehouse](https://github.com/grevix/kuwala/blob/main/kuwala/data/store.py): `kuwala/data/store.py`

### Pricing & Volatility

- [Black pricing](https://github.com/grevix/kuwala/blob/main/kuwala/pricing/black_scholes.py): `kuwala/pricing/black_scholes.py`
- [Option Greeks](https://github.com/grevix/kuwala/blob/main/kuwala/pricing/greeks.py): `kuwala/pricing/greeks.py`
- [IV inversion](https://github.com/grevix/kuwala/blob/main/kuwala/volatility/iv.py): `kuwala/volatility/iv.py`
- [SSVI fitting](https://github.com/grevix/kuwala/blob/main/kuwala/volatility/ssvi.py): `kuwala/volatility/ssvi.py`
- [Volatility surface](https://github.com/grevix/kuwala/blob/main/kuwala/volatility/surface.py): `kuwala/volatility/surface.py`
- [Local volatility](https://github.com/grevix/kuwala/blob/main/kuwala/volatility/local_vol.py): `kuwala/volatility/local_vol.py`
- [Arbitrage diagnostics](https://github.com/grevix/kuwala/blob/main/kuwala/diagnostics/arbitrage.py): `kuwala/diagnostics/arbitrage.py`
- [Diagnostic reports](https://github.com/grevix/kuwala/blob/main/kuwala/diagnostics/report.py): `kuwala/diagnostics/report.py`

### Signals & Research

- [Signals & indicators](https://github.com/grevix/kuwala/tree/main/kuwala/signals): `kuwala/signals`
- [Signal validation](https://github.com/grevix/kuwala/blob/main/kuwala/signals/validation.py): `kuwala/signals/validation.py`
- [Backtesting](https://github.com/grevix/kuwala/tree/main/kuwala/backtest): `kuwala/backtest`

### Numerical Engines

- [Rust numerical core](https://github.com/grevix/kuwala/blob/main/kuwala_core/src/lib.rs): `kuwala_core/src/lib.rs`
- [Rust pricing kernels](https://github.com/grevix/kuwala/blob/main/kuwala_core/src/pricing.rs): `kuwala_core/src/pricing.rs`
- [Rust Greeks](https://github.com/grevix/kuwala/blob/main/kuwala_core/src/greeks.rs): `kuwala_core/src/greeks.rs`
- [C++ pricing](https://github.com/grevix/kuwala/blob/main/kuwala_cpp/include/kuwala_cpp/pricing.hpp): `kuwala_cpp/include/kuwala_cpp/pricing.hpp`
- [C++ Greeks](https://github.com/grevix/kuwala/blob/main/kuwala_cpp/include/kuwala_cpp/greeks.hpp): `kuwala_cpp/include/kuwala_cpp/greeks.hpp`
- [Scala pricing](https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/pricing/BlackScholes.scala): `scala/src/main/scala/kuwala/pricing/BlackScholes.scala`
- [Scala Greeks](https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/pricing/Greeks.scala): `scala/src/main/scala/kuwala/pricing/Greeks.scala`
- [Arrow bridge](https://github.com/grevix/kuwala/blob/main/scala/src/main/scala/kuwala/arrow/ArrowBridge.scala): `scala/src/main/scala/kuwala/arrow/ArrowBridge.scala`

### Other components

- **Quant researcher**
- **Market sources**

## Connections

- Quant researcher → Data pipeline: requests data (evidence: `README.md`)
- Data pipeline → Yahoo adapter: dispatches (evidence: `kuwala/data/pipeline.py`)
- Data pipeline → FRED adapter: dispatches (evidence: `kuwala/data/pipeline.py`)
- Data pipeline → Other adapters: dispatches (evidence: `kuwala/data/pipeline.py`)
- Data pipeline → Option data models: uses models (evidence: `kuwala/data/pipeline.py`)
- Yahoo adapter → Market sources: fetches quotes (evidence: `kuwala/data/adapters/yahoo.py`)
- FRED adapter → Market sources: fetches data
- Data pipeline → Parquet lakehouse: stores data (evidence: `README.md`)
- Data pipeline → IV inversion: extracts IV (evidence: `README.md`)
- Option data models → Yield curves: supports curves (evidence: `README.md`)
- Option data models → Forward curves: supports forwards (evidence: `README.md`)
- Market sources → Microstructure: provides ticks (evidence: `README.md`)
- Quant researcher → Black pricing: researches options (evidence: `README.md`)
- Black pricing → Rust numerical core: uses optional core (evidence: `kuwala/pricing/black_scholes.py`)
- Option Greeks → Rust numerical core: uses optional core (evidence: `kuwala/pricing/greeks.py`)
- IV inversion → Black pricing: reprices options (evidence: `kuwala/volatility/iv.py`)
- Volatility surface → Option data models: consumes data (evidence: `kuwala/volatility/surface.py`)
- Volatility surface → IV inversion: uses inversion (evidence: `kuwala/volatility/surface.py`)
- Volatility surface → SSVI fitting: uses calibration (evidence: `kuwala/volatility/surface.py`)
- Volatility surface → Local volatility: extracts local vol (evidence: `kuwala/volatility/surface.py`)
- Volatility surface → Arbitrage diagnostics: checks arbitrage (evidence: `kuwala/volatility/surface.py`)
- Volatility surface → Option Greeks: calculates Greeks (evidence: `kuwala/volatility/surface.py`)
- Arbitrage diagnostics → Diagnostic reports: builds reports (evidence: `kuwala/diagnostics/arbitrage.py`)
- Quant researcher → Signals & indicators: develops signals (evidence: `README.md`)
- Signals & indicators → Signal validation: validates signals (evidence: `README.md`)
- Signals & indicators → Backtesting: tests strategies (evidence: `README.md`)
- Rust numerical core → Rust pricing kernels: exports kernels (evidence: `kuwala_core/src/lib.rs`)
- Rust numerical core → Rust Greeks: exports kernels (evidence: `kuwala_core/src/lib.rs`)
- Rust Greeks → Rust pricing kernels: calls pricing (evidence: `kuwala_core/src/greeks.rs`)
- Scala Greeks → Scala pricing: uses pricing (evidence: `scala/src/main/scala/kuwala/pricing/Greeks.scala`)
- Arrow bridge → Option data models: maps quotes (evidence: `README.md`)
