# vivek-010107/oilnexus architecture

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

- Interactive diagram: https://gitdiagram.com/vivek-010107/oilnexus
- Repository: https://github.com/vivek-010107/oilnexus

## Overview

OilNexus is a SAR oil-spill analysis prototype with a React intelligence dashboard and FastAPI backend. The main workflow accepts an image and scenario metadata, detects oil, optionally georeferences and reconstructs drift, then optionally ranks synthetic AIS candidates; results and reports are presented in the UI. The map, live-traffic view, and incident archive are separate product capabilities. Backend execution and component imports are supported by excerpts or the SOURCE INDEX; unsampled internals and some UI-to-backend wiring are not expanded beyond shown evidence.

Main entry points: [`backend/main.py`](https://github.com/vivek-010107/oilnexus/blob/main/backend/main.py) (Analysis API), [`backend/pipeline.py`](https://github.com/vivek-010107/oilnexus/blob/main/backend/pipeline.py) (Pipeline Orchestrator), [`frontend/src/App.jsx`](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/App.jsx) (Dashboard), [`frontend/src/LiveTraffic.jsx`](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/LiveTraffic.jsx) (Live Traffic)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Investigation UI"]
  node_app["Dashboard<br/>[App.jsx]"]
  node_api_client["API Client<br/>[api.js]"]
  node_report_view["Report View<br/>[ReportView.jsx]"]
  node_evidence["Evidence Drawer<br/>[EvidenceDrawer.jsx]"]
  node_forensic_map["Forensic Map<br/>[ForensicMap.jsx]"]
  node_globe["Globe Surface<br/>[GlobeSurface.jsx]"]
  node_live_traffic["Live Traffic<br/>[LiveTraffic.jsx]"]
  node_live_data["Live Data<br/>[liveData.js]"]
  node_live_clock["Live Clock<br/>[liveClock.js]"]
  node_archive["Incident Archive"]
end

subgraph group_api["Analysis API"]
  node_api_server["Analysis API<br/>[main.py]"]
  node_pipeline["Pipeline Orchestrator<br/>[pipeline.py]"]
  node_reporting["Report Generation<br/>[reporting.py]"]
  node_mock["Mock Pipeline<br/>[mock_pipeline.py]"]
end

subgraph group_detection["SAR Detection"]
  node_inference["SAR Inference<br/>[inference.py]"]
  node_model["Model Loading<br/>[model.py]"]
  node_geometry["Pixel Geometry<br/>[geometry.py]"]
  node_georeferencing["Georeferencing<br/>[georeferencing.py]"]
end

subgraph group_physics["Drift and Attribution"]
  node_drift["Drift Reconstruction<br/>[drift.py]"]
  node_currents[("Current Grid<br/>[currents.py]")]
  node_winds["Wind Inputs<br/>[winds.py]"]
  node_wind_engine["Wind Engine<br/>[wind_engine.py]"]
  node_opendrift["Current Engine"]
  node_attribution["AIS Attribution<br/>[attribution.py]"]
end

subgraph group_contracts["Contracts and Utilities"]
  node_requests["Request Models<br/>[requests.py]"]
  node_responses["Response Models<br/>[responses.py]"]
  node_common["Shared Schemas<br/>[common.py]"]
  node_settings["Runtime Settings<br/>[settings.py]"]
  node_errors["Pipeline Errors<br/>[errors.py]"]
  node_images["Image Utilities<br/>[images.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_app
node_app -->|"calls"| node_api_client
node_app -->|"submits analysis"| node_api_server
node_app -->|"renders"| node_report_view
node_app -->|"renders"| node_archive
node_app -->|"renders"| node_live_traffic
node_app -->|"renders"| node_evidence
node_report_view -->|"renders"| node_forensic_map
node_report_view -->|"renders"| node_evidence
node_forensic_map -->|"renders"| node_globe
node_live_traffic -->|"renders"| node_globe
node_live_traffic -->|"uses"| node_live_data
node_live_traffic -->|"uses"| node_live_clock
node_api_server -->|"validates"| node_requests
node_api_server -->|"decodes image"| node_images
node_api_server -->|"runs"| node_pipeline
node_api_server -->|"generates report"| node_reporting
node_api_server -->|"configures"| node_settings
node_pipeline -->|"detects"| node_inference
node_pipeline -->|"runs mock stages"| node_mock
node_pipeline -->|"georeferences"| node_georeferencing
node_pipeline -->|"reconstructs"| node_drift
node_pipeline -->|"attributes"| node_attribution
node_inference -->|"loads"| node_model
node_inference -->|"measures"| node_geometry
node_drift -->|"loads"| node_currents
node_drift -->|"uses"| node_winds
node_drift -->|"simulates with"| node_wind_engine
node_attribution -->|"loads"| node_currents
node_attribution -->|"simulates candidates"| node_opendrift
node_api_server -->|"returns"| node_responses
node_responses -->|"uses types"| node_common
node_responses -->|"embeds input"| node_requests
node_requests -->|"uses types"| node_common
node_pipeline -->|"builds results"| node_responses
node_api_server -->|"handles"| node_errors
node_pipeline -->|"raises"| node_errors

click node_app "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/App.jsx"
click node_api_client "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/api.js"
click node_report_view "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/ReportView.jsx"
click node_evidence "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/EvidenceDrawer.jsx"
click node_forensic_map "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/ForensicMap.jsx"
click node_globe "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/GlobeSurface.jsx"
click node_live_traffic "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/LiveTraffic.jsx"
click node_live_data "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/liveData.js"
click node_live_clock "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/liveClock.js"
click node_archive "https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/IncidentArchive.jsx"
click node_api_server "https://github.com/vivek-010107/oilnexus/blob/main/backend/main.py"
click node_pipeline "https://github.com/vivek-010107/oilnexus/blob/main/backend/pipeline.py"
click node_reporting "https://github.com/vivek-010107/oilnexus/blob/main/backend/reporting.py"
click node_mock "https://github.com/vivek-010107/oilnexus/blob/main/backend/mock_pipeline.py"
click node_inference "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/inference.py"
click node_model "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/model.py"
click node_geometry "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/geometry.py"
click node_georeferencing "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/georeferencing.py"
click node_drift "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/drift.py"
click node_currents "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/currents.py"
click node_winds "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/winds.py"
click node_wind_engine "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/wind_engine.py"
click node_opendrift "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/opendrift_engine.py"
click node_attribution "https://github.com/vivek-010107/oilnexus/blob/main/backend/stage3/attribution.py"
click node_requests "https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/requests.py"
click node_responses "https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/responses.py"
click node_common "https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/common.py"
click node_settings "https://github.com/vivek-010107/oilnexus/blob/main/backend/settings.py"
click node_errors "https://github.com/vivek-010107/oilnexus/blob/main/backend/utils/errors.py"
click node_images "https://github.com/vivek-010107/oilnexus/blob/main/backend/utils/images.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_app,node_api_client,node_report_view,node_evidence,node_forensic_map,node_globe,node_live_traffic,node_live_data,node_live_clock,node_archive toneBlue
class node_api_server,node_pipeline,node_reporting,node_mock toneAmber
class node_inference,node_model,node_geometry,node_georeferencing toneMint
class node_drift,node_currents,node_winds,node_wind_engine,node_opendrift,node_attribution toneRose
class node_requests,node_responses,node_common,node_settings,node_errors,node_images,node_analyst toneIndigo
```

## Components

### Investigation UI

- [Dashboard](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [API Client](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [Report View](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/ReportView.jsx): `frontend/src/ReportView.jsx`
- [Evidence Drawer](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/EvidenceDrawer.jsx): `frontend/src/EvidenceDrawer.jsx`
- [Forensic Map](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/ForensicMap.jsx): `frontend/src/ForensicMap.jsx`
- [Globe Surface](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/GlobeSurface.jsx): `frontend/src/GlobeSurface.jsx`
- [Live Traffic](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/LiveTraffic.jsx): `frontend/src/LiveTraffic.jsx`
- [Live Data](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/liveData.js): `frontend/src/liveData.js`
- [Live Clock](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/liveClock.js): `frontend/src/liveClock.js`
- [Incident Archive](https://github.com/vivek-010107/oilnexus/blob/main/frontend/src/IncidentArchive.jsx): `frontend/src/IncidentArchive.jsx`

### Analysis API

- [Analysis API](https://github.com/vivek-010107/oilnexus/blob/main/backend/main.py): `backend/main.py`
- [Pipeline Orchestrator](https://github.com/vivek-010107/oilnexus/blob/main/backend/pipeline.py): `backend/pipeline.py`
- [Report Generation](https://github.com/vivek-010107/oilnexus/blob/main/backend/reporting.py): `backend/reporting.py`
- [Mock Pipeline](https://github.com/vivek-010107/oilnexus/blob/main/backend/mock_pipeline.py): `backend/mock_pipeline.py`

### SAR Detection

- [SAR Inference](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/inference.py): `backend/stage1/inference.py`
- [Model Loading](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/model.py): `backend/stage1/model.py`
- [Pixel Geometry](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/geometry.py): `backend/stage1/geometry.py`
- [Georeferencing](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage1/georeferencing.py): `backend/stage1/georeferencing.py`

### Drift and Attribution

- [Drift Reconstruction](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/drift.py): `backend/stage2/drift.py`
- [Current Grid](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/currents.py): `backend/stage2/currents.py`
- [Wind Inputs](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/winds.py): `backend/stage2/winds.py`
- [Wind Engine](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/wind_engine.py): `backend/stage2/wind_engine.py`
- [Current Engine](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage2/opendrift_engine.py): `backend/stage2/opendrift_engine.py`
- [AIS Attribution](https://github.com/vivek-010107/oilnexus/blob/main/backend/stage3/attribution.py): `backend/stage3/attribution.py`

### Contracts and Utilities

- [Request Models](https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/requests.py): `backend/schemas/requests.py`
- [Response Models](https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/responses.py): `backend/schemas/responses.py`
- [Shared Schemas](https://github.com/vivek-010107/oilnexus/blob/main/backend/schemas/common.py): `backend/schemas/common.py`
- [Runtime Settings](https://github.com/vivek-010107/oilnexus/blob/main/backend/settings.py): `backend/settings.py`
- [Pipeline Errors](https://github.com/vivek-010107/oilnexus/blob/main/backend/utils/errors.py): `backend/utils/errors.py`
- [Image Utilities](https://github.com/vivek-010107/oilnexus/blob/main/backend/utils/images.py): `backend/utils/images.py`

### Other components

- **Analyst**

## Connections

- Analyst → Dashboard: uses (evidence: `README.md`)
- Dashboard → API Client: calls (evidence: `frontend/src/App.jsx`)
- Dashboard → Analysis API: submits analysis (evidence: `frontend/src/App.jsx`)
- Dashboard → Report View: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → Incident Archive: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → Live Traffic: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → Evidence Drawer: renders (evidence: `frontend/src/App.jsx`)
- Report View → Forensic Map: renders (evidence: `frontend/src/ReportView.jsx`)
- Report View → Evidence Drawer: renders (evidence: `frontend/src/ReportView.jsx`)
- Forensic Map → Globe Surface: renders (evidence: `frontend/src/ForensicMap.jsx`)
- Live Traffic → Globe Surface: renders (evidence: `frontend/src/LiveTraffic.jsx`)
- Live Traffic → Live Data: uses (evidence: `frontend/src/LiveTraffic.jsx`)
- Live Traffic → Live Clock: uses (evidence: `frontend/src/LiveTraffic.jsx`)
- Analysis API → Request Models: validates (evidence: `backend/main.py`)
- Analysis API → Image Utilities: decodes image (evidence: `backend/main.py`)
- Analysis API → Pipeline Orchestrator: runs (evidence: `backend/main.py`)
- Analysis API → Report Generation: generates report (evidence: `backend/main.py`)
- Analysis API → Runtime Settings: configures (evidence: `backend/main.py`)
- Pipeline Orchestrator → SAR Inference: detects (evidence: `backend/pipeline.py`)
- Pipeline Orchestrator → Mock Pipeline: runs mock stages (evidence: `backend/pipeline.py`)
- Pipeline Orchestrator → Georeferencing: georeferences (evidence: `backend/pipeline.py`)
- Pipeline Orchestrator → Drift Reconstruction: reconstructs (evidence: `backend/pipeline.py`)
- Pipeline Orchestrator → AIS Attribution: attributes (evidence: `backend/pipeline.py`)
- SAR Inference → Model Loading: loads (evidence: `backend/stage1/inference.py`)
- SAR Inference → Pixel Geometry: measures (evidence: `backend/stage1/inference.py`)
- Drift Reconstruction → Current Grid: loads (evidence: `backend/stage2/drift.py`)
- Drift Reconstruction → Wind Inputs: uses (evidence: `backend/stage2/drift.py`)
- Drift Reconstruction → Wind Engine: simulates with (evidence: `backend/stage2/drift.py`)
- AIS Attribution → Current Grid: loads (evidence: `backend/stage3/attribution.py`)
- AIS Attribution → Current Engine: simulates candidates (evidence: `backend/stage3/attribution.py`)
- Analysis API → Response Models: returns (evidence: `backend/main.py`)
- Response Models → Shared Schemas: uses types (evidence: `backend/schemas/responses.py`)
- Response Models → Request Models: embeds input (evidence: `backend/schemas/responses.py`)
- Request Models → Shared Schemas: uses types (evidence: `backend/schemas/requests.py`)
- Pipeline Orchestrator → Response Models: builds results (evidence: `backend/pipeline.py`)
- Analysis API → Pipeline Errors: handles (evidence: `backend/main.py`)
- Pipeline Orchestrator → Pipeline Errors: raises (evidence: `backend/pipeline.py`)
