# jeet8499/oceanwatch architecture

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

- Interactive diagram: https://gitdiagram.com/jeet8499/oceanwatch
- Repository: https://github.com/jeet8499/oceanwatch

## Overview

OceanWatch AI is a post-event oil-spill forensics product: investigators review a case, inspect satellite-derived slick evidence and drift, examine AIS vessel histories, and compare ranked attribution candidates in a GIS dashboard. The README documents a processing sequence from Sentinel-1 imagery through physical validation, drift, AIS matching and anomaly analysis to attribution; only the drift implementation and portions of the demo/API and map wiring were sampled. The graph preserves documented stages and UI branches, but omits uncertain implementation-level links.

Main entry points: [`frontend/src/context/AppContext.tsx`](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/context/AppContext.tsx) (Case and playback state), [`backend/app/worker/stages/drift.py`](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/drift.py) (Drift ensemble), [`frontend/src/App.tsx`](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/App.tsx) (SPA routes), [`frontend/src/screens/EnnoreDemoScreen.tsx`](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/screens/EnnoreDemoScreen.tsx) (Case investigation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Investigator dashboard"]
  node_app["SPA routes<br/>[App.tsx]"]
  node_case_ui["Case investigation"]
  node_map["GIS map<br/>[MapLibreMap.tsx]"]
  node_vessel_ui["Vessel tracking"]
  node_other_screens["Analysis screens"]
  node_app_state["Case and playback state<br/>[AppContext.tsx]"]
  node_ais_utils["AIS time state<br/>[ais.ts]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_api["Demo API and assets"]
  node_api_app["FastAPI app<br/>[main.py]"]
  node_demo_api["Demo case endpoint<br/>[demo.py]"]
  node_incident_api["Incident endpoints<br/>[incidents.py]"]
  node_assets["Case artifacts"]
end

subgraph group_pipeline["Forensic processing"]
  node_sar["SAR preprocessing and readers"]
  node_detection["Slick detection<br/>[ship_detection.py]"]
  node_validation["Physical validation<br/>[cfar.py]"]
  node_drift["Drift ensemble<br/>[drift.py]"]
  node_ais_reconstruction["AIS reconstruction"]
  node_anomaly["AIS anomaly analysis<br/>[ais.py]"]
  node_attribution["Candidate attribution"]
end

subgraph group_evidence["Evidence sources"]
  node_sar_inputs["Sentinel-1 imagery"]
  node_environment_inputs["Wind and currents"]
  node_ais_inputs["AIS tracks"]
end

node_investigator(("Investigator"))

node_investigator -->|"opens dashboard"| node_app
node_app -->|"routes case"| node_case_ui
node_case_ui -->|"reads case state"| node_app_state
node_app_state -->|"fetches demo"| node_demo_api
node_app_state -->|"fetches playback"| node_assets
node_case_ui -->|"renders scene"| node_map
node_map -->|"reads layers and data"| node_app_state
node_map -->|"resolves vessel state"| node_ais_utils
node_vessel_ui -->|"resolves vessel state"| node_ais_utils
node_app -->|"routes analysis"| node_other_screens
node_api_client -->|"requests API"| node_api_app
node_api_app -->|"dispatches demo route"| node_demo_api
node_api_app -->|"dispatches incident route"| node_incident_api
node_demo_api -->|"reads and serves artifacts"| node_assets
node_sar_inputs -->|"supplies scenes"| node_sar
node_sar -->|"prepares imagery"| node_detection
node_detection -->|"produces candidate slicks"| node_validation
node_validation -->|"passes validated slicks"| node_drift
node_environment_inputs -->|"supplies vectors"| node_drift
node_ais_inputs -->|"supplies tracks"| node_ais_reconstruction
node_drift -->|"defines origin window"| node_ais_reconstruction
node_ais_reconstruction -->|"provides trajectories"| node_anomaly
node_anomaly -->|"provides anomaly evidence"| node_attribution
node_drift -->|"provides drift evidence"| node_attribution
node_attribution -->|"ranks candidates"| node_assets

click node_app "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/App.tsx"
click node_case_ui "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/screens/EnnoreDemoScreen.tsx"
click node_map "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/components/map/MapLibreMap.tsx"
click node_vessel_ui "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/screens/VesselTrackingScreen.tsx"
click node_other_screens "https://github.com/jeet8499/oceanwatch/tree/main/frontend/src/screens"
click node_app_state "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/context/AppContext.tsx"
click node_ais_utils "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/utils/ais.ts"
click node_api_client "https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/services/api.ts"
click node_api_app "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/main.py"
click node_demo_api "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/api/demo.py"
click node_incident_api "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/api/incidents.py"
click node_assets "https://github.com/jeet8499/oceanwatch/tree/main/artifacts/demo/ennore"
click node_sar "https://github.com/jeet8499/oceanwatch/tree/main/backend/app/worker/stages"
click node_detection "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/ship_detection.py"
click node_validation "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/cfar.py"
click node_drift "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/drift.py"
click node_ais_reconstruction "https://github.com/jeet8499/oceanwatch/tree/main/scripts"
click node_anomaly "https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/attribution/ais.py"
click node_attribution "https://github.com/jeet8499/oceanwatch/tree/main/backend/app/worker/stages/attribution"

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_app,node_case_ui,node_map,node_vessel_ui,node_other_screens,node_app_state,node_ais_utils,node_api_client toneBlue
class node_api_app,node_demo_api,node_incident_api,node_assets toneAmber
class node_sar,node_detection,node_validation,node_drift,node_ais_reconstruction,node_anomaly,node_attribution toneMint
class node_sar_inputs,node_environment_inputs,node_ais_inputs toneRose
class node_investigator toneIndigo
```

## Components

### Investigator dashboard

- [SPA routes](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Case investigation](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/screens/EnnoreDemoScreen.tsx): `frontend/src/screens/EnnoreDemoScreen.tsx`
- [GIS map](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/components/map/MapLibreMap.tsx): `frontend/src/components/map/MapLibreMap.tsx`
- [Vessel tracking](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/screens/VesselTrackingScreen.tsx): `frontend/src/screens/VesselTrackingScreen.tsx`
- [Analysis screens](https://github.com/jeet8499/oceanwatch/tree/main/frontend/src/screens): `frontend/src/screens`
- [Case and playback state](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/context/AppContext.tsx): `frontend/src/context/AppContext.tsx`
- [AIS time state](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/utils/ais.ts): `frontend/src/utils/ais.ts`
- [API client](https://github.com/jeet8499/oceanwatch/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`

### Demo API and assets

- [FastAPI app](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/main.py): `backend/app/main.py`
- [Demo case endpoint](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/api/demo.py): `backend/app/api/demo.py`
- [Incident endpoints](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/api/incidents.py): `backend/app/api/incidents.py`
- [Case artifacts](https://github.com/jeet8499/oceanwatch/tree/main/artifacts/demo/ennore): `artifacts/demo/ennore`

### Forensic processing

- [SAR preprocessing and readers](https://github.com/jeet8499/oceanwatch/tree/main/backend/app/worker/stages): `backend/app/worker/stages`
- [Slick detection](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/ship_detection.py): `backend/app/worker/stages/ship_detection.py`
- [Physical validation](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/cfar.py): `backend/app/worker/stages/cfar.py`
- [Drift ensemble](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/drift.py): `backend/app/worker/stages/drift.py`
- [AIS reconstruction](https://github.com/jeet8499/oceanwatch/tree/main/scripts): `scripts`
- [AIS anomaly analysis](https://github.com/jeet8499/oceanwatch/blob/main/backend/app/worker/stages/attribution/ais.py): `backend/app/worker/stages/attribution/ais.py`
- [Candidate attribution](https://github.com/jeet8499/oceanwatch/tree/main/backend/app/worker/stages/attribution): `backend/app/worker/stages/attribution`

### Evidence sources

- **Sentinel-1 imagery**
- **Wind and currents**
- **AIS tracks**

### Other components

- **Investigator**

## Connections

- Investigator → SPA routes: opens dashboard
- SPA routes → Case investigation: routes case
- Case investigation → Case and playback state: reads case state
- Case and playback state → Demo case endpoint: fetches demo
- Case and playback state → Case artifacts: fetches playback
- Case investigation → GIS map: renders scene
- GIS map → Case and playback state: reads layers and data
- GIS map → AIS time state: resolves vessel state
- Vessel tracking → AIS time state: resolves vessel state
- SPA routes → Analysis screens: routes analysis
- API client → FastAPI app: requests API
- FastAPI app → Demo case endpoint: dispatches demo route
- FastAPI app → Incident endpoints: dispatches incident route
- Demo case endpoint → Case artifacts: reads and serves artifacts
- Sentinel-1 imagery → SAR preprocessing and readers: supplies scenes
- SAR preprocessing and readers → Slick detection: prepares imagery
- Slick detection → Physical validation: produces candidate slicks
- Physical validation → Drift ensemble: passes validated slicks
- Wind and currents → Drift ensemble: supplies vectors
- AIS tracks → AIS reconstruction: supplies tracks
- Drift ensemble → AIS reconstruction: defines origin window
- AIS reconstruction → AIS anomaly analysis: provides trajectories
- AIS anomaly analysis → Candidate attribution: provides anomaly evidence
- Drift ensemble → Candidate attribution: provides drift evidence
- Candidate attribution → Case artifacts: ranks candidates