# ahmedshaban0/spectralink architecture

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

- Interactive diagram: https://gitdiagram.com/ahmedshaban0/spectralink
- Repository: https://github.com/ahmedshaban0/spectralink

## Overview

SpectraLink is a satellite-fire harmonization and climate-monitoring product with both a Streamlit analysis app and a FastAPI/3D mission-control experience. In the API workflow, a regional request loads satellite records, runs feature engineering and harmonization, assembles regional analytics and spatial points, and returns results for mapping or CSV export. The README also documents emissions accounting, seasonal calendars, and forecasting. The sampled code supports the main API orchestration and model/data-engine calls; some frontend wiring and analytics implementation details are not shown.

Main entry points: [`server.py`](https://github.com/ahmedshaban0/spectralink/blob/main/server.py) (Analysis API), [`ml_engine_v3.py`](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py) (Features & Models), [`app.py`](https://github.com/ahmedshaban0/spectralink/blob/main/app.py) (Streamlit Analysis), [`gee_global_engine.py`](https://github.com/ahmedshaban0/spectralink/blob/main/gee_global_engine.py) (Regional Data Engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["User Interfaces"]
  node_streamlit_app["Streamlit Analysis<br/>[app.py]"]
  node_mission_ui["3D Mission Control<br/>[app.js]"]
  node_api["Analysis API<br/>[server.py]"]
end

subgraph group_collection["Satellite Data"]
  node_gee["Google Earth Engine"]
  node_regional_data["Regional Data Engine"]
  node_legacy_data["GEE Data Engine<br/>[gee_engine.py]"]
  node_cache[("Regional Cache")]
end

subgraph group_analysis["Harmonization &amp; Analytics"]
  node_features_models["Features &amp; Models<br/>[ml_engine_v3.py]"]
  node_legacy_ml["Harmonization Engine<br/>[harmonizer_ml.py]"]
  node_historical["Harmonized Baseline<br/>[ml_engine_v3.py]"]
  node_forecast["Seasonal Forecast<br/>[ml_engine_v3.py]"]
  node_emissions["Emissions Estimates<br/>[ml_engine_v3.py]"]
  node_calendar["Burning Calendar<br/>[ml_engine_v3.py]"]
  node_spatial["Fire Map Data"]
end

subgraph group_delivery["Results &amp; Storage"]
  node_regional_results["Regional Results<br/>[server.py]"]
  node_csv_export["CSV Export<br/>[server.py]"]
  node_static_assets["Static Web Assets<br/>[index.html]"]
end

node_analyst(("Analyst"))

node_analyst -->|"analyzes regions"| node_streamlit_app
node_analyst -->|"explores globe"| node_mission_ui
node_streamlit_app -->|"checks and loads data"| node_legacy_data
node_streamlit_app -->|"harmonizes data"| node_legacy_ml
node_gee -.->|"provides observations"| node_legacy_data
node_api -->|"loads regional data"| node_regional_data
node_api -->|"engineers and harmonizes"| node_features_models
node_api -->|"generates hotspots"| node_spatial
node_api -->|"assembles response"| node_regional_results
node_api -->|"streams dataset"| node_csv_export
node_regional_data -->|"reads and writes"| node_cache
node_regional_data -.->|"queries observations"| node_gee
node_features_models -->|"produces baseline"| node_historical
node_features_models -->|"forecasts activity"| node_forecast
node_features_models -->|"estimates emissions"| node_emissions
node_features_models -->|"builds calendar"| node_calendar
node_api -->|"serves assets"| node_static_assets

click node_streamlit_app "https://github.com/ahmedshaban0/spectralink/blob/main/app.py"
click node_mission_ui "https://github.com/ahmedshaban0/spectralink/blob/main/static/app.js"
click node_api "https://github.com/ahmedshaban0/spectralink/blob/main/server.py"
click node_regional_data "https://github.com/ahmedshaban0/spectralink/blob/main/gee_global_engine.py"
click node_legacy_data "https://github.com/ahmedshaban0/spectralink/blob/main/gee_engine.py"
click node_cache "https://github.com/ahmedshaban0/spectralink/tree/main/data_cache"
click node_features_models "https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py"
click node_legacy_ml "https://github.com/ahmedshaban0/spectralink/blob/main/harmonizer_ml.py"
click node_historical "https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py"
click node_forecast "https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py"
click node_emissions "https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py"
click node_calendar "https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py"
click node_spatial "https://github.com/ahmedshaban0/spectralink/blob/main/gee_global_engine.py"
click node_regional_results "https://github.com/ahmedshaban0/spectralink/blob/main/server.py"
click node_csv_export "https://github.com/ahmedshaban0/spectralink/blob/main/server.py"
click node_static_assets "https://github.com/ahmedshaban0/spectralink/blob/main/static/index.html"

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_streamlit_app,node_mission_ui,node_api toneBlue
class node_gee,node_regional_data,node_legacy_data,node_cache toneAmber
class node_features_models,node_legacy_ml,node_historical,node_forecast,node_emissions,node_calendar,node_spatial toneMint
class node_regional_results,node_csv_export,node_static_assets toneRose
class node_analyst toneIndigo
```

## Components

### User Interfaces

- [Streamlit Analysis](https://github.com/ahmedshaban0/spectralink/blob/main/app.py): `app.py`
- [3D Mission Control](https://github.com/ahmedshaban0/spectralink/blob/main/static/app.js): `static/app.js`
- [Analysis API](https://github.com/ahmedshaban0/spectralink/blob/main/server.py): `server.py`

### Satellite Data

- **Google Earth Engine**
- [Regional Data Engine](https://github.com/ahmedshaban0/spectralink/blob/main/gee_global_engine.py): `gee_global_engine.py`
- [GEE Data Engine](https://github.com/ahmedshaban0/spectralink/blob/main/gee_engine.py): `gee_engine.py`
- [Regional Cache](https://github.com/ahmedshaban0/spectralink/tree/main/data_cache): `data_cache`

### Harmonization & Analytics

- [Features & Models](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py): `ml_engine_v3.py`
- [Harmonization Engine](https://github.com/ahmedshaban0/spectralink/blob/main/harmonizer_ml.py): `harmonizer_ml.py`
- [Harmonized Baseline](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py): `ml_engine_v3.py`
- [Seasonal Forecast](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py): `ml_engine_v3.py`
- [Emissions Estimates](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py): `ml_engine_v3.py`
- [Burning Calendar](https://github.com/ahmedshaban0/spectralink/blob/main/ml_engine_v3.py): `ml_engine_v3.py`
- [Fire Map Data](https://github.com/ahmedshaban0/spectralink/blob/main/gee_global_engine.py): `gee_global_engine.py`

### Results & Storage

- [Regional Results](https://github.com/ahmedshaban0/spectralink/blob/main/server.py): `server.py`
- [CSV Export](https://github.com/ahmedshaban0/spectralink/blob/main/server.py): `server.py`
- [Static Web Assets](https://github.com/ahmedshaban0/spectralink/blob/main/static/index.html): `static/index.html`

### Other components

- **Analyst**

## Connections

- Analyst → Streamlit Analysis: analyzes regions (evidence: `README.md`)
- Analyst → 3D Mission Control: explores globe (evidence: `README.md`)
- Streamlit Analysis → GEE Data Engine: checks and loads data (evidence: `app.py`)
- Streamlit Analysis → Harmonization Engine: harmonizes data (evidence: `app.py`)
- Google Earth Engine → GEE Data Engine: provides observations (evidence: `README.md`)
- Analysis API → Regional Data Engine: loads regional data (evidence: `server.py`)
- Analysis API → Features & Models: engineers and harmonizes (evidence: `server.py`)
- Analysis API → Fire Map Data: generates hotspots (evidence: `server.py`)
- Analysis API → Regional Results: assembles response (evidence: `server.py`)
- Analysis API → CSV Export: streams dataset (evidence: `server.py`)
- Regional Data Engine → Regional Cache: reads and writes (evidence: `gee_global_engine.py`)
- Regional Data Engine → Google Earth Engine: queries observations
- Features & Models → Harmonized Baseline: produces baseline (evidence: `README.md`)
- Features & Models → Seasonal Forecast: forecasts activity (evidence: `README.md`)
- Features & Models → Emissions Estimates: estimates emissions (evidence: `README.md`)
- Features & Models → Burning Calendar: builds calendar (evidence: `README.md`)
- Analysis API → Static Web Assets: serves assets (evidence: `server.py`)
