How mayurkhalse/cycloscope works
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: prediction_engine.py Prediction engine · ragService.js Context retrieval and response · app.js REST application · cyclone.controller.js Cyclone API
Components 27
Operations dashboard
- Dashboard app
frontend/src/App.jsx - Operations views
frontend/src/pages - API clients
frontend/src/api
Backend API
- REST application
backend/src/app.js - Cyclone API
backend/src/controllers/cyclone.controller.js - Prediction API
backend/src/controllers/prediction.controller.js - Genesis API
backend/src/controllers/cyclogenesis.controller.js - Prediction orchestrator
backend/src/services/predictionOrchestrator.js - ML service client
backend/src/services/mlClient.js - Cyclone records
backend/src/models/Cyclone.js - Forecast records
backend/src/models/PredictionResult.js
ML inference
- Inference service
ML/serving/app/main.py - Prediction engine
ML/serving/app/services/prediction_engine.py - Track inference
ML/serving/app/inference/track_infer.py - Genesis inference
ML/serving/app/inference/cyclogenesis_infer.py - Model loader
ML/serving/app/models/model_loader.py
Satellite and science data
- Satellite repository
ML/ingestion/satellite_repository.py - Satellite providers
ML/ingestion - Live preprocessing
ML/ingestion/live_preprocessor.py - Model training
ML/training/src - Historical backtesting
ML/evaluation/backtest_suite.py
Grounded assistant
- Chat controller
backend/src/controllers/chat.controller.js - Context retrieval and response
backend/src/services/ragService.js - Embedding service
backend/src/services/embeddingService.js - Pinecone index
backend/src/config/pinecone.js
Other components
- Forecaster
- Gemini service
Connections 35
- Forecaster → Dashboard app: uses
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
backend/src/app.js - REST application → Prediction API: routes requests
backend/src/app.js - REST application → Genesis API: routes requests
backend/src/app.js - Cyclone API → Cyclone records: reads
backend/src/controllers/cyclone.controller.js - Cyclone API → Forecast records: reads
backend/src/controllers/cyclone.controller.js - Cyclone API → ML service client: fetches imagery
backend/src/controllers/cyclone.controller.js - Prediction API → Prediction orchestrator: refreshes forecast
- Genesis API → ML service client: requests risk
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
ML/serving/app/services/prediction_engine.py - Prediction engine → Live preprocessing: preprocesses frame
ML/serving/app/services/prediction_engine.py - Prediction engine → Model loader: loads intensity model
ML/serving/app/services/prediction_engine.py - Prediction engine → Track inference: forecasts track
ML/serving/app/services/prediction_engine.py - Prediction engine → Genesis inference: assesses genesis
ML/serving/app/services/prediction_engine.py - Track inference → Model loader: loads track model
ML/serving/app/inference/track_infer.py - Track inference → Satellite repository: gets observation
ML/serving/app/inference/track_infer.py - Satellite repository → Satellite providers: selects provider
ML/ingestion/satellite_repository.py - Model training → Model loader: exports artifacts
ML/serving/app/models/model_loader.py - Historical backtesting → Track inference: evaluates forecasts
ML/evaluation/backtest_suite.py - REST application → Chat controller: routes requests
backend/src/app.js - Chat controller → Context retrieval and response: handles messages
- Context retrieval and response → Embedding service: generates embeddings
backend/src/services/ragService.js - Context retrieval and response → Pinecone index: queries index
backend/src/services/ragService.js - Embedding service → Pinecone index: upserts vectors
backend/src/services/embeddingService.js - Embedding service → Gemini service: embeds text
backend/src/services/embeddingService.js - Context retrieval and response → Gemini service: generates reply
backend/src/services/ragService.js - Context retrieval and response → Cyclone records: reads fallback context
backend/src/services/ragService.js - Context retrieval and response → Forecast records: reads fallback context
backend/src/services/ragService.js