# arandomguyhere/ais_tracker architecture

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

- Interactive diagram: https://gitdiagram.com/arandomguyhere/ais_tracker
- Repository: https://github.com/arandomguyhere/ais_tracker

## Overview

Arsenal Ship Tracker is a maritime intelligence fusion proof of concept. Its principal workflow is AIS collection and vessel tracking through the API and persistent state, followed by analyst-facing enrichment and risk assessment. Separate documented branches cover SAR-to-AIS correlation, OSINT news analysis, and specialized threat monitoring. The excerpts show the server’s module imports and AIS source orchestration; several specialist capabilities are documented but their internal calls were not sampled, so those connections are limited to supported server imports or omitted.

Main entry points: [`server.py`](https://github.com/arandomguyhere/ais_tracker/blob/main/server.py) (REST API), [`ais_sources/manager.py`](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/manager.py) (Source manager), [`ais_sources/base.py`](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/base.py) (AIS source models), [`osint/correlator.py`](https://github.com/arandomguyhere/ais_tracker/blob/main/osint/correlator.py) (News correlation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_collection["AIS collection"]
  node_stream_runner["Stream runner<br/>[stream_area.py]"]
  node_source_manager["Source manager<br/>[manager.py]"]
  node_source_contract["AIS source models<br/>[base.py]"]
  node_aisstream["AISStream<br/>[aisstream.py]"]
  node_aishub["AISHub<br/>[aishub.py]"]
  node_marinesia["Marinesia<br/>[marinesia.py]"]
  node_gfw_source["GFW source<br/>[gfw.py]"]
  node_ingest["AIS ingestion<br/>[ais_ingest.py]"]
end

subgraph group_api["Tracking API"]
  node_api_server["REST API<br/>[server.py]"]
  node_vessel_store[("Vessel state<br/>[server.py]")]
end

subgraph group_analysis["Vessel intelligence"]
  node_vessel_intel["Vessel intelligence<br/>[vessel_intel.py]"]
  node_weather["Weather enrichment<br/>[weather.py]"]
  node_confidence["Confidence scoring<br/>[confidence.py]"]
  node_behavior["Behavior detection<br/>[behavior.py]"]
  node_intelligence["Intelligence reports<br/>[intelligence.py]"]
end

subgraph group_osint["OSINT analysis"]
  node_osint_sources["News sources"]
  node_entities["Entity extraction<br/>[entities.py]"]
  node_scoring["Relevance scoring<br/>[scoring.py]"]
  node_correlator["News correlation<br/>[correlator.py]"]
  node_osint_models["OSINT models<br/>[models.py]"]
end

subgraph group_special["Specialist monitoring"]
  node_sar["SAR detections<br/>[sar_import.py]"]
  node_satellite["Satellite imagery<br/>[satellite_intel.py]"]
  node_sanctions["Sanctions checks<br/>[sanctions.py]"]
  node_dark_fleet["Dark fleet analysis<br/>[dark_fleet.py]"]
  node_venezuela["Venezuela monitoring<br/>[venezuela.py]"]
  node_infrastructure["Infrastructure analysis<br/>[infra_analysis.py]"]
  node_laden["Laden status<br/>[laden_status.py]"]
  node_photos["Shoreside photos"]
  node_gfw_analysis["GFW analysis<br/>[gfw_integration.py]"]
  node_ports["Ports database<br/>[ports_database.py]"]
end

node_operator(("Analyst"))

node_operator -->|"uses API"| node_api_server
node_stream_runner -->|"starts sources"| node_source_manager
node_source_manager -->|"uses interface"| node_source_contract
node_source_manager -->|"dispatches to"| node_aisstream
node_source_manager -->|"dispatches to"| node_aishub
node_source_manager -->|"dispatches to"| node_marinesia
node_source_manager -->|"dispatches to"| node_gfw_source
node_aisstream -->|"implements"| node_source_contract
node_aishub -->|"implements"| node_source_contract
node_marinesia -->|"implements"| node_source_contract
node_gfw_source -->|"implements"| node_source_contract
node_operator -->|"starts stream"| node_stream_runner
node_api_server -->|"reads and writes"| node_vessel_store
node_api_server -->|"uses"| node_vessel_intel
node_api_server -->|"uses"| node_weather
node_api_server -->|"uses"| node_confidence
node_api_server -->|"uses"| node_behavior
node_api_server -->|"uses"| node_intelligence
node_api_server -->|"routes to"| node_sar
node_api_server -->|"uses"| node_satellite
node_api_server -->|"uses"| node_sanctions
node_api_server -->|"uses"| node_dark_fleet
node_api_server -->|"uses"| node_venezuela
node_api_server -->|"uses"| node_infrastructure
node_api_server -->|"uses"| node_laden
node_api_server -->|"uses"| node_photos
node_api_server -->|"uses"| node_gfw_analysis
node_api_server -->|"uses"| node_ports
node_correlator -->|"extracts entities"| node_entities
node_correlator -->|"scores relevance"| node_scoring
node_entities -->|"uses models"| node_osint_models
node_scoring -->|"uses models"| node_osint_models
node_correlator -->|"builds events"| node_osint_models

click node_stream_runner "https://github.com/arandomguyhere/ais_tracker/blob/main/stream_area.py"
click node_source_manager "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/manager.py"
click node_source_contract "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/base.py"
click node_aisstream "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/aisstream.py"
click node_aishub "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/aishub.py"
click node_marinesia "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/marinesia.py"
click node_gfw_source "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/gfw.py"
click node_ingest "https://github.com/arandomguyhere/ais_tracker/blob/main/ais_ingest.py"
click node_api_server "https://github.com/arandomguyhere/ais_tracker/blob/main/server.py"
click node_vessel_store "https://github.com/arandomguyhere/ais_tracker/blob/main/server.py"
click node_vessel_intel "https://github.com/arandomguyhere/ais_tracker/blob/main/vessel_intel.py"
click node_weather "https://github.com/arandomguyhere/ais_tracker/blob/main/weather.py"
click node_confidence "https://github.com/arandomguyhere/ais_tracker/blob/main/confidence.py"
click node_behavior "https://github.com/arandomguyhere/ais_tracker/blob/main/behavior.py"
click node_intelligence "https://github.com/arandomguyhere/ais_tracker/blob/main/intelligence.py"
click node_osint_sources "https://github.com/arandomguyhere/ais_tracker/tree/main/osint/sources"
click node_entities "https://github.com/arandomguyhere/ais_tracker/blob/main/osint/entities.py"
click node_scoring "https://github.com/arandomguyhere/ais_tracker/blob/main/osint/scoring.py"
click node_correlator "https://github.com/arandomguyhere/ais_tracker/blob/main/osint/correlator.py"
click node_osint_models "https://github.com/arandomguyhere/ais_tracker/blob/main/osint/models.py"
click node_sar "https://github.com/arandomguyhere/ais_tracker/blob/main/sar_import.py"
click node_satellite "https://github.com/arandomguyhere/ais_tracker/blob/main/satellite_intel.py"
click node_sanctions "https://github.com/arandomguyhere/ais_tracker/blob/main/sanctions.py"
click node_dark_fleet "https://github.com/arandomguyhere/ais_tracker/blob/main/dark_fleet.py"
click node_venezuela "https://github.com/arandomguyhere/ais_tracker/blob/main/venezuela.py"
click node_infrastructure "https://github.com/arandomguyhere/ais_tracker/blob/main/infra_analysis.py"
click node_laden "https://github.com/arandomguyhere/ais_tracker/blob/main/laden_status.py"
click node_photos "https://github.com/arandomguyhere/ais_tracker/blob/main/shoreside_photos.py"
click node_gfw_analysis "https://github.com/arandomguyhere/ais_tracker/blob/main/gfw_integration.py"
click node_ports "https://github.com/arandomguyhere/ais_tracker/blob/main/ports_database.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_stream_runner,node_source_manager,node_source_contract,node_aisstream,node_aishub,node_marinesia,node_gfw_source,node_ingest toneBlue
class node_api_server,node_vessel_store toneAmber
class node_vessel_intel,node_weather,node_confidence,node_behavior,node_intelligence toneMint
class node_osint_sources,node_entities,node_scoring,node_correlator,node_osint_models toneRose
class node_sar,node_satellite,node_sanctions,node_dark_fleet,node_venezuela,node_infrastructure,node_laden,node_photos,node_gfw_analysis,node_ports,node_operator toneIndigo
```

## Components

### AIS collection

- [Stream runner](https://github.com/arandomguyhere/ais_tracker/blob/main/stream_area.py): `stream_area.py`
- [Source manager](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/manager.py): `ais_sources/manager.py`
- [AIS source models](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/base.py): `ais_sources/base.py`
- [AISStream](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/aisstream.py): `ais_sources/aisstream.py`
- [AISHub](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/aishub.py): `ais_sources/aishub.py`
- [Marinesia](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/marinesia.py): `ais_sources/marinesia.py`
- [GFW source](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_sources/gfw.py): `ais_sources/gfw.py`
- [AIS ingestion](https://github.com/arandomguyhere/ais_tracker/blob/main/ais_ingest.py): `ais_ingest.py`

### Tracking API

- [REST API](https://github.com/arandomguyhere/ais_tracker/blob/main/server.py): `server.py`
- [Vessel state](https://github.com/arandomguyhere/ais_tracker/blob/main/server.py): `server.py`

### Vessel intelligence

- [Vessel intelligence](https://github.com/arandomguyhere/ais_tracker/blob/main/vessel_intel.py): `vessel_intel.py`
- [Weather enrichment](https://github.com/arandomguyhere/ais_tracker/blob/main/weather.py): `weather.py`
- [Confidence scoring](https://github.com/arandomguyhere/ais_tracker/blob/main/confidence.py): `confidence.py`
- [Behavior detection](https://github.com/arandomguyhere/ais_tracker/blob/main/behavior.py): `behavior.py`
- [Intelligence reports](https://github.com/arandomguyhere/ais_tracker/blob/main/intelligence.py): `intelligence.py`

### OSINT analysis

- [News sources](https://github.com/arandomguyhere/ais_tracker/tree/main/osint/sources): `osint/sources`
- [Entity extraction](https://github.com/arandomguyhere/ais_tracker/blob/main/osint/entities.py): `osint/entities.py`
- [Relevance scoring](https://github.com/arandomguyhere/ais_tracker/blob/main/osint/scoring.py): `osint/scoring.py`
- [News correlation](https://github.com/arandomguyhere/ais_tracker/blob/main/osint/correlator.py): `osint/correlator.py`
- [OSINT models](https://github.com/arandomguyhere/ais_tracker/blob/main/osint/models.py): `osint/models.py`

### Specialist monitoring

- [SAR detections](https://github.com/arandomguyhere/ais_tracker/blob/main/sar_import.py): `sar_import.py`
- [Satellite imagery](https://github.com/arandomguyhere/ais_tracker/blob/main/satellite_intel.py): `satellite_intel.py`
- [Sanctions checks](https://github.com/arandomguyhere/ais_tracker/blob/main/sanctions.py): `sanctions.py`
- [Dark fleet analysis](https://github.com/arandomguyhere/ais_tracker/blob/main/dark_fleet.py): `dark_fleet.py`
- [Venezuela monitoring](https://github.com/arandomguyhere/ais_tracker/blob/main/venezuela.py): `venezuela.py`
- [Infrastructure analysis](https://github.com/arandomguyhere/ais_tracker/blob/main/infra_analysis.py): `infra_analysis.py`
- [Laden status](https://github.com/arandomguyhere/ais_tracker/blob/main/laden_status.py): `laden_status.py`
- [Shoreside photos](https://github.com/arandomguyhere/ais_tracker/blob/main/shoreside_photos.py): `shoreside_photos.py`
- [GFW analysis](https://github.com/arandomguyhere/ais_tracker/blob/main/gfw_integration.py): `gfw_integration.py`
- [Ports database](https://github.com/arandomguyhere/ais_tracker/blob/main/ports_database.py): `ports_database.py`

### Other components

- **Analyst**

## Connections

- Analyst → REST API: uses API
- Stream runner → Source manager: starts sources (evidence: `stream_area.py`)
- Source manager → AIS source models: uses interface (evidence: `ais_sources/manager.py`)
- Source manager → AISStream: dispatches to (evidence: `ais_sources/manager.py`)
- Source manager → AISHub: dispatches to (evidence: `ais_sources/manager.py`)
- Source manager → Marinesia: dispatches to (evidence: `ais_sources/manager.py`)
- Source manager → GFW source: dispatches to (evidence: `ais_sources/manager.py`)
- AISStream → AIS source models: implements (evidence: `ais_sources/aisstream.py`)
- AISHub → AIS source models: implements (evidence: `ais_sources/aishub.py`)
- Marinesia → AIS source models: implements (evidence: `ais_sources/marinesia.py`)
- GFW source → AIS source models: implements (evidence: `ais_sources/gfw.py`)
- Analyst → Stream runner: starts stream
- REST API → Vessel state: reads and writes (evidence: `server.py`)
- REST API → Vessel intelligence: uses (evidence: `server.py`)
- REST API → Weather enrichment: uses (evidence: `server.py`)
- REST API → Confidence scoring: uses (evidence: `server.py`)
- REST API → Behavior detection: uses (evidence: `server.py`)
- REST API → Intelligence reports: uses (evidence: `server.py`)
- REST API → SAR detections: routes to (evidence: `server.py`)
- REST API → Satellite imagery: uses (evidence: `server.py`)
- REST API → Sanctions checks: uses (evidence: `server.py`)
- REST API → Dark fleet analysis: uses (evidence: `server.py`)
- REST API → Venezuela monitoring: uses (evidence: `server.py`)
- REST API → Infrastructure analysis: uses (evidence: `server.py`)
- REST API → Laden status: uses (evidence: `server.py`)
- REST API → Shoreside photos: uses (evidence: `server.py`)
- REST API → GFW analysis: uses (evidence: `server.py`)
- REST API → Ports database: uses (evidence: `server.py`)
- News correlation → Entity extraction: extracts entities (evidence: `osint/correlator.py`)
- News correlation → Relevance scoring: scores relevance (evidence: `osint/correlator.py`)
- Entity extraction → OSINT models: uses models (evidence: `osint/entities.py`)
- Relevance scoring → OSINT models: uses models (evidence: `osint/scoring.py`)
- News correlation → OSINT models: builds events (evidence: `osint/correlator.py`)