# s-t-a-rnalin1/tidetrail architecture

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

- Interactive diagram: https://gitdiagram.com/s-t-a-rnalin1/tidetrail
- Repository: https://github.com/s-t-a-rnalin1/tidetrail

## Overview

TideTrail is an offline oil-spill detection and vessel-attribution console. An analyst selects or uploads a radar scene and runs a job; the pipeline detects and characterises slicks, estimates origin and forecast drift, joins AIS traffic, and ranks vessels. Forward source tests compare candidate releases with the observed slick, while the console presents the case and its evidence. The graph includes documented EO corroboration and upload/probe capabilities. Several implementation links rely on the SOURCE INDEX or README because the relevant source excerpts are incomplete.

Main entry points: [`app/pipeline.py`](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/pipeline.py) (Analysis pipeline), [`app/api`](https://github.com/s-t-a-rnalin1/tidetrail/tree/main/app/api) (HTTP API), [`app/api/pipeline.py`](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/api/pipeline.py) (Run endpoints), [`app/jobs/store.py`](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/jobs/store.py) (Job records)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Console and jobs"]
  node_console_ui["Case console<br/>[app.js]"]
  node_api["HTTP API"]
  node_pipeline_api["Run endpoints<br/>[pipeline.py]"]
  node_jobs[("Job records<br/>[store.py]")]
  node_pipeline["Analysis pipeline<br/>[pipeline.py]"]
  node_report["Case reporting<br/>[report.py]"]
  node_tiles["Map overlays<br/>[tiles.py]"]
end

subgraph group_detection["Scene and detection"]
  node_scenes["Scene catalog<br/>[scenes.py]"]
  node_uploads["User data<br/>[userdata.py]"]
  node_inference["SAR detection<br/>[infer.py]"]
  node_fallback["Look-alike detection<br/>[fallback.py]"]
  node_eo["EO corroboration<br/>[corroborate.py]"]
end

subgraph group_drift["Drift and sources"]
  node_fields["Metocean fields<br/>[fields.py]"]
  node_advection["Drift integration<br/>[advection.py]"]
  node_cone["Forecast cone<br/>[cone.py]"]
  node_land["Coast checks<br/>[land.py]"]
  node_source_test["Forward source tests<br/>[source.py]"]
end

subgraph group_attribution["AIS attribution"]
  node_ais_ingest[("AIS ingestion<br/>[ingest.py]")]
  node_ais_filter["Traffic filtering<br/>[filter.py]"]
  node_ais_interp["Track interpolation<br/>[interpolate.py]"]
  node_ais_score["Vessel ranking<br/>[score.py]"]
  node_dark["Dark-vessel analysis<br/>[dark.py]"]
end

subgraph group_foundation["Shared foundations"]
  node_geometry["Slick geometry<br/>[geometry.py]"]
  node_raster["Raster georeferencing<br/>[raster.py]"]
  node_crs["Coordinate transforms<br/>[crs.py]"]
  node_config["Runtime configuration<br/>[config.py]"]
end

node_analyst(("Analyst"))

node_analyst -->|"uses"| node_console_ui
node_console_ui -.->|"requests"| node_api
node_api -->|"routes runs"| node_pipeline_api
node_pipeline_api -->|"runs analysis"| node_pipeline
node_pipeline_api -->|"reads progress"| node_jobs
node_pipeline_api -->|"lists jobs"| node_jobs
node_api -->|"handles uploads"| node_uploads
node_api -->|"starts scene runs"| node_scenes
node_pipeline -->|"detects slicks"| node_inference
node_inference -->|"uses fallback"| node_fallback
node_pipeline -->|"characterises slicks"| node_geometry
node_pipeline -->|"corroborates optically"| node_eo
node_pipeline -->|"loads fields"| node_fields
node_pipeline -->|"integrates drift"| node_advection
node_pipeline -->|"forecasts flow"| node_cone
node_pipeline -->|"checks coast"| node_land
node_pipeline -->|"tests sources"| node_source_test
node_pipeline -->|"queries AIS"| node_ais_ingest
node_pipeline -->|"filters traffic"| node_ais_filter
node_pipeline -->|"reconstructs tracks"| node_ais_interp
node_pipeline -->|"ranks vessels"| node_ais_score
node_pipeline -->|"checks dark vessels"| node_dark
node_pipeline -.->|"persists results"| node_jobs
node_pipeline -->|"renders overlays"| node_tiles
node_report -->|"reads case records"| node_jobs
node_raster -->|"uses transforms"| node_crs
node_geometry -->|"uses projection"| node_crs
node_pipeline -->|"loads scene"| node_scenes
node_pipeline -->|"loads raster"| node_raster
node_pipeline -->|"uses settings"| node_config

click node_console_ui "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/static/app.js"
click node_api "https://github.com/s-t-a-rnalin1/tidetrail/tree/main/app/api"
click node_pipeline_api "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/api/pipeline.py"
click node_jobs "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/jobs/store.py"
click node_scenes "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/scenes.py"
click node_uploads "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/userdata.py"
click node_pipeline "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/pipeline.py"
click node_inference "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ml/infer.py"
click node_fallback "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ml/fallback.py"
click node_geometry "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/geometry.py"
click node_raster "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/raster.py"
click node_eo "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/eo/corroborate.py"
click node_fields "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/fields.py"
click node_advection "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/advection.py"
click node_cone "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/cone.py"
click node_land "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/land.py"
click node_source_test "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/source.py"
click node_ais_ingest "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/ingest.py"
click node_ais_filter "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/filter.py"
click node_ais_interp "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/interpolate.py"
click node_ais_score "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/score.py"
click node_dark "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/dark.py"
click node_report "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/api/report.py"
click node_tiles "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/viz/tiles.py"
click node_crs "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/crs.py"
click node_config "https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/config.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_console_ui,node_api,node_pipeline_api,node_jobs,node_pipeline,node_report,node_tiles toneBlue
class node_scenes,node_uploads,node_inference,node_fallback,node_eo toneAmber
class node_fields,node_advection,node_cone,node_land,node_source_test toneMint
class node_ais_ingest,node_ais_filter,node_ais_interp,node_ais_score,node_dark toneRose
class node_geometry,node_raster,node_crs,node_config,node_analyst toneIndigo
```

## Components

### Console and jobs

- [Case console](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/static/app.js): `app/static/app.js`
- [HTTP API](https://github.com/s-t-a-rnalin1/tidetrail/tree/main/app/api): `app/api`
- [Run endpoints](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/api/pipeline.py): `app/api/pipeline.py`
- [Job records](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/jobs/store.py): `app/jobs/store.py`
- [Analysis pipeline](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/pipeline.py): `app/pipeline.py`
- [Case reporting](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/api/report.py): `app/api/report.py`
- [Map overlays](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/viz/tiles.py): `app/viz/tiles.py`

### Scene and detection

- [Scene catalog](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/scenes.py): `app/scenes.py`
- [User data](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/userdata.py): `app/userdata.py`
- [SAR detection](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ml/infer.py): `app/ml/infer.py`
- [Look-alike detection](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ml/fallback.py): `app/ml/fallback.py`
- [EO corroboration](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/eo/corroborate.py): `app/eo/corroborate.py`

### Drift and sources

- [Metocean fields](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/fields.py): `app/drift/fields.py`
- [Drift integration](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/advection.py): `app/drift/advection.py`
- [Forecast cone](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/cone.py): `app/drift/cone.py`
- [Coast checks](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/land.py): `app/drift/land.py`
- [Forward source tests](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/drift/source.py): `app/drift/source.py`

### AIS attribution

- [AIS ingestion](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/ingest.py): `app/ais/ingest.py`
- [Traffic filtering](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/filter.py): `app/ais/filter.py`
- [Track interpolation](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/interpolate.py): `app/ais/interpolate.py`
- [Vessel ranking](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/score.py): `app/ais/score.py`
- [Dark-vessel analysis](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/ais/dark.py): `app/ais/dark.py`

### Shared foundations

- [Slick geometry](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/geometry.py): `app/geo/geometry.py`
- [Raster georeferencing](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/raster.py): `app/geo/raster.py`
- [Coordinate transforms](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/geo/crs.py): `app/geo/crs.py`
- [Runtime configuration](https://github.com/s-t-a-rnalin1/tidetrail/blob/main/app/config.py): `app/config.py`

### Other components

- **Analyst**

## Connections

- Analyst → Case console: uses (evidence: `README.md`)
- Case console → HTTP API: requests
- HTTP API → Run endpoints: routes runs (evidence: `app/main.py`)
- Run endpoints → Analysis pipeline: runs analysis (evidence: `app/api/pipeline.py`)
- Run endpoints → Job records: reads progress (evidence: `app/api/pipeline.py`)
- Run endpoints → Job records: lists jobs (evidence: `app/api/pipeline.py`)
- HTTP API → User data: handles uploads (evidence: `app/api/data.py`)
- HTTP API → Scene catalog: starts scene runs (evidence: `app/api/detect.py`)
- Analysis pipeline → SAR detection: detects slicks (evidence: `app/pipeline.py`)
- SAR detection → Look-alike detection: uses fallback (evidence: `app/ml/infer.py`)
- Analysis pipeline → Slick geometry: characterises slicks (evidence: `app/pipeline.py`)
- Analysis pipeline → EO corroboration: corroborates optically (evidence: `app/pipeline.py`)
- Analysis pipeline → Metocean fields: loads fields (evidence: `app/pipeline.py`)
- Analysis pipeline → Drift integration: integrates drift (evidence: `app/pipeline.py`)
- Analysis pipeline → Forecast cone: forecasts flow (evidence: `app/pipeline.py`)
- Analysis pipeline → Coast checks: checks coast (evidence: `app/pipeline.py`)
- Analysis pipeline → Forward source tests: tests sources (evidence: `app/pipeline.py`)
- Analysis pipeline → AIS ingestion: queries AIS (evidence: `app/pipeline.py`)
- Analysis pipeline → Traffic filtering: filters traffic (evidence: `app/pipeline.py`)
- Analysis pipeline → Track interpolation: reconstructs tracks (evidence: `app/pipeline.py`)
- Analysis pipeline → Vessel ranking: ranks vessels (evidence: `app/pipeline.py`)
- Analysis pipeline → Dark-vessel analysis: checks dark vessels (evidence: `app/pipeline.py`)
- Analysis pipeline → Job records: persists results (evidence: `app/pipeline.py`)
- Analysis pipeline → Map overlays: renders overlays (evidence: `app/pipeline.py`)
- Case reporting → Job records: reads case records (evidence: `app/api/report.py`)
- Raster georeferencing → Coordinate transforms: uses transforms (evidence: `app/geo/raster.py`)
- Slick geometry → Coordinate transforms: uses projection (evidence: `app/geo/geometry.py`)
- Analysis pipeline → Scene catalog: loads scene (evidence: `app/pipeline.py`)
- Analysis pipeline → Raster georeferencing: loads raster (evidence: `app/pipeline.py`)
- Analysis pipeline → Runtime configuration: uses settings (evidence: `app/pipeline.py`)
