# thakur-sahab-01/suryanet-ai-v2 architecture

> Architecture diagram of the GitHub repository thakur-sahab-01/suryanet-ai-v2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thakur-sahab-01/suryanet-ai-v2
- Repository: https://github.com/thakur-sahab-01/suryanet-ai-v2

## Overview

1. **Repo shape**
   - This is a three-runtime system: a **Python backend** for data ingestion/inference, a **React/TypeScript dashboard** for visualization and operator interaction, and a **C++/CUDA/TensorRT edge path** for GPU inference acceleration.
   - The root `models/` directory holds deployed artifacts; `python/scripts/` and `python/models/` are the training and model-definition side; `dashboard/` is the client side.

2. **Primary runtime: Python API**
   - The main service is `python/api/server.py`, a **FastAPI** application exposed over HTTP and WebSocket.
   - It acts as the orchestration layer: loads the inference model, fetches live GOES data, assembles predictions, serves explainability outputs, and returns satellite-risk and copilot responses to the UI.

3. **Data ingestion boundary**
   - Live input comes from **NOAA GOES public JSON feeds** via `python/data/goes_fetcher.py`; this is the only clearly external live data dependency.
   - Historical/offline solar data is handled separately through `python/data/solexs_loader.py`, `hel1os_loader.py`, and `preprocessor.py`, which convert FITS/ZIP sources into processed tabular/time-series formats used for training and alignment.

4. **Offline preprocessing and dataset generation**
   - The offline pipeline is distinct from runtime inference: scripts under `python/scripts/` process batch data, train models, and export artifacts.
   - `process_solexs_batch.py`, `process_hel1os_batch.py`, and `train_deep.py`/`train_legacy.py` suggest a separation between **data engineering**, **model training**, and **deployment artifact generation**.

5. **Model layer split**
   - The architecture has two independent model paths under `python/models/`:
     - **Deep learning** (`deep/model.py`, `dataset.py`, `loss.py`) for the ONNX-exported model.
     - **Legacy/traditional ML** (`legacy/`) for anomaly detection, flare classification, and forecasting.
   - `ensemble_v2.py` is the fusion boundary that combines both paths into the final risk output.

6. **Deployed model artifacts**
   - The `models/` directory contains the runtime artifacts consumed by the backend: `suryanet.onnx` plus external weights, and legacy model files such as `flare_classifier.json`.
   - This indicates the production inference path is designed to be **artifact-driven**, not trained in place.

7. **Inference outputs and scoring**
   - The API returns multi-horizon flare probabilities, class-specific probabilities, and a final ensemble risk score with a risk level.
   - The ensemble boundary is explicit: deep learning contributes the main score, while the legacy ML stack provides an auxiliary score that is fused into the final decision.

8. **Explainability subsystem**
   - `python/explainability/` contains both **SHAP** and **Integrated Gradients** implementations.
   - This is a separate explanation plane attached to the model API, not embedded in the dashboard logic; the frontend just renders the returned explanations.

9. **Copilot subsystem**
   - `python/copilot/agent.py` and `knowledge.py` implement a bilingual Hindi/English assistant.
   - It is a distinct query/response service that can optionally use a Hugging Face LLM token, with a local knowledge base fallback, and is exposed through the `/copilot` API.

10. **Frontend presentation layer**
   - `dashboard/` is a **Vite + React + TypeScript** application.
   - `src/hooks/usePredictions.ts` is the main data-access layer to the backend; `src/components/` is organized by visualization responsibility: GOES flux, probability charts, class breakdowns, risk gauge, satellite matrix, model card, alert banner, and copilot chat.

11. **Dashboard-to-backend data flow**
   - The dashboard is a consumer only: it pulls prediction/state data from the FastAPI endpoints and listens to the WebSocket stream for live updates.
   - The UI is structured around four operational views: live monitoring, forecast charts, satellite risk, and AI copilot.

