# unrealone1-sys/project-oceansentinel architecture

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

- Interactive diagram: https://gitdiagram.com/unrealone1-sys/project-oceansentinel
- Repository: https://github.com/unrealone1-sys/project-oceansentinel

## Overview

OceanSentinel turns live maritime sensor feeds into fused vessel tracks, alerts, and a map/API; Project Icarus adds a separate aircraft-tracking domain. The documented maritime path runs from feed ingestion through fusion and live state to the UI, with optional Global Fishing Watch enrichment. The source index and excerpts support the principal module relationships; several routes and startup details are unsampled, so those links are omitted where not documented.

Main entry points: [`src/sources/ingest.rs`](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/ingest.rs) (Ingest router), [`src/server.rs`](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/server.rs) (HTTP and WebSocket server), [`src/fusion.rs`](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/fusion.rs) (Track fusion and alerts), [`src/sources/mod.rs`](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/mod.rs) (Feed manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Sensor inputs"]
  node_feed_manager["Feed manager<br/>[mod.rs]"]
  node_nmea_feeds["TCP and UDP feeds<br/>[nmea_tcp.rs]"]
  node_aisstream_feed["AISStream client<br/>[aisstream.rs]"]
  node_simulator["Traffic simulator<br/>[simulator.rs]"]
end

subgraph group_maritime["Maritime tracking"]
  node_ingest["Ingest router<br/>[ingest.rs]"]
  node_nmea_decode["NMEA parsing<br/>[nmea.rs]"]
  node_ais_decode["AIS decoding<br/>[ais.rs]"]
  node_fusion["Track fusion and alerts<br/>[fusion.rs]"]
  node_geo["Geospatial helpers<br/>[geo.rs]"]
  node_land["Land boundaries<br/>[land.rs]"]
end

subgraph group_state["State and enrichment"]
  node_track_store[("Live track store<br/>[store.rs]")]
  node_persistence[("File persistence<br/>[persist.rs]")]
  node_gfw_client["Fishing enrichment<br/>[gfw.rs]"]
  node_alert_delivery["Alert delivery<br/>[notify.rs]"]
  node_config["Runtime configuration<br/>[config.rs]"]
end

subgraph group_aviation["Project Icarus"]
  node_adsb_client["ADS-B polling<br/>[adsb.rs]"]
  node_aircraft_store[("Aircraft tracking and alerts<br/>[icarus.rs]")]
end

subgraph group_delivery["API and map"]
  node_server["HTTP and WebSocket server<br/>[server.rs]"]
  node_map_ui["Maritime map<br/>[app.js]"]
  node_aircraft_ui["Icarus map<br/>[icarus.js]"]
end

node_radio(("AIS radio"))
node_sensor(("Sonar and LiDAR"))
node_aisstream_service(("AISStream"))
node_aircraft_feed(("ADS-B network"))
node_gfw_service(("Global Fishing Watch"))
node_operators(("Operators"))

node_operators -->|"uses API and map"| node_server
node_radio -->|"sends NMEA"| node_nmea_feeds
node_sensor -->|"sends NMEA or JSON"| node_nmea_feeds
node_aisstream_service -->|"streams AIS"| node_aisstream_feed
node_aircraft_feed -->|"provides aircraft data"| node_adsb_client
node_feed_manager -->|"starts feeds"| node_nmea_feeds
node_feed_manager -->|"starts feed"| node_aisstream_feed
node_feed_manager -->|"starts simulator"| node_simulator
node_nmea_feeds -->|"routes feed data"| node_ingest
node_aisstream_feed -->|"emits feed events"| node_ingest
node_simulator -->|"uses shared ingest path"| node_ingest
node_ingest -->|"parses sentences"| node_nmea_decode
node_ingest -->|"assembles and decodes AIS"| node_ais_decode
node_ingest -->|"emits sensor events"| node_fusion
node_fusion -->|"updates tracks"| node_track_store
node_fusion -->|"uses distance calculations"| node_geo
node_track_store -->|"loads saved zones and lists"| node_persistence
node_track_store -->|"provides live state"| node_server
node_server -->|"requests enrichment"| node_gfw_client
node_gfw_client -->|"fetches registry data"| node_gfw_service
node_server -->|"serves embedded UI and live feed"| node_map_ui
node_server -->|"serves Icarus UI"| node_aircraft_ui
node_adsb_client -.->|"supplies aircraft updates"| node_aircraft_store
node_aircraft_store -->|"serves aircraft state"| node_server
node_config -->|"configures feeds"| node_feed_manager
node_config -->|"configures service"| node_gfw_client
node_config -->|"configures polling"| node_adsb_client
node_alert_delivery -->|"records alerts"| node_persistence
node_fusion -.->|"dispatches alerts"| node_alert_delivery
node_land -->|"uses polygon checks"| node_geo

click node_feed_manager "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/mod.rs"
click node_nmea_feeds "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/nmea_tcp.rs"
click node_aisstream_feed "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/aisstream.rs"
click node_simulator "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/simulator.rs"
click node_ingest "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/ingest.rs"
click node_nmea_decode "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/nmea.rs"
click node_ais_decode "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/ais.rs"
click node_fusion "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/fusion.rs"
click node_track_store "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/store.rs"
click node_persistence "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/persist.rs"
click node_gfw_client "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/gfw.rs"
click node_alert_delivery "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/notify.rs"
click node_adsb_client "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/adsb.rs"
click node_aircraft_store "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/icarus.rs"
click node_server "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/server.rs"
click node_map_ui "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/ui/app.js"
click node_aircraft_ui "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/ui/icarus.js"
click node_config "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/config.rs"
click node_geo "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/geo.rs"
click node_land "https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/land.rs"

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_feed_manager,node_nmea_feeds,node_aisstream_feed,node_simulator toneBlue
class node_ingest,node_nmea_decode,node_ais_decode,node_fusion,node_geo,node_land toneAmber
class node_track_store,node_persistence,node_gfw_client,node_alert_delivery,node_config toneMint
class node_adsb_client,node_aircraft_store toneRose
class node_server,node_map_ui,node_aircraft_ui,node_radio,node_sensor,node_aisstream_service,node_aircraft_feed,node_gfw_service,node_operators toneIndigo
```

## Components

### Sensor inputs

- [Feed manager](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/mod.rs): `src/sources/mod.rs`
- [TCP and UDP feeds](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/nmea_tcp.rs): `src/sources/nmea_tcp.rs`
- [AISStream client](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/aisstream.rs): `src/sources/aisstream.rs`
- [Traffic simulator](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/simulator.rs): `src/sources/simulator.rs`

### Maritime tracking

- [Ingest router](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/sources/ingest.rs): `src/sources/ingest.rs`
- [NMEA parsing](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/nmea.rs): `src/nmea.rs`
- [AIS decoding](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/ais.rs): `src/ais.rs`
- [Track fusion and alerts](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/fusion.rs): `src/fusion.rs`
- [Geospatial helpers](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/geo.rs): `src/geo.rs`
- [Land boundaries](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/land.rs): `src/land.rs`

### State and enrichment

- [Live track store](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/store.rs): `src/store.rs`
- [File persistence](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/persist.rs): `src/persist.rs`
- [Fishing enrichment](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/gfw.rs): `src/gfw.rs`
- [Alert delivery](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/notify.rs): `src/notify.rs`
- [Runtime configuration](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/config.rs): `src/config.rs`

### Project Icarus

- [ADS-B polling](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/adsb.rs): `src/adsb.rs`
- [Aircraft tracking and alerts](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/icarus.rs): `src/icarus.rs`

### API and map

- [HTTP and WebSocket server](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/src/server.rs): `src/server.rs`
- [Maritime map](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/ui/app.js): `ui/app.js`
- [Icarus map](https://github.com/unrealone1-sys/project-oceansentinel/blob/main/ui/icarus.js): `ui/icarus.js`

### Other components

- **AIS radio**
- **Sonar and LiDAR**
- **AISStream**
- **ADS-B network**
- **Global Fishing Watch**
- **Operators**

## Connections

- Operators → HTTP and WebSocket server: uses API and map (evidence: `README.md`)
- AIS radio → TCP and UDP feeds: sends NMEA (evidence: `README.md`)
- Sonar and LiDAR → TCP and UDP feeds: sends NMEA or JSON (evidence: `README.md`)
- AISStream → AISStream client: streams AIS (evidence: `README.md`)
- ADS-B network → ADS-B polling: provides aircraft data (evidence: `src/adsb.rs`)
- Feed manager → TCP and UDP feeds: starts feeds (evidence: `src/sources/mod.rs`)
- Feed manager → AISStream client: starts feed (evidence: `src/sources/mod.rs`)
- Feed manager → Traffic simulator: starts simulator (evidence: `src/sources/mod.rs`)
- TCP and UDP feeds → Ingest router: routes feed data (evidence: `src/sources/nmea_tcp.rs`)
- AISStream client → Ingest router: emits feed events (evidence: `src/sources/aisstream.rs`)
- Traffic simulator → Ingest router: uses shared ingest path (evidence: `src/sources/simulator.rs`)
- Ingest router → NMEA parsing: parses sentences (evidence: `src/sources/ingest.rs`)
- Ingest router → AIS decoding: assembles and decodes AIS (evidence: `src/sources/ingest.rs`)
- Ingest router → Track fusion and alerts: emits sensor events (evidence: `src/sources/ingest.rs`)
- Track fusion and alerts → Live track store: updates tracks (evidence: `src/fusion.rs`)
- Track fusion and alerts → Geospatial helpers: uses distance calculations (evidence: `src/fusion.rs`)
- Live track store → File persistence: loads saved zones and lists (evidence: `src/store.rs`)
- Live track store → HTTP and WebSocket server: provides live state (evidence: `src/server.rs`)
- HTTP and WebSocket server → Fishing enrichment: requests enrichment (evidence: `src/server.rs`)
- Fishing enrichment → Global Fishing Watch: fetches registry data (evidence: `README.md`)
- HTTP and WebSocket server → Maritime map: serves embedded UI and live feed (evidence: `src/server.rs`)
- HTTP and WebSocket server → Icarus map: serves Icarus UI (evidence: `README.md`)
- ADS-B polling → Aircraft tracking and alerts: supplies aircraft updates (evidence: `src/icarus.rs`)
- Aircraft tracking and alerts → HTTP and WebSocket server: serves aircraft state (evidence: `src/server.rs`)
- Runtime configuration → Feed manager: configures feeds (evidence: `src/sources/mod.rs`)
- Runtime configuration → Fishing enrichment: configures service (evidence: `src/gfw.rs`)
- Runtime configuration → ADS-B polling: configures polling (evidence: `src/adsb.rs`)
- Alert delivery → File persistence: records alerts (evidence: `src/notify.rs`)
- Track fusion and alerts → Alert delivery: dispatches alerts
- Land boundaries → Geospatial helpers: uses polygon checks (evidence: `src/land.rs`)
