# sidhazzzzzz/samudra architecture

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

- Interactive diagram: https://gitdiagram.com/sidhazzzzzz/samudra
- Repository: https://github.com/sidhazzzzzz/samudra

## Overview

SAMUDRA is a marine decision-support application for fishing and commercial route planning, PFZ lookup, storm advisories, and voyage risk assessment. The documented user flow runs from the browser’s query to the FastAPI query endpoint, where an LLM selects data tools and returns an advisory; users can also view marine layers and export reports. Separate capabilities include bathymetric routing, protected-area and boundary checks, coastal alerts, and system status. Relationships among unsampled modules are omitted unless documented; the graph uses the README and shown excerpts rather than assuming calls from module names alone.

Main entry points: [`orca-backend/app/orchestrator.py`](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/orchestrator.py) (LLM Orchestrator), [`orca-backend/app/main.py`](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/main.py) (FastAPI Endpoints), [`orca-backend/app/agents/weather_agent.py`](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/weather_agent.py) (Marine Weather), [`orca-backend/app/layer_proxy.py`](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/layer_proxy.py) (Marine Layer Proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User Interface"]
  node_frontend["Web Interface<br/>[index.html]"]
end

subgraph group_api["API and Orchestration"]
  node_backend["FastAPI Endpoints<br/>[main.py]"]
  node_schemas["Request State<br/>[schemas.py]"]
  node_orchestrator["LLM Orchestrator<br/>[orchestrator.py]"]
  node_cache["Response Cache<br/>[cache.py]"]
end

subgraph group_marine["Marine Intelligence"]
  node_pfz["PFZ Advisories<br/>[pfz_agent.py]"]
  node_weather["Marine Weather<br/>[weather_agent.py]"]
  node_marine_data["Marine Data"]
  node_geospatial["Geospatial Checks"]
  node_routing["Bathymetric Routing<br/>[routing_engine.py]"]
end

subgraph group_safety["Safety and Reporting"]
  node_risk["Voyage Risk<br/>[risk_agent.py]"]
  node_coastal["Coastal Authority"]
  node_reporting["PDF Reporting<br/>[reporting_agent.py]"]
end

subgraph group_integrations["Data Integrations"]
  node_layer_proxy["Marine Layer Proxy<br/>[layer_proxy.py]"]
  node_fallbacks["Fallback Snapshots"]
end

node_user(("Planner"))
node_incois["INCOIS Services"]
node_open_meteo["Open-Meteo"]
node_opentopo["OpenTopoData"]
node_llm["LLM Provider"]

node_user -->|"uses"| node_frontend
node_frontend -->|"submits query"| node_backend
node_backend -->|"dispatches query"| node_orchestrator
node_backend -->|"accepts state"| node_schemas
node_backend -->|"generates PDF"| node_reporting
node_backend -->|"proxies layers"| node_layer_proxy
node_backend -->|"builds risk field"| node_routing
node_backend -->|"checks broadcast"| node_coastal
node_orchestrator -->|"selects tools"| node_llm
node_orchestrator -->|"fetches PFZ"| node_pfz
node_orchestrator -->|"fetches weather"| node_weather
node_orchestrator -->|"plans routes"| node_routing
node_orchestrator -.->|"retrieves data"| node_marine_data
node_orchestrator -.->|"checks routes"| node_geospatial
node_orchestrator -.->|"assesses risk"| node_risk
node_weather -->|"fetches forecasts"| node_open_meteo
node_routing -->|"loads bathymetry"| node_opentopo
node_layer_proxy -->|"proxies layers"| node_incois
node_layer_proxy -->|"serves snapshots"| node_fallbacks
node_pfz -->|"fetches advisories"| node_incois
node_weather -.->|"uses cache"| node_cache
node_coastal -->|"gets storm data"| node_weather

click node_frontend "https://github.com/sidhazzzzzz/samudra/blob/main/orca-frontend/index.html"
click node_backend "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/main.py"
click node_schemas "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/schemas.py"
click node_orchestrator "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/orchestrator.py"
click node_cache "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/cache.py"
click node_pfz "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/pfz_agent.py"
click node_weather "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/weather_agent.py"
click node_marine_data "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/marine_data_agent.py"
click node_geospatial "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/geospatial_agent.py"
click node_routing "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/routing_engine.py"
click node_risk "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/risk_agent.py"
click node_coastal "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/coastal_authority_agent.py"
click node_reporting "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/reporting_agent.py"
click node_layer_proxy "https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/layer_proxy.py"
click node_fallbacks "https://github.com/sidhazzzzzz/samudra/tree/main/orca-backend/app/data/fallback"

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_frontend toneBlue
class node_backend,node_schemas,node_orchestrator,node_cache toneAmber
class node_pfz,node_weather,node_marine_data,node_geospatial,node_routing toneMint
class node_risk,node_coastal,node_reporting toneRose
class node_layer_proxy,node_fallbacks,node_user,node_incois,node_open_meteo,node_opentopo,node_llm toneIndigo
```

## Components

### User Interface

- [Web Interface](https://github.com/sidhazzzzzz/samudra/blob/main/orca-frontend/index.html): `orca-frontend/index.html`

### API and Orchestration

- [FastAPI Endpoints](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/main.py): `orca-backend/app/main.py`
- [Request State](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/schemas.py): `orca-backend/app/schemas.py`
- [LLM Orchestrator](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/orchestrator.py): `orca-backend/app/orchestrator.py`
- [Response Cache](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/cache.py): `orca-backend/app/cache.py`

### Marine Intelligence

- [PFZ Advisories](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/pfz_agent.py): `orca-backend/app/agents/pfz_agent.py`
- [Marine Weather](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/weather_agent.py): `orca-backend/app/agents/weather_agent.py`
- [Marine Data](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/marine_data_agent.py): `orca-backend/app/agents/marine_data_agent.py`
- [Geospatial Checks](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/geospatial_agent.py): `orca-backend/app/agents/geospatial_agent.py`
- [Bathymetric Routing](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/routing_engine.py): `orca-backend/app/agents/routing_engine.py`

### Safety and Reporting

- [Voyage Risk](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/risk_agent.py): `orca-backend/app/agents/risk_agent.py`
- [Coastal Authority](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/coastal_authority_agent.py): `orca-backend/app/agents/coastal_authority_agent.py`
- [PDF Reporting](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/agents/reporting_agent.py): `orca-backend/app/agents/reporting_agent.py`

### Data Integrations

- [Marine Layer Proxy](https://github.com/sidhazzzzzz/samudra/blob/main/orca-backend/app/layer_proxy.py): `orca-backend/app/layer_proxy.py`
- [Fallback Snapshots](https://github.com/sidhazzzzzz/samudra/tree/main/orca-backend/app/data/fallback): `orca-backend/app/data/fallback`

### Other components

- **Planner**
- **INCOIS Services**
- **Open-Meteo**
- **OpenTopoData**
- **LLM Provider**

## Connections

- Planner → Web Interface: uses (evidence: `README.md`)
- Web Interface → FastAPI Endpoints: submits query (evidence: `README.md`)
- FastAPI Endpoints → LLM Orchestrator: dispatches query (evidence: `README.md`)
- FastAPI Endpoints → Request State: accepts state (evidence: `orca-backend/app/main.py`)
- FastAPI Endpoints → PDF Reporting: generates PDF (evidence: `orca-backend/app/main.py`)
- FastAPI Endpoints → Marine Layer Proxy: proxies layers (evidence: `orca-backend/app/main.py`)
- FastAPI Endpoints → Bathymetric Routing: builds risk field (evidence: `orca-backend/app/main.py`)
- FastAPI Endpoints → Coastal Authority: checks broadcast (evidence: `orca-backend/app/main.py`)
- LLM Orchestrator → LLM Provider: selects tools (evidence: `orca-backend/app/orchestrator.py`)
- LLM Orchestrator → PFZ Advisories: fetches PFZ (evidence: `README.md`)
- LLM Orchestrator → Marine Weather: fetches weather (evidence: `README.md`)
- LLM Orchestrator → Bathymetric Routing: plans routes (evidence: `README.md`)
- LLM Orchestrator → Marine Data: retrieves data (evidence: `orca-backend/app/orchestrator.py`)
- LLM Orchestrator → Geospatial Checks: checks routes (evidence: `orca-backend/app/orchestrator.py`)
- LLM Orchestrator → Voyage Risk: assesses risk (evidence: `orca-backend/app/orchestrator.py`)
- Marine Weather → Open-Meteo: fetches forecasts (evidence: `orca-backend/app/agents/weather_agent.py`)
- Bathymetric Routing → OpenTopoData: loads bathymetry (evidence: `orca-backend/app/agents/routing_engine.py`)
- Marine Layer Proxy → INCOIS Services: proxies layers (evidence: `orca-backend/app/layer_proxy.py`)
- Marine Layer Proxy → Fallback Snapshots: serves snapshots (evidence: `orca-backend/app/layer_proxy.py`)
- PFZ Advisories → INCOIS Services: fetches advisories (evidence: `orca-backend/app/agents/pfz_agent.py`)
- Marine Weather → Response Cache: uses cache (evidence: `orca-backend/app/agents/weather_agent.py`)
- Coastal Authority → Marine Weather: gets storm data (evidence: `orca-backend/app/agents/coastal_authority_agent.py`)