12. **Edge inference boundary**
   - The `cpp/include/suryanet/` headers define a separate deployment path for **TensorRT/CUDA** inference, preprocessing, and server plumbing.
   - Because only headers are present in the tree, this looks like an accelerator/runtime boundary rather than the main application path; it likely mirrors the Python inference behavior for GPU/edge deployment.

13. **Deployment and packaging**
   - `docker/` contains separate images for the API, dashboard, and CUDA runtime, with `docker-compose.yml` wiring them together.
   - `run.bat` provides a Windows bootstrap path, so the repo supports both local development and containerized deployment.

14. **Storage and state**
   - There is no external database dependency in the architecture.
   - Persistent assets are file-based model/data artifacts, while live GOES feeds and recent alerts are kept in server memory/cache, which keeps the runtime stateless aside from local files.

15. **What to show in an architecture diagram**
   - The key diagram boundaries are: **external NOAA feeds → Python data pipeline → model ensemble → FastAPI/WebSocket → React dashboard**, with side branches for **explainability**, **copilot**, and **C++/TensorRT acceleration**.
   - The offline training/export path should be shown as separate from the live inference path, feeding the artifact store in `models/`.

Main entry points: [`python/api/server.py`](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/api/server.py) (API server), [`models/suryanet.onnx`](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/models/suryanet.onnx) (Model files), [`python/models/ensemble_v2.py`](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/ensemble_v2.py) (Ensemble), [`dashboard/src/hooks/usePredictions.ts`](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/hooks/usePredictions.ts) (Predictions hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_external["External Inputs"]
  node_goes_feed[("GOES feed<br/>NOAA JSON source")]
end

subgraph group_python["Python Backend"]
  node_api_server["API server<br/>FastAPI app<br/>[server.py]"]
  node_goes_fetcher["GOES fetcher<br/>live ingestion<br/>[goes_fetcher.py]"]
  node_preprocess["Preprocess<br/>runtime prep<br/>[preprocessor.py]"]
  node_ensemble["Ensemble<br/>fusion layer<br/>[ensemble_v2.py]"]
  node_deep_model["Deep model<br/>ONNX path<br/>[model.py]"]
  node_legacy_models["Legacy ML<br/>traditional ML<br/>[ensemble.py]"]
  node_explainability["Explainability<br/>SHAP and IG<br/>[shap_explainer.py]"]
  node_copilot["Copilot<br/>bilingual agent<br/>[agent.py]"]
end

subgraph group_offline["Offline Training"]
  node_train_scripts["Training scripts<br/>batch pipeline<br/>[train_deep.py]"]
  node_data_loaders["Data loaders<br/>offline ETL<br/>[solexs_loader.py]"]
  node_export_onnx["Export ONNX<br/>artifact export<br/>[export_to_onnx.py]"]
end

subgraph group_dashboard["Dashboard"]
  node_dashboard_ui["Dashboard<br/>Vite React UI<br/>[App.tsx]"]
  node_predictions_hook["Predictions hook<br/>UI data client<br/>[usePredictions.ts]"]
  node_dashboard_charts["Charts<br/>visual components<br/>[GOESFluxChart.tsx]"]
  node_dashboard_copilot["Copilot panel<br/>chat component<br/>[AICopilot.tsx]"]
end

subgraph group_edge["Edge Runtime"]
  node_cuda_headers["CUDA runtime<br/>C++ accel"]
  node_inference_server["Edge server<br/>C++ runtime"]
end

subgraph group_artifacts["Model Artifacts"]
  node_artifact_store[("Model files<br/>deployed artifacts<br/>[suryanet.onnx]")]
  node_legacy_flare["Flare model<br/>legacy classifier"]
end

node_goes_feed -->|"live feed"| node_goes_fetcher
node_goes_fetcher -->|"raw data"| node_preprocess
node_preprocess -->|"features"| node_ensemble
node_ensemble -->|"deep score"| node_deep_model
node_ensemble -->|"aux score"| node_legacy_models
node_deep_model -->|"loads"| node_artifact_store
node_legacy_models -->|"loads"| node_artifact_store
node_artifact_store -->|"model load"| node_api_server
node_api_server -->|"HTTP/WebSocket"| node_dashboard_ui
node_dashboard_ui -->|"uses"| node_predictions_hook
node_predictions_hook -->|"feeds"| node_dashboard_charts
node_predictions_hook -->|"feeds"| node_dashboard_copilot
node_api_server -->|"explanations"| node_explainability
node_api_server -->|"/copilot"| node_copilot
node_train_scripts -->|"batch data"| node_data_loaders
node_train_scripts -->|"exports"| node_export_onnx
node_export_onnx -->|"writes"| node_artifact_store
node_data_loaders -->|"datasets"| node_train_scripts
node_cuda_headers -->|"accelerated path"| node_inference_server
node_inference_server -.->|"optional accel"| node_api_server
node_legacy_flare -->|"class model"| node_legacy_models

click node_dashboard_ui "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/App.tsx"
click node_predictions_hook "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/hooks/usePredictions.ts"
click node_dashboard_charts "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/components/GOESFluxChart.tsx"
click node_dashboard_copilot "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/components/AICopilot.tsx"
click node_api_server "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/api/server.py"
click node_goes_fetcher "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/goes_fetcher.py"
click node_preprocess "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/preprocessor.py"
click node_ensemble "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/ensemble_v2.py"
click node_deep_model "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/deep/model.py"
click node_legacy_models "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/legacy/ensemble.py"
click node_explainability "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/explainability/shap_explainer.py"
click node_copilot "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/copilot/agent.py"
click node_train_scripts "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/scripts/train_deep.py"
click node_data_loaders "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/solexs_loader.py"
click node_export_onnx "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/scripts/export_to_onnx.py"
click node_artifact_store "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/models/suryanet.onnx"
click node_cuda_headers "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/cpp/include/suryanet/tensorrt_engine.hpp"
click node_inference_server "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/cpp/include/suryanet/inference_server.hpp"
click node_legacy_flare "https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/models/flare_classifier.json"

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_goes_feed toneBlue
class node_api_server,node_goes_fetcher,node_preprocess,node_ensemble,node_deep_model,node_legacy_models,node_explainability,node_copilot toneAmber
class node_train_scripts,node_data_loaders,node_export_onnx toneMint
class node_dashboard_ui,node_predictions_hook,node_dashboard_charts,node_dashboard_copilot toneRose
class node_cuda_headers,node_inference_server toneIndigo
class node_artifact_store,node_legacy_flare toneTeal
```

## Components

### External Inputs

Outside data and client consumers

- **GOES feed**: NOAA JSON source · Public NOAA GOES live feed consumed by the backend

### Python Backend

Live API, data ingestion, inference, explainability, and copilot services

- [API server](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/api/server.py): FastAPI app · HTTP and WebSocket orchestration layer for live inference and UI responses · `python/api/server.py`
- [GOES fetcher](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/goes_fetcher.py): live ingestion · Fetches live NOAA GOES data for runtime inference · `python/data/goes_fetcher.py`
- [Preprocess](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/preprocessor.py): runtime prep · Aligns and prepares incoming data for inference · `python/data/preprocessor.py`
- [Ensemble](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/ensemble_v2.py): fusion layer · Combines deep and legacy model outputs into final risk scoring · `python/models/ensemble_v2.py`
- [Deep model](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/deep/model.py): ONNX path · Deep learning inference path backing the main score · `python/models/deep/model.py`
- [Legacy ML](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/models/legacy/ensemble.py): traditional ML · Auxiliary anomaly, flare, and forecast models · `python/models/legacy/ensemble.py`
- [Explainability](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/explainability/shap_explainer.py): SHAP and IG · Produces model explanations returned by the API · `python/explainability/shap_explainer.py`
- [Copilot](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/copilot/agent.py): bilingual agent · Hindi/English assistant with knowledge base and optional HF LLM · `python/copilot/agent.py`

### Offline Training

Batch processing, model training, and export pipeline

- [Training scripts](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/scripts/train_deep.py): batch pipeline · Processes datasets, trains models, and exports runtime artifacts · `python/scripts/train_deep.py`
- [Data loaders](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/data/solexs_loader.py): offline ETL · Converts SOLExS and HEL1OS sources into processed training data · `python/data/solexs_loader.py`
- [Export ONNX](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/python/scripts/export_to_onnx.py): artifact export · Exports trained deep models to deployable ONNX artifacts · `python/scripts/export_to_onnx.py`

### Dashboard

React/TypeScript operator UI

- [Dashboard](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/App.tsx): Vite React UI · Operator interface for monitoring, charts, and copilot · `dashboard/src/App.tsx`
- [Predictions hook](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/hooks/usePredictions.ts): UI data client · Main dashboard data-access layer for backend predictions and stream updates · `dashboard/src/hooks/usePredictions.ts`
- [Charts](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/components/GOESFluxChart.tsx): visual components · Flux, probability, class, risk, and satellite visualizations · `dashboard/src/components/GOESFluxChart.tsx`
- [Copilot panel](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/dashboard/src/components/AICopilot.tsx): chat component · Frontend surface for AI copilot responses · `dashboard/src/components/AICopilot.tsx`

### Edge Runtime

C++/CUDA/TensorRT acceleration boundary

- [CUDA runtime](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/cpp/include/suryanet/tensorrt_engine.hpp): C++ accel · TensorRT/CUDA inference, preprocessing, and server plumbing headers · `cpp/include/suryanet/tensorrt_engine.hpp`
- [Edge server](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/cpp/include/suryanet/inference_server.hpp): C++ runtime · Edge inference server boundary for accelerated deployment · `cpp/include/suryanet/inference_server.hpp`

### Model Artifacts

Deployed files consumed by inference

- [Model files](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/models/suryanet.onnx): deployed artifacts · Runtime ONNX and legacy model files loaded by the backend · `models/suryanet.onnx`
- [Flare model](https://github.com/thakur-sahab-01/suryanet-ai-v2/blob/master/models/flare_classifier.json): legacy classifier · Representative legacy artifact used in production scoring · `models/flare_classifier.json`

## Connections

- GOES feed → GOES fetcher: live feed · Runtime NOAA input
- GOES fetcher → Preprocess: raw data · Fetch output is normalized for inference
- Preprocess → Ensemble: features · Prepared runtime features enter scoring
- Ensemble → Deep model: deep score · Primary deep-learning inference path
- Ensemble → Legacy ML: aux score · Legacy model outputs contribute to fusion
- Deep model → Model files: loads · Deep runtime artifacts are consumed from files
- Legacy ML → Model files: loads · Legacy runtime artifacts are consumed from files
- Model files → API server: model load · Backend loads deployed artifacts at runtime
- API server → Dashboard: HTTP/WebSocket · Serves predictions and live updates to the UI
- Dashboard → Predictions hook: uses · UI data flow is centralized in the predictions hook
- Predictions hook → Charts: feeds · Prediction state drives monitoring and forecast views
- Predictions hook → Copilot panel: feeds · Copilot panel consumes API responses
- API server → Explainability: explanations · Backend attaches model explanations to responses
- API server → Copilot: /copilot · Dedicated assistant endpoint and response flow
- Training scripts → Data loaders: batch data · Training pipeline starts from offline source processing
- Training scripts → Export ONNX: exports · Training produces deployable ONNX artifacts
- Export ONNX → Model files: writes · Exported model files are placed in the artifact store
- Data loaders → Training scripts: datasets · Processed historical data feeds model training
- CUDA runtime → Edge server: accelerated path · Headers define the GPU/edge inference boundary
- Edge server → API server: optional accel · Edge deployment mirrors backend inference behavior
- Flare model → Legacy ML: class model · Representative deployed legacy model artifact
