# aryan9-6-5/neural-volatility-forecaster architecture

> Architecture diagram of the GitHub repository aryan9-6-5/neural-volatility-forecaster, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/aryan9-6-5/neural-volatility-forecaster
- Repository: https://github.com/aryan9-6-5/neural-volatility-forecaster

## Overview

The repository is an implied-volatility-surface forecasting platform. Its main workflow turns options-chain data into standardized surface sequences, trains and evaluates forecasting models, then serves forecasts and drift status through an API and interactive interface. The graph includes documented baseline, statistical-comparison, quality-reporting, and visualization capabilities. Some subsystems are included from the README and source index; their internal behavior and connections are not inferred where excerpts do not show them.

Main entry points: [`inference/app.py`](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/app.py) (Forecast API), [`training/train.py`](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/training/train.py) (Training & Benchmarking), [`data/dataset.py`](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/dataset.py) (Dataset Builder), [`data/processor.py`](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/processor.py) (Surface Processor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Market Data"]
  node_collector["Snapshot Collector<br/>[collector.py]"]
  node_processor["Surface Processor<br/>[processor.py]"]
  node_dataset["Dataset Builder<br/>[dataset.py]"]
  node_quality["Quality Reporting"]
  node_buffer["History Buffer<br/>[rolling_buffer.py]"]
end

subgraph group_ml["Forecasting"]
  node_architectures["Forecast Architectures<br/>[architectures.py]"]
  node_loss["Regularized Loss<br/>[loss.py]"]
  node_baselines["Econometric Baselines<br/>[baselines.py]"]
  node_training["Training &amp; Benchmarking<br/>[train.py]"]
  node_serialization["Checkpoint Serialization<br/>[serialization.py]"]
end

subgraph group_serve["Serving"]
  node_api["Forecast API<br/>[app.py]"]
  node_predictions[("Prediction Store")]
  node_monitor["Drift Monitor<br/>[monitor.py]"]
  node_ui["Interactive Interface"]
end

subgraph group_analysis["Evaluation &amp; Visualization"]
  node_stats["Significance Tests"]
  node_plots["Forecast Visualizations<br/>[plotting.py]"]
end

node_user(("Options User"))
node_market["Options Market Data"]

node_market -->|"provides snapshots"| node_collector
node_collector -.->|"collects for processing"| node_processor
node_processor -->|"builds surfaces"| node_dataset
node_dataset -->|"processes snapshots"| node_processor
node_dataset -->|"reports quality"| node_quality
node_api -->|"processes input"| node_processor
node_api -->|"builds sequences"| node_dataset
node_api -->|"updates history"| node_buffer
node_training -->|"loads data"| node_dataset
node_training -->|"trains models"| node_architectures
node_training -->|"optimizes with"| node_loss
node_training -->|"benchmarks against"| node_baselines
node_training -->|"saves checkpoints"| node_serialization
node_api -->|"runs forecasts"| node_architectures
node_api -->|"loads checkpoint"| node_serialization
node_api -->|"stores forecasts"| node_predictions
node_api -->|"checks drift"| node_monitor
node_api -->|"generates plots"| node_plots
node_api -.->|"triggers retraining"| node_training
node_user -->|"requests forecast"| node_api
node_api -->|"serves interface"| node_ui
node_training -.->|"supplies predictions"| node_stats

click node_collector "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/collector.py"
click node_processor "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/processor.py"
click node_dataset "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/dataset.py"
click node_quality "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/historical_quality_report.py"
click node_buffer "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/rolling_buffer.py"
click node_architectures "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/architectures.py"
click node_loss "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/loss.py"
click node_baselines "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/baselines.py"
click node_training "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/training/train.py"
click node_serialization "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/serialization.py"
click node_api "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/app.py"
click node_predictions "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/prediction_store.py"
click node_monitor "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/monitor.py"
click node_ui "https://github.com/aryan9-6-5/neural-volatility-forecaster/tree/main/inference/static"
click node_stats "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/training/significance_tests.py"
click node_plots "https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/utils/plotting.py"

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_collector,node_processor,node_dataset,node_quality,node_buffer,node_user toneBlue
class node_architectures,node_loss,node_baselines,node_training,node_serialization toneAmber
class node_api,node_predictions,node_monitor,node_ui toneMint
class node_stats,node_plots toneRose
class node_market toneIndigo
```

## Components

### Market Data

- [Snapshot Collector](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/collector.py): `data/collector.py`
- [Surface Processor](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/processor.py): `data/processor.py`
- [Dataset Builder](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/dataset.py): `data/dataset.py`
- [Quality Reporting](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/historical_quality_report.py): `data/historical_quality_report.py`
- [History Buffer](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/data/rolling_buffer.py): `data/rolling_buffer.py`

### Forecasting

- [Forecast Architectures](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/architectures.py): `models/architectures.py`
- [Regularized Loss](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/loss.py): `models/loss.py`
- [Econometric Baselines](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/baselines.py): `models/baselines.py`
- [Training & Benchmarking](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/training/train.py): `training/train.py`
- [Checkpoint Serialization](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/models/serialization.py): `models/serialization.py`

### Serving

- [Forecast API](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/app.py): `inference/app.py`
- [Prediction Store](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/prediction_store.py): `inference/prediction_store.py`
- [Drift Monitor](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/inference/monitor.py): `inference/monitor.py`
- [Interactive Interface](https://github.com/aryan9-6-5/neural-volatility-forecaster/tree/main/inference/static): `inference/static`

### Evaluation & Visualization

- [Significance Tests](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/training/significance_tests.py): `training/significance_tests.py`
- [Forecast Visualizations](https://github.com/aryan9-6-5/neural-volatility-forecaster/blob/main/utils/plotting.py): `utils/plotting.py`

### Other components

- **Options User**
- **Options Market Data**

## Connections

- Options Market Data → Snapshot Collector: provides snapshots (evidence: `README.md`)
- Snapshot Collector → Surface Processor: collects for processing
- Surface Processor → Dataset Builder: builds surfaces (evidence: `data/dataset.py`)
- Dataset Builder → Surface Processor: processes snapshots (evidence: `data/dataset.py`)
- Dataset Builder → Quality Reporting: reports quality (evidence: `data/historical_quality_report.py`)
- Forecast API → Surface Processor: processes input (evidence: `inference/app.py`)
- Forecast API → Dataset Builder: builds sequences (evidence: `inference/app.py`)
- Forecast API → History Buffer: updates history (evidence: `inference/app.py`)
- Training & Benchmarking → Dataset Builder: loads data (evidence: `training/train.py`)
- Training & Benchmarking → Forecast Architectures: trains models (evidence: `training/train.py`)
- Training & Benchmarking → Regularized Loss: optimizes with (evidence: `training/train.py`)
- Training & Benchmarking → Econometric Baselines: benchmarks against (evidence: `training/train.py`)
- Training & Benchmarking → Checkpoint Serialization: saves checkpoints (evidence: `training/train.py`)
- Forecast API → Forecast Architectures: runs forecasts (evidence: `inference/app.py`)
- Forecast API → Checkpoint Serialization: loads checkpoint (evidence: `inference/app.py`)
- Forecast API → Prediction Store: stores forecasts (evidence: `inference/app.py`)
- Forecast API → Drift Monitor: checks drift (evidence: `inference/app.py`)
- Forecast API → Forecast Visualizations: generates plots (evidence: `inference/app.py`)
- Forecast API → Training & Benchmarking: triggers retraining (evidence: `inference/app.py`)
- Options User → Forecast API: requests forecast (evidence: `README.md`)
- Forecast API → Interactive Interface: serves interface (evidence: `README.md`)
- Training & Benchmarking → Significance Tests: supplies predictions
