# divya-a10/ocean-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/divya-a10/ocean-intelligence
- Repository: https://github.com/divya-a10/ocean-intelligence

## Overview

Ocean Intelligence is a marine-plastic research platform: users select a region and forecast day, retrieve a simulation, currents, and hotspots, inspect transport and risk in an interactive dashboard, and request scientific explanations or reports. The repository contains both a documented OceanState/CMEMS backend and a separate forecast/API implementation; sampled evidence does not establish how they are wired together. Dashed, uncited edges mark documented or likely integrations not shown in source excerpts.

Main entry points: [`frontend/src/App.tsx`](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/App.tsx) (Dashboard), [`backend/api/routes_simulation.py`](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/api/routes_simulation.py) (Simulation routes), [`backend/app/engine/ocean_engine.py`](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/engine/ocean_engine.py) (Ocean engine), [`backend/app/main.py`](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/main.py) (FastAPI app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Research workspace"]
  node_dashboard["Dashboard<br/>[App.tsx]"]
  node_globe["Ocean globe<br/>[GlobePreview.tsx]"]
  node_plastic_ui["Plastic simulator"]
  node_copilot_ui["Copilot workspace"]
  node_reports_ui["Report workspace"]
  node_simulation_hook["Simulation state<br/>[useSimulation.ts]"]
  node_simulation_client["Simulation client"]
  node_api_client["HTTP client<br/>[apiClient.ts]"]
end

subgraph group_api["API and contracts"]
  node_api_contract["API contract<br/>[api.ts]"]
  node_fastapi["FastAPI app<br/>[main.py]"]
  node_legacy_routes["Simulation routes"]
  node_legacy_schema["Response schemas<br/>[schemas.py]"]
  node_settings["Application settings<br/>[settings.py]"]
  node_logger["Structured logging<br/>[logger.py]"]
end

subgraph group_science["Ocean data and simulation"]
  node_engine["Ocean engine<br/>[ocean_engine.py]"]
  node_ocean_state["OceanState model<br/>[ocean_state.py]"]
  node_cmems_loader["CMEMS loader<br/>[loader.py]"]
  node_cmems_processor["CMEMS processor<br/>[processor.py]"]
  node_forecast["Forecast engine<br/>[forecast_engine.py]"]
  node_particles["Particle simulation"]
  node_currents["Current loader<br/>[current_loader.py]"]
  node_hotspot_analysis["Hotspot analysis"]
  node_hotspot_service["Hotspot service<br/>[hotspot_service.py]"]
end

subgraph group_insight["Scientific insight"]
  node_copilot_service["Scientific copilot<br/>[gemini_service.py]"]
  node_report_service["Report service<br/>[report_service.py]"]
  node_report_generator["Report generator"]
end

node_researcher(("Researcher"))
node_gemini{{"Gemini API"}}

node_researcher -->|"explores"| node_dashboard
node_dashboard -->|"manages state"| node_simulation_hook
node_dashboard -->|"renders"| node_globe
node_dashboard -->|"renders"| node_plastic_ui
node_simulation_hook -->|"requests data"| node_simulation_client
node_simulation_client -->|"uses"| node_api_client
node_simulation_client -->|"uses types"| node_api_contract
node_dashboard -->|"offers"| node_copilot_ui
node_dashboard -->|"offers"| node_reports_ui
node_api_client -.->|"sends requests"| node_fastapi
node_fastapi -.->|"registers routes"| node_legacy_routes
node_fastapi -->|"configures"| node_settings
node_fastapi -->|"logs"| node_logger
node_legacy_routes -->|"generates forecast"| node_forecast
node_legacy_routes -->|"loads vectors"| node_currents
node_legacy_routes -->|"calculates hotspots"| node_hotspot_analysis
node_legacy_routes -->|"validates responses"| node_legacy_schema
node_forecast -->|"initializes particles"| node_particles
node_engine -->|"fetches data"| node_cmems_loader
node_engine -->|"processes data"| node_cmems_processor
node_engine -->|"builds state"| node_ocean_state
node_hotspot_service -->|"reads state"| node_engine
node_copilot_service -->|"reads state"| node_engine
node_copilot_service -.->|"requests explanation"| node_gemini
node_report_service -.->|"delegates generation"| node_report_generator

click node_dashboard "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/App.tsx"
click node_globe "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/GlobePreview.tsx"
click node_plastic_ui "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/PlasticSimulator.tsx"
click node_copilot_ui "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/AICopilotWorkspace.tsx"
click node_reports_ui "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/ReportsGenerator.tsx"
click node_simulation_hook "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/hooks/useSimulation.ts"
click node_simulation_client "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/services/simulationService.ts"
click node_api_client "https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/services/apiClient.ts"
click node_api_contract "https://github.com/divya-a10/ocean-intelligence/blob/main/shared/types/api.ts"
click node_fastapi "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/main.py"
click node_legacy_routes "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/api/routes_simulation.py"
click node_legacy_schema "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/models/schemas.py"
click node_engine "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/engine/ocean_engine.py"
click node_ocean_state "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/schemas/ocean_state.py"
click node_cmems_loader "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/cmems/loader.py"
click node_cmems_processor "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/cmems/processor.py"
click node_forecast "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/forecast_engine.py"
click node_particles "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/particle_simulation.py"
click node_currents "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/current_loader.py"
click node_hotspot_analysis "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/hotspot_analysis.py"
click node_hotspot_service "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/hotspot_service.py"
click node_copilot_service "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/gemini_service.py"
click node_report_service "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/report_service.py"
click node_report_generator "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/reports/report_generator.py"
click node_settings "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/config/settings.py"
click node_logger "https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/utils/logger.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_globe,node_plastic_ui,node_copilot_ui,node_reports_ui,node_simulation_hook,node_simulation_client,node_api_client toneBlue
class node_api_contract,node_fastapi,node_legacy_routes,node_legacy_schema,node_settings,node_logger toneAmber
class node_engine,node_ocean_state,node_cmems_loader,node_cmems_processor,node_forecast,node_particles,node_currents,node_hotspot_analysis,node_hotspot_service,node_gemini toneMint
class node_copilot_service,node_report_service,node_report_generator toneRose
class node_researcher toneIndigo
```

## Components

### Research workspace

- [Dashboard](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Ocean globe](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/GlobePreview.tsx): `frontend/src/components/GlobePreview.tsx`
- [Plastic simulator](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/PlasticSimulator.tsx): `frontend/src/components/PlasticSimulator.tsx`
- [Copilot workspace](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/AICopilotWorkspace.tsx): `frontend/src/components/AICopilotWorkspace.tsx`
- [Report workspace](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/components/ReportsGenerator.tsx): `frontend/src/components/ReportsGenerator.tsx`
- [Simulation state](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/hooks/useSimulation.ts): `frontend/src/hooks/useSimulation.ts`
- [Simulation client](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/services/simulationService.ts): `frontend/src/services/simulationService.ts`
- [HTTP client](https://github.com/divya-a10/ocean-intelligence/blob/main/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`

### API and contracts

- [API contract](https://github.com/divya-a10/ocean-intelligence/blob/main/shared/types/api.ts): `shared/types/api.ts`
- [FastAPI app](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/main.py): `backend/app/main.py`
- [Simulation routes](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/api/routes_simulation.py): `backend/api/routes_simulation.py`
- [Response schemas](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/models/schemas.py): `backend/models/schemas.py`
- [Application settings](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/config/settings.py): `backend/app/config/settings.py`
- [Structured logging](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/utils/logger.py): `backend/app/utils/logger.py`

### Ocean data and simulation

- [Ocean engine](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/engine/ocean_engine.py): `backend/app/engine/ocean_engine.py`
- [OceanState model](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/schemas/ocean_state.py): `backend/app/schemas/ocean_state.py`
- [CMEMS loader](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/cmems/loader.py): `backend/app/services/cmems/loader.py`
- [CMEMS processor](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/cmems/processor.py): `backend/app/services/cmems/processor.py`
- [Forecast engine](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/forecast_engine.py): `backend/simulation/forecast_engine.py`
- [Particle simulation](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/particle_simulation.py): `backend/simulation/particle_simulation.py`
- [Current loader](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/current_loader.py): `backend/simulation/current_loader.py`
- [Hotspot analysis](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/simulation/hotspot_analysis.py): `backend/simulation/hotspot_analysis.py`
- [Hotspot service](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/hotspot_service.py): `backend/app/services/hotspot_service.py`

### Scientific insight

- [Scientific copilot](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/gemini_service.py): `backend/app/services/gemini_service.py`
- [Report service](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`
- [Report generator](https://github.com/divya-a10/ocean-intelligence/blob/main/backend/reports/report_generator.py): `backend/reports/report_generator.py`

### Other components

- **Researcher**
- **Gemini API**

## Connections

- Researcher → Dashboard: explores (evidence: `README.md`)
- Dashboard → Simulation state: manages state (evidence: `frontend/src/App.tsx`)
- Dashboard → Ocean globe: renders (evidence: `frontend/src/App.tsx`)
- Dashboard → Plastic simulator: renders (evidence: `frontend/src/App.tsx`)
- Simulation state → Simulation client: requests data (evidence: `frontend/src/hooks/useSimulation.ts`)
- Simulation client → HTTP client: uses (evidence: `frontend/src/services/simulationService.ts`)
- Simulation client → API contract: uses types (evidence: `frontend/src/services/simulationService.ts`)
- Dashboard → Copilot workspace: offers (evidence: `frontend/src/App.tsx`)
- Dashboard → Report workspace: offers (evidence: `frontend/src/App.tsx`)
- HTTP client → FastAPI app: sends requests
- FastAPI app → Simulation routes: registers routes
- FastAPI app → Application settings: configures (evidence: `backend/app/main.py`)
- FastAPI app → Structured logging: logs (evidence: `backend/app/main.py`)
- Simulation routes → Forecast engine: generates forecast (evidence: `backend/api/routes_simulation.py`)
- Simulation routes → Current loader: loads vectors (evidence: `backend/api/routes_simulation.py`)
- Simulation routes → Hotspot analysis: calculates hotspots (evidence: `backend/api/routes_simulation.py`)
- Simulation routes → Response schemas: validates responses (evidence: `backend/api/routes_simulation.py`)
- Forecast engine → Particle simulation: initializes particles (evidence: `backend/simulation/forecast_engine.py`)
- Ocean engine → CMEMS loader: fetches data (evidence: `backend/app/engine/ocean_engine.py`)
- Ocean engine → CMEMS processor: processes data (evidence: `backend/app/engine/ocean_engine.py`)
- Ocean engine → OceanState model: builds state (evidence: `backend/app/engine/ocean_engine.py`)
- Hotspot service → Ocean engine: reads state (evidence: `backend/app/services/hotspot_service.py`)
- Scientific copilot → Ocean engine: reads state (evidence: `backend/app/services/gemini_service.py`)
- Scientific copilot → Gemini API: requests explanation
- Report service → Report generator: delegates generation