# netalgupta/varuna architecture

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

- Interactive diagram: https://gitdiagram.com/netalgupta/varuna
- Repository: https://github.com/netalgupta/varuna

## Overview

VARUNA combines ARGO physical-ocean observations and CMLRE biodiversity information for ocean operations, analytics, alerts, and natural-language investigation. A typical query enters through the API, is decomposed into agent tasks, and its gathered evidence is checked before synthesis; the frontend presents the answer and operational views. The README also documents ingestion, forecasting, quality control, and spatial visualization. Some domain branches are supported by README descriptions and the file tree rather than sampled implementation excerpts, so their internal links are omitted.

Main entry points: [`backend/src/agents/orchestrator.py`](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/orchestrator.py) (Agent DAG), [`backend/src/aegis/aegis_engine.py`](https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/aegis_engine.py) (AEGIS Evidence Check), [`frontend/src/features/command-center/CommandCenterView.tsx`](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/command-center/CommandCenterView.tsx) (Operations Center), [`backend/src/database/postgres.py`](https://github.com/netalgupta/varuna/blob/main/backend/src/database/postgres.py) (PostGIS Store)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Data Ingestion"]
  node_ingestion["ARGO Ingestion<br/>[pipeline.py]"]
  node_netcdf["NetCDF Reader<br/>[netcdf_reader.py]"]
end

subgraph group_api["Query and Agents"]
  node_entry["FastAPI App<br/>[app.py]"]
  node_routes["API Routes<br/>[routes.py]"]
  node_orchestrator["Agent DAG<br/>[orchestrator.py]"]
  node_sqlagent["SQL Agent<br/>[sql_gen_agent.py]"]
  node_retrievalagent["Retrieval Agent<br/>[retrieval_agent.py]"]
  node_bioagent["Biodiversity Agent"]
  node_synth["Answer Synthesizer"]
end

subgraph group_evidence["Evidence and Retrieval"]
  node_aegis["AEGIS Evidence Check<br/>[aegis_engine.py]"]
  node_ledger["Evidence Ledger<br/>[evidence_ledger.py]"]
  node_claims["Claim Extraction<br/>[claim_extractor.py]"]
  node_firewall["Claim Firewall<br/>[claim_firewall.py]"]
  node_rag["RAG Chain<br/>[rag_chain.py]"]
end

subgraph group_data["Data and Models"]
  node_postgres[("PostGIS Store<br/>[postgres.py]")]
  node_qdrant[("Vector Store<br/>[qdrant.py]")]
  node_ml["Forecast and QC"]
end

subgraph group_frontend["Ocean Operations UI"]
  node_ui["Operations Center"]
  node_map["Ocean Maps<br/>[VarunaMap.tsx]"]
  node_analytics["Ocean Analytics<br/>[AnalyticsView.tsx]"]
  node_bio["Biodiversity View"]
  node_alerts["Early Warnings<br/>[ForecastsView.tsx]"]
  node_datasets["Dataset Export<br/>[DatasetsView.tsx]"]
end

node_user(("Ocean User"))

node_user -->|"uses"| node_ui
node_ui -.->|"queries"| node_routes
node_entry -->|"registers"| node_routes
node_routes -->|"invokes"| node_orchestrator
node_orchestrator -->|"dispatches"| node_sqlagent
node_orchestrator -->|"dispatches"| node_retrievalagent
node_orchestrator -->|"dispatches"| node_bioagent
node_orchestrator -->|"verifies evidence"| node_aegis
node_orchestrator -->|"synthesizes"| node_synth
node_aegis -->|"builds"| node_ledger
node_aegis -->|"extracts claims"| node_claims
node_aegis -->|"checks claims"| node_firewall
node_ingestion -->|"reads profiles"| node_netcdf
node_ingestion -->|"loads observations"| node_postgres
node_sqlagent -.->|"queries"| node_postgres
node_retrievalagent -.->|"retrieves context"| node_rag
node_rag -.->|"searches vectors"| node_qdrant
node_postgres -.->|"supplies observations"| node_analytics
node_bioagent -.->|"supports exploration"| node_bio
node_ml -.->|"supports forecasts"| node_alerts
node_postgres -.->|"supplies ocean data"| node_map
node_ui -.->|"presents warnings"| node_alerts
node_ui -.->|"offers exports"| node_datasets

click node_entry "https://github.com/netalgupta/varuna/blob/main/backend/src/api/app.py"
click node_routes "https://github.com/netalgupta/varuna/blob/main/backend/src/api/routes.py"
click node_orchestrator "https://github.com/netalgupta/varuna/blob/main/backend/src/agents/orchestrator.py"
click node_sqlagent "https://github.com/netalgupta/varuna/blob/main/backend/src/agents/sql_gen_agent.py"
click node_retrievalagent "https://github.com/netalgupta/varuna/blob/main/backend/src/agents/retrieval_agent.py"
click node_bioagent "https://github.com/netalgupta/varuna/blob/main/backend/src/agents/biodiversity_agent.py"
click node_synth "https://github.com/netalgupta/varuna/blob/main/backend/src/agents/synthesizer_agent.py"
click node_aegis "https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/aegis_engine.py"
click node_ledger "https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/evidence_ledger.py"
click node_claims "https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/claim_extractor.py"
click node_firewall "https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/claim_firewall.py"
click node_rag "https://github.com/netalgupta/varuna/blob/main/backend/src/chains/rag_chain.py"
click node_ingestion "https://github.com/netalgupta/varuna/blob/main/backend/src/ingestion/pipeline.py"
click node_netcdf "https://github.com/netalgupta/varuna/blob/main/backend/src/ingestion/netcdf_reader.py"
click node_postgres "https://github.com/netalgupta/varuna/blob/main/backend/src/database/postgres.py"
click node_qdrant "https://github.com/netalgupta/varuna/blob/main/backend/src/database/qdrant.py"
click node_ml "https://github.com/netalgupta/varuna/tree/main/backend/src/ml"
click node_ui "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/command-center/CommandCenterView.tsx"
click node_map "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/ocean-map/VarunaMap.tsx"
click node_analytics "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/cross-domain/AnalyticsView.tsx"
click node_bio "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/biodiversity/BiodiversityView.tsx"
click node_alerts "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/early-warning/ForecastsView.tsx"
click node_datasets "https://github.com/netalgupta/varuna/blob/main/frontend/src/features/datasets/DatasetsView.tsx"

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_ingestion,node_netcdf,node_user toneBlue
class node_entry,node_routes,node_orchestrator,node_sqlagent,node_retrievalagent,node_bioagent,node_synth toneAmber
class node_aegis,node_ledger,node_claims,node_firewall,node_rag toneMint
class node_postgres,node_qdrant,node_ml toneRose
class node_ui,node_map,node_analytics,node_bio,node_alerts,node_datasets toneIndigo
```

## Components

### Data Ingestion

- [ARGO Ingestion](https://github.com/netalgupta/varuna/blob/main/backend/src/ingestion/pipeline.py): `backend/src/ingestion/pipeline.py`
- [NetCDF Reader](https://github.com/netalgupta/varuna/blob/main/backend/src/ingestion/netcdf_reader.py): `backend/src/ingestion/netcdf_reader.py`

### Query and Agents

- [FastAPI App](https://github.com/netalgupta/varuna/blob/main/backend/src/api/app.py): `backend/src/api/app.py`
- [API Routes](https://github.com/netalgupta/varuna/blob/main/backend/src/api/routes.py): `backend/src/api/routes.py`
- [Agent DAG](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/orchestrator.py): `backend/src/agents/orchestrator.py`
- [SQL Agent](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/sql_gen_agent.py): `backend/src/agents/sql_gen_agent.py`
- [Retrieval Agent](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/retrieval_agent.py): `backend/src/agents/retrieval_agent.py`
- [Biodiversity Agent](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/biodiversity_agent.py): `backend/src/agents/biodiversity_agent.py`
- [Answer Synthesizer](https://github.com/netalgupta/varuna/blob/main/backend/src/agents/synthesizer_agent.py): `backend/src/agents/synthesizer_agent.py`

### Evidence and Retrieval

- [AEGIS Evidence Check](https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/aegis_engine.py): `backend/src/aegis/aegis_engine.py`
- [Evidence Ledger](https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/evidence_ledger.py): `backend/src/aegis/evidence_ledger.py`
- [Claim Extraction](https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/claim_extractor.py): `backend/src/aegis/claim_extractor.py`
- [Claim Firewall](https://github.com/netalgupta/varuna/blob/main/backend/src/aegis/claim_firewall.py): `backend/src/aegis/claim_firewall.py`
- [RAG Chain](https://github.com/netalgupta/varuna/blob/main/backend/src/chains/rag_chain.py): `backend/src/chains/rag_chain.py`

### Data and Models

- [PostGIS Store](https://github.com/netalgupta/varuna/blob/main/backend/src/database/postgres.py): `backend/src/database/postgres.py`
- [Vector Store](https://github.com/netalgupta/varuna/blob/main/backend/src/database/qdrant.py): `backend/src/database/qdrant.py`
- [Forecast and QC](https://github.com/netalgupta/varuna/tree/main/backend/src/ml): `backend/src/ml`

### Ocean Operations UI

- [Operations Center](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/command-center/CommandCenterView.tsx): `frontend/src/features/command-center/CommandCenterView.tsx`
- [Ocean Maps](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/ocean-map/VarunaMap.tsx): `frontend/src/features/ocean-map/VarunaMap.tsx`
- [Ocean Analytics](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/cross-domain/AnalyticsView.tsx): `frontend/src/features/cross-domain/AnalyticsView.tsx`
- [Biodiversity View](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/biodiversity/BiodiversityView.tsx): `frontend/src/features/biodiversity/BiodiversityView.tsx`
- [Early Warnings](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/early-warning/ForecastsView.tsx): `frontend/src/features/early-warning/ForecastsView.tsx`
- [Dataset Export](https://github.com/netalgupta/varuna/blob/main/frontend/src/features/datasets/DatasetsView.tsx): `frontend/src/features/datasets/DatasetsView.tsx`

### Other components

- **Ocean User**

## Connections

- Ocean User → Operations Center: uses (evidence: `README.md`)
- Operations Center → API Routes: queries
- FastAPI App → API Routes: registers (evidence: `backend/src/api/app.py`)
- API Routes → Agent DAG: invokes (evidence: `backend/src/api/routes.py`)
- Agent DAG → SQL Agent: dispatches (evidence: `backend/src/agents/orchestrator.py`)
- Agent DAG → Retrieval Agent: dispatches (evidence: `backend/src/agents/orchestrator.py`)
- Agent DAG → Biodiversity Agent: dispatches (evidence: `backend/src/agents/orchestrator.py`)
- Agent DAG → AEGIS Evidence Check: verifies evidence (evidence: `backend/src/agents/orchestrator.py`)
- Agent DAG → Answer Synthesizer: synthesizes (evidence: `backend/src/agents/orchestrator.py`)
- AEGIS Evidence Check → Evidence Ledger: builds (evidence: `backend/src/aegis/aegis_engine.py`)
- AEGIS Evidence Check → Claim Extraction: extracts claims (evidence: `backend/src/aegis/aegis_engine.py`)
- AEGIS Evidence Check → Claim Firewall: checks claims (evidence: `backend/src/aegis/aegis_engine.py`)
- ARGO Ingestion → NetCDF Reader: reads profiles (evidence: `backend/src/ingestion/pipeline.py`)
- ARGO Ingestion → PostGIS Store: loads observations (evidence: `backend/src/ingestion/pipeline.py`)
- SQL Agent → PostGIS Store: queries
- Retrieval Agent → RAG Chain: retrieves context
- RAG Chain → Vector Store: searches vectors
- PostGIS Store → Ocean Analytics: supplies observations
- Biodiversity Agent → Biodiversity View: supports exploration
- Forecast and QC → Early Warnings: supports forecasts
- PostGIS Store → Ocean Maps: supplies ocean data
- Operations Center → Early Warnings: presents warnings (evidence: `README.md`)
- Operations Center → Dataset Export: offers exports (evidence: `README.md`)
