# mayurkhalse/cycloscope architecture

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

- Interactive diagram: https://gitdiagram.com/mayurkhalse/cycloscope
- Repository: https://github.com/mayurkhalse/cycloscope

## Overview

Cycloscope is a cyclone decision-support platform for North Indian Ocean monitoring, forecasts, historical replay and cyclogenesis risk. Its main workflow runs from satellite observations through ML inference, backend persistence/API, and a React dashboard; a separate grounded chat assistant uses cyclone data and optional Pinecone/Gemini services. The graph emphasizes those product branches and the training/evaluation capability. Some routes and frontend pages are documented but unsampled, so their internal links are limited to explicit wiring or README evidence.

Main entry points: [`ML/serving/app/services/prediction_engine.py`](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/services/prediction_engine.py) (Prediction engine), [`backend/src/services/ragService.js`](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/ragService.js) (Context retrieval and response), [`backend/src/app.js`](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/app.js) (REST application), [`backend/src/controllers/cyclone.controller.js`](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/cyclone.controller.js) (Cyclone API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Operations dashboard"]
  node_dashboard["Dashboard app<br/>[App.jsx]"]
  node_views["Operations views"]
  node_frontend_api["API clients"]
end

subgraph group_api["Backend API"]
  node_backend_app["REST application<br/>[app.js]"]
  node_cyclone_api["Cyclone API"]
  node_prediction_api["Prediction API"]
  node_genesis_api["Genesis API"]
  node_orchestrator["Prediction orchestrator"]
  node_ml_client["ML service client<br/>[mlClient.js]"]
  node_storm_store[("Cyclone records<br/>[Cyclone.js]")]
  node_forecast_store[("Forecast records")]
end

subgraph group_ml["ML inference"]
  node_ml_api["Inference service<br/>[main.py]"]
  node_engine["Prediction engine"]
  node_track_infer["Track inference<br/>[track_infer.py]"]
  node_genesis_infer["Genesis inference"]
  node_models["Model loader<br/>[model_loader.py]"]
end

subgraph group_data["Satellite and science data"]
  node_satellite_repo["Satellite repository"]
  node_sat_providers["Satellite providers"]
  node_preprocess["Live preprocessing"]
  node_training["Model training"]
  node_backtest["Historical backtesting<br/>[backtest_suite.py]"]
end

subgraph group_assistant["Grounded assistant"]
  node_chat_api["Chat controller<br/>[chat.controller.js]"]
  node_rag["Context retrieval and response<br/>[ragService.js]"]
  node_embedding["Embedding service"]
  node_pinecone[("Pinecone index<br/>[pinecone.js]")]
end

node_operator(("Forecaster"))
node_gemini["Gemini service"]

node_operator -->|"uses"| node_dashboard
node_dashboard -->|"routes to"| node_views
node_views -.->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls API"| node_backend_app
node_backend_app -->|"routes requests"| node_cyclone_api
node_backend_app -->|"routes requests"| node_prediction_api
node_backend_app -->|"routes requests"| node_genesis_api
node_cyclone_api -->|"reads"| node_storm_store
node_cyclone_api -->|"reads"| node_forecast_store
node_cyclone_api -->|"fetches imagery"| node_ml_client
node_prediction_api -.->|"refreshes forecast"| node_orchestrator
node_genesis_api -->|"requests risk"| node_ml_client
node_orchestrator -.->|"requests inference"| node_ml_client
node_orchestrator -.->|"stores forecasts"| node_forecast_store
node_ml_client -.->|"calls service"| node_ml_api
node_ml_api -.->|"serves inference"| node_engine
node_engine -->|"gets observation"| node_satellite_repo
node_engine -->|"preprocesses frame"| node_preprocess
node_engine -->|"loads intensity model"| node_models
node_engine -->|"forecasts track"| node_track_infer
node_engine -->|"assesses genesis"| node_genesis_infer
node_track_infer -->|"loads track model"| node_models
node_track_infer -->|"gets observation"| node_satellite_repo
node_satellite_repo -->|"selects provider"| node_sat_providers
node_training -.->|"exports artifacts"| node_models
node_backtest -->|"evaluates forecasts"| node_track_infer
node_backend_app -->|"routes requests"| node_chat_api
node_chat_api -.->|"handles messages"| node_rag
node_rag -->|"generates embeddings"| node_embedding
node_rag -->|"queries index"| node_pinecone
node_embedding -->|"upserts vectors"| node_pinecone
node_embedding -.->|"embeds text"| node_gemini
node_rag -->|"generates reply"| node_gemini
node_rag -->|"reads fallback context"| node_storm_store
node_rag -->|"reads fallback context"| node_forecast_store

click node_dashboard "https://github.com/mayurkhalse/cycloscope/blob/main/frontend/src/App.jsx"
click node_views "https://github.com/mayurkhalse/cycloscope/tree/main/frontend/src/pages"
click node_frontend_api "https://github.com/mayurkhalse/cycloscope/tree/main/frontend/src/api"
click node_backend_app "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/app.js"
click node_cyclone_api "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/cyclone.controller.js"
click node_prediction_api "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/prediction.controller.js"
click node_genesis_api "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/cyclogenesis.controller.js"
click node_orchestrator "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/predictionOrchestrator.js"
click node_ml_client "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/mlClient.js"
click node_storm_store "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/models/Cyclone.js"
click node_forecast_store "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/models/PredictionResult.js"
click node_ml_api "https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/main.py"
click node_engine "https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/services/prediction_engine.py"
click node_track_infer "https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/inference/track_infer.py"
click node_genesis_infer "https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/inference/cyclogenesis_infer.py"
click node_models "https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/models/model_loader.py"
click node_satellite_repo "https://github.com/mayurkhalse/cycloscope/blob/main/ML/ingestion/satellite_repository.py"
click node_sat_providers "https://github.com/mayurkhalse/cycloscope/tree/main/ML/ingestion"
click node_preprocess "https://github.com/mayurkhalse/cycloscope/blob/main/ML/ingestion/live_preprocessor.py"
click node_training "https://github.com/mayurkhalse/cycloscope/tree/main/ML/training/src"
click node_backtest "https://github.com/mayurkhalse/cycloscope/blob/main/ML/evaluation/backtest_suite.py"
click node_chat_api "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/chat.controller.js"
click node_rag "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/ragService.js"
click node_embedding "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/embeddingService.js"
click node_pinecone "https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/config/pinecone.js"

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_dashboard,node_views,node_frontend_api toneBlue
class node_backend_app,node_cyclone_api,node_prediction_api,node_genesis_api,node_orchestrator,node_ml_client,node_storm_store,node_forecast_store toneAmber
class node_ml_api,node_engine,node_track_infer,node_genesis_infer,node_models toneMint
class node_satellite_repo,node_sat_providers,node_preprocess,node_training,node_backtest toneRose
class node_chat_api,node_rag,node_embedding,node_pinecone,node_operator,node_gemini toneIndigo
```

## Components

### Operations dashboard

- [Dashboard app](https://github.com/mayurkhalse/cycloscope/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Operations views](https://github.com/mayurkhalse/cycloscope/tree/main/frontend/src/pages): `frontend/src/pages`
- [API clients](https://github.com/mayurkhalse/cycloscope/tree/main/frontend/src/api): `frontend/src/api`

### Backend API

- [REST application](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/app.js): `backend/src/app.js`
- [Cyclone API](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/cyclone.controller.js): `backend/src/controllers/cyclone.controller.js`
- [Prediction API](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/prediction.controller.js): `backend/src/controllers/prediction.controller.js`
- [Genesis API](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/cyclogenesis.controller.js): `backend/src/controllers/cyclogenesis.controller.js`
- [Prediction orchestrator](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/predictionOrchestrator.js): `backend/src/services/predictionOrchestrator.js`
- [ML service client](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/mlClient.js): `backend/src/services/mlClient.js`
- [Cyclone records](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/models/Cyclone.js): `backend/src/models/Cyclone.js`
- [Forecast records](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/models/PredictionResult.js): `backend/src/models/PredictionResult.js`

### ML inference

- [Inference service](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/main.py): `ML/serving/app/main.py`
- [Prediction engine](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/services/prediction_engine.py): `ML/serving/app/services/prediction_engine.py`
- [Track inference](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/inference/track_infer.py): `ML/serving/app/inference/track_infer.py`
- [Genesis inference](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/inference/cyclogenesis_infer.py): `ML/serving/app/inference/cyclogenesis_infer.py`
- [Model loader](https://github.com/mayurkhalse/cycloscope/blob/main/ML/serving/app/models/model_loader.py): `ML/serving/app/models/model_loader.py`

### Satellite and science data

- [Satellite repository](https://github.com/mayurkhalse/cycloscope/blob/main/ML/ingestion/satellite_repository.py): `ML/ingestion/satellite_repository.py`
- [Satellite providers](https://github.com/mayurkhalse/cycloscope/tree/main/ML/ingestion): `ML/ingestion`
- [Live preprocessing](https://github.com/mayurkhalse/cycloscope/blob/main/ML/ingestion/live_preprocessor.py): `ML/ingestion/live_preprocessor.py`
- [Model training](https://github.com/mayurkhalse/cycloscope/tree/main/ML/training/src): `ML/training/src`
- [Historical backtesting](https://github.com/mayurkhalse/cycloscope/blob/main/ML/evaluation/backtest_suite.py): `ML/evaluation/backtest_suite.py`

### Grounded assistant

- [Chat controller](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/controllers/chat.controller.js): `backend/src/controllers/chat.controller.js`
- [Context retrieval and response](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/ragService.js): `backend/src/services/ragService.js`
- [Embedding service](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/services/embeddingService.js): `backend/src/services/embeddingService.js`
- [Pinecone index](https://github.com/mayurkhalse/cycloscope/blob/main/backend/src/config/pinecone.js): `backend/src/config/pinecone.js`

### Other components

- **Forecaster**
- **Gemini service**

## Connections

- Forecaster → Dashboard app: uses (evidence: `frontend/src/App.jsx`)
- Dashboard app → Operations views: routes to
- Operations views → API clients: requests data
- API clients → REST application: calls API
- REST application → Cyclone API: routes requests (evidence: `backend/src/app.js`)
- REST application → Prediction API: routes requests (evidence: `backend/src/app.js`)
- REST application → Genesis API: routes requests (evidence: `backend/src/app.js`)
- Cyclone API → Cyclone records: reads (evidence: `backend/src/controllers/cyclone.controller.js`)
- Cyclone API → Forecast records: reads (evidence: `backend/src/controllers/cyclone.controller.js`)
- Cyclone API → ML service client: fetches imagery (evidence: `backend/src/controllers/cyclone.controller.js`)
- Prediction API → Prediction orchestrator: refreshes forecast
- Genesis API → ML service client: requests risk (evidence: `backend/src/controllers/cyclogenesis.controller.js`)
- Prediction orchestrator → ML service client: requests inference
- Prediction orchestrator → Forecast records: stores forecasts
- ML service client → Inference service: calls service
- Inference service → Prediction engine: serves inference
- Prediction engine → Satellite repository: gets observation (evidence: `ML/serving/app/services/prediction_engine.py`)
- Prediction engine → Live preprocessing: preprocesses frame (evidence: `ML/serving/app/services/prediction_engine.py`)
- Prediction engine → Model loader: loads intensity model (evidence: `ML/serving/app/services/prediction_engine.py`)
- Prediction engine → Track inference: forecasts track (evidence: `ML/serving/app/services/prediction_engine.py`)
- Prediction engine → Genesis inference: assesses genesis (evidence: `ML/serving/app/services/prediction_engine.py`)
- Track inference → Model loader: loads track model (evidence: `ML/serving/app/inference/track_infer.py`)
- Track inference → Satellite repository: gets observation (evidence: `ML/serving/app/inference/track_infer.py`)
- Satellite repository → Satellite providers: selects provider (evidence: `ML/ingestion/satellite_repository.py`)
- Model training → Model loader: exports artifacts (evidence: `ML/serving/app/models/model_loader.py`)
- Historical backtesting → Track inference: evaluates forecasts (evidence: `ML/evaluation/backtest_suite.py`)
- REST application → Chat controller: routes requests (evidence: `backend/src/app.js`)
- Chat controller → Context retrieval and response: handles messages
- Context retrieval and response → Embedding service: generates embeddings (evidence: `backend/src/services/ragService.js`)
- Context retrieval and response → Pinecone index: queries index (evidence: `backend/src/services/ragService.js`)
- Embedding service → Pinecone index: upserts vectors (evidence: `backend/src/services/embeddingService.js`)
- Embedding service → Gemini service: embeds text (evidence: `backend/src/services/embeddingService.js`)
- Context retrieval and response → Gemini service: generates reply (evidence: `backend/src/services/ragService.js`)
- Context retrieval and response → Cyclone records: reads fallback context (evidence: `backend/src/services/ragService.js`)
- Context retrieval and response → Forecast records: reads fallback context (evidence: `backend/src/services/ragService.js`)
