# mithilesh-24/oceanproject architecture

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

- Interactive diagram: https://gitdiagram.com/mithilesh-24/oceanproject
- Repository: https://github.com/mithilesh-24/oceanproject

## Overview

BlueSphere is an oceanographic digital-twin and intelligence platform. Scientists and operators use its web workspaces to explore ocean observations and model fields, run time-aware visualization and scientific comparisons, and access derived analysis; results can also be saved or exported. The React client routes users to specialized views and calls a FastAPI scientific backend, while a separate Express service handles authentication. The README documents broader capabilities than the sampled code establishes; those branches are retained with documented relationships, and unsampled implementation details are not inferred.

Main entry points: [`backend/app/main.py`](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/main.py) (FastAPI router), [`frontend/src/App.tsx`](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/App.tsx) (Workspace router), [`frontend/src/services/apiClient.ts`](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/services/apiClient.ts) (REST API client), [`frontend/src/views/OceanExplorerView.tsx`](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/OceanExplorerView.tsx) (3D Ocean Explorer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web Workstation"]
  node_webapp["Workspace router<br/>[App.tsx]"]
  node_explorer["3D Ocean Explorer"]
  node_comparison_view["Model comparison<br/>[ComparisonView.tsx]"]
  node_time_view["4D time machine<br/>[FourDView.tsx]"]
  node_validation_view["Model validation<br/>[AccuracyView.tsx]"]
  node_api_client["REST API client<br/>[apiClient.ts]"]
  node_cesium["Globe controller"]
end

subgraph group_science["Scientific API"]
  node_api["FastAPI router<br/>[main.py]"]
end

subgraph group_data["Data and Ingestion"]
  node_observations["Observation services<br/>[unified_service.py]"]
  node_gliders["Glider provider<br/>[glider_provider.py]"]
  node_observation_records[("Observation records<br/>[observation.py]")]
  node_database_session[("Database sessions<br/>[session.py]")]
  node_ingestion["Ingestion pipelines<br/>[pipelines.py]"]
end

subgraph group_intelligence["Analysis and Copilot"]
  node_comparison_engine["Comparison engine"]
  node_ocean_math["Ocean metrics<br/>[ocean_math.py]"]
  node_research["Research analysis<br/>[research_engine.py]"]
  node_spatiotemporal["Spatiotemporal analysis"]
  node_copilot["Agentic copilot<br/>[copilot_engine.py]"]
end

subgraph group_identity["Identity Service"]
  node_auth_router["Authentication routes<br/>[auth.py]"]
  node_express_auth["Express auth service<br/>[server.js]"]
end

node_user(("Scientist or operator"))
node_neon[("Neon PostgreSQL")]
node_satellite[("Satellite and Copernicus feeds")]

node_user -->|"opens workspace"| node_webapp
node_webapp -->|"routes to"| node_explorer
node_webapp -->|"routes to"| node_comparison_view
node_webapp -->|"routes to"| node_time_view
node_webapp -->|"routes to"| node_validation_view
node_explorer -.->|"requests data"| node_api_client
node_comparison_view -.->|"requests analysis"| node_api_client
node_time_view -.->|"requests snapshots"| node_api_client
node_api_client -->|"calls REST API"| node_api
node_api -.->|"serves observations"| node_observations
node_observations -->|"uses provider"| node_gliders
node_observations -->|"reads records"| node_observation_records
node_comparison_engine -->|"reads records"| node_observation_records
node_comparison_engine -->|"computes metrics"| node_ocean_math
node_api -.->|"serves comparison"| node_comparison_engine
node_api -.->|"serves time analysis"| node_spatiotemporal
node_api -.->|"serves research"| node_research
node_api -.->|"serves copilot"| node_copilot
node_api -->|"registers routes"| node_ingestion
node_ingestion -->|"queries session"| node_database_session
node_ingestion -.->|"updates pipeline rows"| node_observation_records
node_database_session -->|"connects or falls back"| node_neon
node_api -.->|"integrates feeds"| node_satellite
node_api -->|"registers routes"| node_auth_router
node_auth_router -->|"uses session"| node_database_session
node_user -->|"authenticates"| node_express_auth
node_express_auth -.->|"queries users"| node_neon
node_explorer -.->|"controls globe"| node_cesium

click node_webapp "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/App.tsx"
click node_explorer "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/OceanExplorerView.tsx"
click node_comparison_view "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/ComparisonView.tsx"
click node_time_view "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/FourDView.tsx"
click node_validation_view "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/AccuracyView.tsx"
click node_api_client "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/services/apiClient.ts"
click node_cesium "https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/controllers/cesiumController.ts"
click node_api "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/main.py"
click node_observations "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/observation_providers/unified_service.py"
click node_gliders "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/observation_providers/glider_provider.py"
click node_observation_records "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/models/observation.py"
click node_database_session "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/db/session.py"
click node_ingestion "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/api/v1/endpoints/pipelines.py"
click node_comparison_engine "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/comparison_engine.py"
click node_ocean_math "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/ocean_math.py"
click node_research "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/research_engine.py"
click node_spatiotemporal "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/spatiotemporal_engine.py"
click node_copilot "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/copilot_engine.py"
click node_auth_router "https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/api/v1/endpoints/auth.py"
click node_express_auth "https://github.com/mithilesh-24/oceanproject/blob/master/databasecon/server.js"

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_webapp,node_explorer,node_comparison_view,node_time_view,node_validation_view,node_api_client,node_cesium toneBlue
class node_api,node_neon,node_satellite toneAmber
class node_observations,node_gliders,node_observation_records,node_database_session,node_ingestion toneMint
class node_comparison_engine,node_ocean_math,node_research,node_spatiotemporal,node_copilot toneRose
class node_auth_router,node_express_auth,node_user toneIndigo
```

## Components

### Web Workstation

- [Workspace router](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/App.tsx): `frontend/src/App.tsx`
- [3D Ocean Explorer](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/OceanExplorerView.tsx): `frontend/src/views/OceanExplorerView.tsx`
- [Model comparison](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/ComparisonView.tsx): `frontend/src/views/ComparisonView.tsx`
- [4D time machine](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/FourDView.tsx): `frontend/src/views/FourDView.tsx`
- [Model validation](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/views/AccuracyView.tsx): `frontend/src/views/AccuracyView.tsx`
- [REST API client](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/services/apiClient.ts): `frontend/src/services/apiClient.ts`
- [Globe controller](https://github.com/mithilesh-24/oceanproject/blob/master/frontend/src/controllers/cesiumController.ts): `frontend/src/controllers/cesiumController.ts`

### Scientific API

- [FastAPI router](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/main.py): `backend/app/main.py`

### Data and Ingestion

- [Observation services](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/observation_providers/unified_service.py): `backend/app/services/observation_providers/unified_service.py`
- [Glider provider](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/observation_providers/glider_provider.py): `backend/app/services/observation_providers/glider_provider.py`
- [Observation records](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/models/observation.py): `backend/app/models/observation.py`
- [Database sessions](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/db/session.py): `backend/app/db/session.py`
- [Ingestion pipelines](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/api/v1/endpoints/pipelines.py): `backend/app/api/v1/endpoints/pipelines.py`

### Analysis and Copilot

- [Comparison engine](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/comparison_engine.py): `backend/app/services/comparison_engine.py`
- [Ocean metrics](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/ocean_math.py): `backend/app/services/ocean_math.py`
- [Research analysis](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/research_engine.py): `backend/app/services/research_engine.py`
- [Spatiotemporal analysis](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/spatiotemporal_engine.py): `backend/app/services/spatiotemporal_engine.py`
- [Agentic copilot](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/services/copilot_engine.py): `backend/app/services/copilot_engine.py`

### Identity Service

- [Authentication routes](https://github.com/mithilesh-24/oceanproject/blob/master/backend/app/api/v1/endpoints/auth.py): `backend/app/api/v1/endpoints/auth.py`
- [Express auth service](https://github.com/mithilesh-24/oceanproject/blob/master/databasecon/server.js): `databasecon/server.js`

### Other components

- **Scientist or operator**
- **Neon PostgreSQL**
- **Satellite and Copernicus feeds**

## Connections

- Scientist or operator → Workspace router: opens workspace (evidence: `README.md`)
- Workspace router → 3D Ocean Explorer: routes to (evidence: `frontend/src/App.tsx`)
- Workspace router → Model comparison: routes to (evidence: `frontend/src/App.tsx`)
- Workspace router → 4D time machine: routes to (evidence: `frontend/src/App.tsx`)
- Workspace router → Model validation: routes to (evidence: `frontend/src/App.tsx`)
- 3D Ocean Explorer → REST API client: requests data
- Model comparison → REST API client: requests analysis
- 4D time machine → REST API client: requests snapshots
- REST API client → FastAPI router: calls REST API (evidence: `frontend/src/services/apiClient.ts`)
- FastAPI router → Observation services: serves observations
- Observation services → Glider provider: uses provider (evidence: `backend/app/services/observation_providers/unified_service.py`)
- Observation services → Observation records: reads records (evidence: `backend/app/services/observation_providers/unified_service.py`)
- Comparison engine → Observation records: reads records (evidence: `backend/app/services/comparison_engine.py`)
- Comparison engine → Ocean metrics: computes metrics (evidence: `backend/app/services/comparison_engine.py`)
- FastAPI router → Comparison engine: serves comparison
- FastAPI router → Spatiotemporal analysis: serves time analysis
- FastAPI router → Research analysis: serves research
- FastAPI router → Agentic copilot: serves copilot
- FastAPI router → Ingestion pipelines: registers routes (evidence: `backend/app/main.py`)
- Ingestion pipelines → Database sessions: queries session (evidence: `backend/app/api/v1/endpoints/pipelines.py`)
- Ingestion pipelines → Observation records: updates pipeline rows
- Database sessions → Neon PostgreSQL: connects or falls back (evidence: `backend/app/db/session.py`)
- FastAPI router → Satellite and Copernicus feeds: integrates feeds (evidence: `README.md`)
- FastAPI router → Authentication routes: registers routes (evidence: `backend/app/main.py`)
- Authentication routes → Database sessions: uses session (evidence: `backend/app/api/v1/endpoints/auth.py`)
- Scientist or operator → Express auth service: authenticates (evidence: `databasecon/server.js`)
- Express auth service → Neon PostgreSQL: queries users
- 3D Ocean Explorer → Globe controller: controls globe
