# tauqeerahmed0309/oceanshield-backend architecture

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

- Interactive diagram: https://gitdiagram.com/tauqeerahmed0309/oceanshield-backend
- Repository: https://github.com/tauqeerahmed0309/oceanshield-backend

## Overview

OceanShield AI is a maritime spill-intelligence platform: it ingests live or replayed AIS and satellite SAR data, detects vessel anomalies and slick candidates, correlates evidence to attribute vessels and assess risk, then exposes incidents, reports, analytics, and alerts through a React dashboard and FastAPI API. The graph follows the documented stages and sampled startup, ingestion, correlation, persistence, and frontend API wiring. Several endpoint and task implementations were not sampled, so their internal call relationships are omitted; documented capabilities remain represented.

Main entry points: [`backend/app/api`](https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/api) (REST routers), [`backend/app/db/json_store.py`](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/db/json_store.py) (JSON data store), [`backend/app/main.py`](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/tasks/run_spill_pipeline.py`](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/run_spill_pipeline.py) (Spill pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Dashboard"]
  node_web["Web dashboard<br/>[App.tsx]"]
  node_views["Operations views"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API Surface"]
  node_backend["FastAPI app<br/>[main.py]"]
  node_routers["REST routers"]
end

subgraph group_ingestion["Data Ingestion"]
  node_ais_supervisor["AIS supervisor<br/>[ais_supervisor.py]"]
  node_ais_client["AIS message handler"]
  node_replay["AIS replay"]
  node_sar_poll["SAR catalogue poll"]
  node_sar_ingestion["SAR fetchers<br/>[sar_fetcher.py]"]
end

subgraph group_analysis["Detection &amp; Attribution"]
  node_anomaly_task["Anomaly scoring"]
  node_anomaly_model["Anomaly model"]
  node_spill_task["Spill pipeline"]
  node_segmentation["Slick segmentation"]
  node_correlation["Filter correlation"]
  node_filters["Five-layer filters"]
  node_risk["Risk scoring<br/>[risk_scoring.py]"]
  node_attribution["Vessel attribution"]
  node_drift["Drift prediction"]
end

subgraph group_operations["Incidents &amp; Storage"]
  node_store[("JSON data store<br/>[json_store.py]")]
  node_records["Maritime records"]
  node_reports["Incident reports<br/>[reports.py]"]
  node_alerting["ICG notifications<br/>[icg_notifier.py]"]
end

node_operator(("Maritime operator"))
node_ais_source(("AIS feed"))
node_sar_source(("SAR catalogue"))
node_icg(("ICG / MRCC"))
node_weather(("Open-Meteo"))

node_operator -->|"uses"| node_web
node_web -->|"renders"| node_views
node_views -->|"requests data"| node_api_client
node_api_client -->|"REST JSON"| node_backend
node_backend -->|"registers routes"| node_routers
node_backend -->|"starts feed"| node_ais_supervisor
node_ais_supervisor -->|"connects live"| node_ais_client
node_ais_source -->|"streams positions"| node_ais_client
node_ais_supervisor -.->|"falls back"| node_replay
node_replay -->|"reuses handler"| node_ais_client
node_ais_client -->|"writes positions/history"| node_store
node_backend -->|"schedules"| node_anomaly_task
node_anomaly_task -->|"reads history"| node_store
node_anomaly_task -->|"scores vessels"| node_anomaly_model
node_anomaly_task -->|"writes anomalies"| node_store
node_backend -->|"schedules"| node_spill_task
node_spill_task -->|"reads anomalies"| node_store
node_spill_task -->|"scores candidates"| node_risk
node_spill_task -->|"writes candidates/incidents"| node_store
node_spill_task -->|"ranks vessels"| node_attribution
node_attribution -->|"queries positions"| node_store
node_sar_source -->|"provides scenes"| node_sar_poll
node_backend -->|"schedules"| node_sar_poll
node_sar_poll -->|"acquires imagery"| node_sar_ingestion
node_sar_ingestion -->|"stores scenes"| node_store
node_segmentation -->|"supplies mask"| node_correlation
node_correlation -->|"applies layers"| node_filters
node_correlation -->|"computes score"| node_risk
node_filters -.->|"gets wind"| node_weather
node_routers -->|"serves records"| node_store
node_routers -->|"analyzes uploads"| node_segmentation
node_routers -->|"filters candidates"| node_correlation
node_routers -->|"requests drift"| node_drift
node_routers -->|"requests attribution"| node_attribution
node_routers -->|"generates reports"| node_reports
node_routers -->|"dispatches alerts"| node_alerting
node_alerting -.->|"notifies"| node_icg
node_reports -->|"reads incidents"| node_store
node_routers -->|"returns domain data"| node_records

click node_web "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/oceanshield-ai/src/App.tsx"
click node_views "https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/oceanshield-ai/src/pages"
click node_api_client "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/oceanshield-ai/src/api/client.ts"
click node_backend "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/main.py"
click node_routers "https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/api"
click node_ais_supervisor "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/ais_supervisor.py"
click node_ais_client "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/aisstream_client.py"
click node_replay "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/ais_replay_client.py"
click node_sar_poll "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/poll_sar_catalogue.py"
click node_sar_ingestion "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/sar_fetcher.py"
click node_anomaly_task "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/run_anomaly_detection.py"
click node_anomaly_model "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/anomaly_detector.py"
click node_spill_task "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/run_spill_pipeline.py"
click node_segmentation "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/unet_segmentation.py"
click node_correlation "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/processing/correlation_engine.py"
click node_filters "https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/filters"
click node_risk "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/processing/risk_scoring.py"
click node_attribution "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/vessel_attribution.py"
click node_drift "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/drift_prediction.py"
click node_store "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/db/json_store.py"
click node_records "https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/models"
click node_reports "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/api/reports.py"
click node_alerting "https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/alerting/icg_notifier.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_web,node_views,node_api_client toneBlue
class node_backend,node_routers toneAmber
class node_ais_supervisor,node_ais_client,node_replay,node_sar_poll,node_sar_ingestion toneMint
class node_anomaly_task,node_anomaly_model,node_spill_task,node_segmentation,node_correlation,node_filters,node_risk,node_attribution,node_drift toneRose
class node_store,node_records,node_reports,node_alerting,node_operator,node_ais_source,node_sar_source,node_icg,node_weather toneIndigo
```

## Components

### Dashboard

- [Web dashboard](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/oceanshield-ai/src/App.tsx): `oceanshield-ai/src/App.tsx`
- [Operations views](https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/oceanshield-ai/src/pages): `oceanshield-ai/src/pages`
- [API client](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/oceanshield-ai/src/api/client.ts): `oceanshield-ai/src/api/client.ts`

### API Surface

- [FastAPI app](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/main.py): `backend/app/main.py`
- [REST routers](https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/api): `backend/app/api`

### Data Ingestion

- [AIS supervisor](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/ais_supervisor.py): `backend/app/ingestion/ais_supervisor.py`
- [AIS message handler](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/aisstream_client.py): `backend/app/ingestion/aisstream_client.py`
- [AIS replay](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/ais_replay_client.py): `backend/app/ingestion/ais_replay_client.py`
- [SAR catalogue poll](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/poll_sar_catalogue.py): `backend/app/tasks/poll_sar_catalogue.py`
- [SAR fetchers](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ingestion/sar_fetcher.py): `backend/app/ingestion/sar_fetcher.py`

### Detection & Attribution

- [Anomaly scoring](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/run_anomaly_detection.py): `backend/app/tasks/run_anomaly_detection.py`
- [Anomaly model](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/anomaly_detector.py): `backend/app/ml/anomaly_detector.py`
- [Spill pipeline](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/tasks/run_spill_pipeline.py): `backend/app/tasks/run_spill_pipeline.py`
- [Slick segmentation](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/unet_segmentation.py): `backend/app/ml/unet_segmentation.py`
- [Filter correlation](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/processing/correlation_engine.py): `backend/app/processing/correlation_engine.py`
- [Five-layer filters](https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/filters): `backend/app/filters`
- [Risk scoring](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/processing/risk_scoring.py): `backend/app/processing/risk_scoring.py`
- [Vessel attribution](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/vessel_attribution.py): `backend/app/ml/vessel_attribution.py`
- [Drift prediction](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/ml/drift_prediction.py): `backend/app/ml/drift_prediction.py`

### Incidents & Storage

- [JSON data store](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/db/json_store.py): `backend/app/db/json_store.py`
- [Maritime records](https://github.com/tauqeerahmed0309/oceanshield-backend/tree/main/backend/app/models): `backend/app/models`
- [Incident reports](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/api/reports.py): `backend/app/api/reports.py`
- [ICG notifications](https://github.com/tauqeerahmed0309/oceanshield-backend/blob/main/backend/app/alerting/icg_notifier.py): `backend/app/alerting/icg_notifier.py`

### Other components

- **Maritime operator**
- **AIS feed**
- **SAR catalogue**
- **ICG / MRCC**
- **Open-Meteo**

## Connections

- Maritime operator → Web dashboard: uses
- Web dashboard → Operations views: renders
- Operations views → API client: requests data
- API client → FastAPI app: REST JSON
- FastAPI app → REST routers: registers routes
- FastAPI app → AIS supervisor: starts feed
- AIS supervisor → AIS message handler: connects live
- AIS feed → AIS message handler: streams positions
- AIS supervisor → AIS replay: falls back
- AIS replay → AIS message handler: reuses handler
- AIS message handler → JSON data store: writes positions/history
- FastAPI app → Anomaly scoring: schedules
- Anomaly scoring → JSON data store: reads history
- Anomaly scoring → Anomaly model: scores vessels
- Anomaly scoring → JSON data store: writes anomalies
- FastAPI app → Spill pipeline: schedules
- Spill pipeline → JSON data store: reads anomalies
- Spill pipeline → Risk scoring: scores candidates
- Spill pipeline → JSON data store: writes candidates/incidents
- Spill pipeline → Vessel attribution: ranks vessels
- Vessel attribution → JSON data store: queries positions
- SAR catalogue → SAR catalogue poll: provides scenes
- FastAPI app → SAR catalogue poll: schedules
- SAR catalogue poll → SAR fetchers: acquires imagery
- SAR fetchers → JSON data store: stores scenes
- Slick segmentation → Filter correlation: supplies mask
- Filter correlation → Five-layer filters: applies layers
- Filter correlation → Risk scoring: computes score
- Five-layer filters → Open-Meteo: gets wind
- REST routers → JSON data store: serves records
- REST routers → Slick segmentation: analyzes uploads
- REST routers → Filter correlation: filters candidates
- REST routers → Drift prediction: requests drift
- REST routers → Vessel attribution: requests attribution
- REST routers → Incident reports: generates reports
- REST routers → ICG notifications: dispatches alerts
- ICG notifications → ICG / MRCC: notifies
- Incident reports → JSON data store: reads incidents
- REST routers → Maritime records: returns domain data