# shivamgawade-xs/nsc architecture

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

- Interactive diagram: https://gitdiagram.com/shivamgawade-xs/nsc
- Repository: https://github.com/shivamgawade-xs/nsc

## Overview

Tellura is a climate-observation analytics workstation: users choose a dataset, variable, time span and region, submit an analysis, then inspect mapped trends and cell-level evidence, compare or discover signals, and export results. The graph follows the evidenced browser-to-API analysis path and preserves README-described scientific capabilities, plus dataset adapters and supporting cache state. Several feature modules are documented or indexed but unsampled, so their internal calls are omitted rather than inferred.

Main entry points: [`backend/app/api/routers/analysis.py`](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/routers/analysis.py) (Analysis Endpoint), [`frontend-react/src/store/useStore.js`](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/store/useStore.js) (Analysis State), [`frontend-react/src/pages/DashboardPage.jsx`](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/pages/DashboardPage.jsx) (Analysis Workspace), [`backend/app/adapters/base.py`](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/base.py) (Observation Adapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workstation["Scientific Workstation"]
  node_dashboard["Analysis Workspace<br/>[DashboardPage.jsx]"]
  node_controls["Analysis Controls<br/>[AnalysisPanel.jsx]"]
  node_state["Analysis State<br/>[useStore.js]"]
  node_client["API Client<br/>[client.js]"]
  node_map["Trend Map<br/>[TrendMap.jsx]"]
  node_evidence["Evidence View<br/>[EvidencePanel.jsx]"]
  node_exports["Result Exports<br/>[ExportButtons.jsx]"]
end

subgraph group_api["API and Data"]
  node_api_entry["API Router<br/>[endpoints.py]"]
  node_analysis_api["Analysis Endpoint<br/>[analysis.py]"]
  node_contracts["Analysis Schemas<br/>[analysis.py]"]
  node_shared["Shared Data Access<br/>[shared.py]"]
  node_adapters["Observation Adapters<br/>[base.py]"]
  node_merra["MERRA-2 Adapter<br/>[merra2.py]"]
  node_power["NASA POWER Adapter<br/>[nasa_power.py]"]
  node_planetary["Planetary Computer"]
end

subgraph group_science["Climate Analysis"]
  node_trend["Trend Statistics<br/>[trend.py]"]
  node_spatial["Spatial Clustering<br/>[spatial.py]"]
  node_shared_science["Signal Metrics<br/>[shared.py]"]
  node_attribution["Event Attribution<br/>[attribution.py]"]
  node_hazards["Compound Hazards<br/>[copula_hazard.py]"]
  node_velocity["Climate Velocity"]
  node_discovery["Signal Discovery<br/>[discovery.py]"]
  node_robustness["Robustness Analysis<br/>[robustness.py]"]
  node_copilot["Natural Language Queries<br/>[nlq_parser.py]"]
  node_exports_engine["Export Generation<br/>[export.py]"]
end

subgraph group_platform["Platform Services"]
  node_cache[("Analysis Cache<br/>[db_cache.py]")]
  node_auth["Authentication<br/>[auth.py]"]
  node_main["Application Runtime<br/>[main.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_controls
node_dashboard -->|"renders"| node_map
node_dashboard -->|"renders"| node_evidence
node_controls -.->|"updates"| node_state
node_state -->|"requests analysis"| node_client
node_client -.->|"HTTP requests"| node_api_entry
node_api_entry -->|"routes"| node_analysis_api
node_analysis_api -->|"validates"| node_contracts
node_analysis_api -->|"uses data helpers"| node_shared
node_analysis_api -->|"reads and writes"| node_cache
node_analysis_api -->|"selects dataset"| node_adapters
node_adapters -->|"implements"| node_merra
node_adapters -->|"implements"| node_power
node_adapters -->|"implements"| node_planetary
node_analysis_api -->|"computes trends"| node_trend
node_trend -->|"uses clustering"| node_spatial
node_shared -->|"computes metrics"| node_shared_science
node_analysis_api -.->|"supports attribution"| node_attribution
node_analysis_api -->|"supports compound analysis"| node_hazards
node_analysis_api -->|"serves velocity"| node_velocity
node_analysis_api -->|"ranks discoveries"| node_discovery
node_analysis_api -->|"runs robustness"| node_robustness
node_analysis_api -.->|"parses queries"| node_copilot
node_analysis_api -.->|"generates exports"| node_exports_engine
node_analysis_api -->|"checks access"| node_auth
node_main -->|"mounts routes"| node_api_entry
node_main -->|"configures security"| node_auth
node_state -->|"supplies results"| node_map
node_state -->|"supplies results"| node_evidence
node_state -.->|"supplies results"| node_exports

click node_dashboard "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/pages/DashboardPage.jsx"
click node_controls "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/AnalysisPanel.jsx"
click node_state "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/store/useStore.js"
click node_client "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/api/client.js"
click node_map "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/TrendMap.jsx"
click node_evidence "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/EvidencePanel.jsx"
click node_exports "https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/ExportButtons.jsx"
click node_api_entry "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/endpoints.py"
click node_analysis_api "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/routers/analysis.py"
click node_contracts "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/schemas/analysis.py"
click node_shared "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/shared.py"
click node_cache "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/core/db_cache.py"
click node_adapters "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/base.py"
click node_merra "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/merra2.py"
click node_power "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/nasa_power.py"
click node_planetary "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/planetary_computer.py"
click node_trend "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/trend.py"
click node_spatial "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/spatial.py"
click node_shared_science "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/shared.py"
click node_attribution "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/attribution.py"
click node_hazards "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/copula_hazard.py"
click node_velocity "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/climate_velocity.py"
click node_discovery "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/discovery.py"
click node_robustness "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/robustness.py"
click node_copilot "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/nlq_parser.py"
click node_exports_engine "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/export.py"
click node_auth "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/core/auth.py"
click node_main "https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/main.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_dashboard,node_controls,node_state,node_client,node_map,node_evidence,node_exports toneBlue
class node_api_entry,node_analysis_api,node_contracts,node_shared,node_adapters,node_merra,node_power,node_planetary toneAmber
class node_trend,node_spatial,node_shared_science,node_attribution,node_hazards,node_velocity,node_discovery,node_robustness,node_copilot,node_exports_engine toneMint
class node_cache,node_auth,node_main toneRose
class node_researcher toneIndigo
```

## Components

### Scientific Workstation

- [Analysis Workspace](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/pages/DashboardPage.jsx): `frontend-react/src/pages/DashboardPage.jsx`
- [Analysis Controls](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/AnalysisPanel.jsx): `frontend-react/src/components/AnalysisPanel.jsx`
- [Analysis State](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/store/useStore.js): `frontend-react/src/store/useStore.js`
- [API Client](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/api/client.js): `frontend-react/src/api/client.js`
- [Trend Map](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/TrendMap.jsx): `frontend-react/src/components/TrendMap.jsx`
- [Evidence View](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/EvidencePanel.jsx): `frontend-react/src/components/EvidencePanel.jsx`
- [Result Exports](https://github.com/shivamgawade-xs/nsc/blob/main/frontend-react/src/components/ExportButtons.jsx): `frontend-react/src/components/ExportButtons.jsx`

### API and Data

- [API Router](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/endpoints.py): `backend/app/api/endpoints.py`
- [Analysis Endpoint](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/routers/analysis.py): `backend/app/api/routers/analysis.py`
- [Analysis Schemas](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/schemas/analysis.py): `backend/app/schemas/analysis.py`
- [Shared Data Access](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/shared.py): `backend/app/api/shared.py`
- [Observation Adapters](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/base.py): `backend/app/adapters/base.py`
- [MERRA-2 Adapter](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/merra2.py): `backend/app/adapters/merra2.py`
- [NASA POWER Adapter](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/nasa_power.py): `backend/app/adapters/nasa_power.py`
- [Planetary Computer](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/adapters/planetary_computer.py): `backend/app/adapters/planetary_computer.py`

### Climate Analysis

- [Trend Statistics](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/trend.py): `backend/app/science/trend.py`
- [Spatial Clustering](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/spatial.py): `backend/app/science/spatial.py`
- [Signal Metrics](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/api/shared.py): `backend/app/api/shared.py`
- [Event Attribution](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/attribution.py): `backend/app/science/attribution.py`
- [Compound Hazards](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/copula_hazard.py): `backend/app/science/copula_hazard.py`
- [Climate Velocity](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/climate_velocity.py): `backend/app/science/climate_velocity.py`
- [Signal Discovery](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/discovery.py): `backend/app/science/discovery.py`
- [Robustness Analysis](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/robustness.py): `backend/app/science/robustness.py`
- [Natural Language Queries](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/nlq_parser.py): `backend/app/science/nlq_parser.py`
- [Export Generation](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/science/export.py): `backend/app/science/export.py`

### Platform Services

- [Analysis Cache](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/core/db_cache.py): `backend/app/core/db_cache.py`
- [Authentication](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/core/auth.py): `backend/app/core/auth.py`
- [Application Runtime](https://github.com/shivamgawade-xs/nsc/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Researcher**

## Connections

- Researcher → Analysis Workspace: uses
- Analysis Workspace → Analysis Controls: renders (evidence: `frontend-react/src/pages/DashboardPage.jsx`)
- Analysis Workspace → Trend Map: renders (evidence: `frontend-react/src/pages/DashboardPage.jsx`)
- Analysis Workspace → Evidence View: renders (evidence: `frontend-react/src/pages/DashboardPage.jsx`)
- Analysis Controls → Analysis State: updates (evidence: `frontend-react/src/components/AnalysisPanel.jsx`)
- Analysis State → API Client: requests analysis (evidence: `frontend-react/src/store/useStore.js`)
- API Client → API Router: HTTP requests
- API Router → Analysis Endpoint: routes (evidence: `backend/app/api/endpoints.py`)
- Analysis Endpoint → Analysis Schemas: validates (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Shared Data Access: uses data helpers (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Analysis Cache: reads and writes (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Observation Adapters: selects dataset
- Observation Adapters → MERRA-2 Adapter: implements (evidence: `backend/app/adapters/merra2.py`)
- Observation Adapters → NASA POWER Adapter: implements (evidence: `backend/app/adapters/nasa_power.py`)
- Observation Adapters → Planetary Computer: implements (evidence: `backend/app/adapters/planetary_computer.py`)
- Analysis Endpoint → Trend Statistics: computes trends (evidence: `backend/app/api/routers/analysis.py`)
- Trend Statistics → Spatial Clustering: uses clustering (evidence: `backend/app/science/trend.py`)
- Shared Data Access → Signal Metrics: computes metrics (evidence: `backend/app/api/shared.py`)
- Analysis Endpoint → Event Attribution: supports attribution
- Analysis Endpoint → Compound Hazards: supports compound analysis (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Climate Velocity: serves velocity (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Signal Discovery: ranks discoveries (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Robustness Analysis: runs robustness (evidence: `backend/app/api/routers/analysis.py`)
- Analysis Endpoint → Natural Language Queries: parses queries
- Analysis Endpoint → Export Generation: generates exports
- Analysis Endpoint → Authentication: checks access (evidence: `backend/app/api/routers/analysis.py`)
- Application Runtime → API Router: mounts routes (evidence: `backend/app/main.py`)
- Application Runtime → Authentication: configures security (evidence: `backend/app/main.py`)
- Analysis State → Trend Map: supplies results (evidence: `frontend-react/src/store/useStore.js`)
- Analysis State → Evidence View: supplies results (evidence: `frontend-react/src/components/EvidencePanel.jsx`)
- Analysis State → Result Exports: supplies results