# omar1ramadan/fishy architecture

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

- Interactive diagram: https://gitdiagram.com/omar1ramadan/fishy
- Repository: https://github.com/omar1ramadan/fishy

## Overview

1. **Overall shape**
   - This repository is a two-part system: a **Next.js frontend/API layer** in the root `app/` directory, and a **separate Python ML service** under `ml/`.
   - The product is a vessel-monitoring dashboard for fishing activity, AIS gaps, and SAR-based suspicious vessel detection.

2. **Primary user interface**
   - The main entry point is `app/page.tsx`, with shared shell/layout in `app/layout.tsx`.
   - The UI is built from focused components in `app/components/`, including:
     - `FishingMap` for the main geospatial view
     - `VesselMonitor`, `VesselList`, and `VesselPanel` for vessel-centric inspection
     - `TimelineSlider` for time navigation
     - `EEZSelector` and `CountryFilter` for geographic filtering
     - `PredictionOverlay` for model output
     - `LoadingScreen` and `Globe3D` for transitional/visual polish

3. **Front-end visualization boundary**
   - Map rendering is a central subsystem, likely backed by **Mapbox GL JS** as stated in the README.
   - The map layer is not just decorative: it is the primary interaction surface for vessel tracks, EEZ boundaries, SAR overlays, and infrastructure layers.

4. **Next.js API layer as the data gateway**
   - The `app/api/*/route.ts` files form the backend boundary for the frontend.
   - These routes encapsulate all server-side data fetching, filtering, transformation, and proxying, keeping the browser from talking directly to upstream data sources.

5. **API groups and their responsibilities**
   - The route names show clear functional domains:
     - **EEZ geometry and reporting**: `eez-boundary`, `eez-regions`, `eez-tiles`, `lookup-regions`, `eez-report`
     - **Vessel analytics**: `vessel-details`, `vessel-events`, `vessel-gaps`, `vessel-interaction`, `vessels-near-eez`
     - **Map/tile services**: `tiles`, `tiles-mvt`, `tiles-sar`, `fixed-infrastructure-mvt`
     - **Styling and overlays**: `generate-style`, `sar-style`
     - **Prediction**: `predict-path`
   - Together these routes act as the application’s service layer for geospatial and vessel-intelligence workflows.

6. **Data sources and external dependencies**
   - The README explicitly ties the app to the **Global Fishing Watch API v3**, which is likely the upstream source behind most vessel and EEZ queries.
   - The frontend also depends on a **Mapbox token** for map rendering.
   - The architecture therefore has two key external integrations: vessel/EEZ intelligence from GFW and map rendering from Mapbox.

7. **AIS gap / “dark vessel” workflow**
   - A major domain concept is AIS interruption detection.
   - The `vessel-gaps`, `vessel-events`, and `vessel-interaction` routes indicate a workflow where tracks are analyzed for periods of silence, correlated with nearby EEZs or SAR detections, and presented as suspicious activity.
   - This is the main analytic loop of the product: **track vessel → detect gap → correlate with geography/SAR → surface risk in UI**.

8. **SAR and tile-based rendering**
   - The presence of `tiles-sar`, `sar-style`, and `tiles-mvt` suggests the app renders large geospatial datasets as map tiles rather than raw point collections.
   - This is important for architecture because it implies the app is optimized for **spatial streaming and viewport-based loading**, not bulk client-side data transfer.

9. **Prediction subsystem**
   - `predict-path` is the bridge between the web app and the ML prediction logic.
   - The UI’s `PredictionOverlay` likely consumes route output to display a vessel’s probable future path or “cloud” of predictions.

10. **Standalone Python ML service**
   - The `ml/` directory is a separate backend subsystem with its own runtime, dependencies, and deployment artifacts.
   - It contains:
     - `prediction_server.py` for serving predictions
     - `models/lstm_predictor.py` and `models/baseline.py`
     - trained model artifacts like `lstm_v3.h5`
     - normalization metadata and training history JSON files

11. **ML data pipeline**
   - The ML code is organized as a classic offline training pipeline:
     - `data/fetch_vessel_tracks.py` to ingest track data
     - `data/preprocess_tracks.py` and `data/detect_gaps.py` to clean and label behavior
     - `features/build_sequences.py` and `features/extract_features.py` to transform trajectories into model inputs
     - `train_v3.py` to train the LSTM model
   - This means training is not embedded in the web app; inference is the runtime concern, while training is a separate batch process.

12. **Deployment boundaries**
   - The repo includes multiple deployment descriptors: `Dockerfile.frontend`, `docker-compose.yml`, `render.yaml`, `ml/Dockerfile`, `ml/Procfile`, and `ml/railway.json`.
   - That strongly suggests the frontend and ML service can be deployed independently, with the web app calling the model service over HTTP.

13. **Configuration and secrets**
   - Runtime configuration is minimal but important:
     - `FISH_API` for Global Fishing Watch access
     - `NEXT_PUBLIC_MAPBOX_TOKEN` for client-side map rendering
   - The architecture therefore separates public browser configuration from server-side API credentials.

14. **What an architecture diagram should emphasize**
   - Draw three main boundaries:
     1. **Browser/UI**: map, filters, panels, timeline
     2. **Next.js server/API**: vessel/EEZ/tile endpoints, styling, prediction proxy
     3. **Python ML service**: trained model and trajectory prediction
   - Then connect those to external systems: **Global Fishing Watch API**, **Mapbox**, and any tile/SAR data sources implied by the route structure.

Main entry points: [`app/page.tsx`](https://github.com/omar1ramadan/fishy/blob/main/app/page.tsx) (App shell), [`app/components/FishingMap.tsx`](https://github.com/omar1ramadan/fishy/blob/main/app/components/FishingMap.tsx) (Fishing map), [`app/components/VesselMonitor.tsx`](https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselMonitor.tsx) (Vessel monitor), [`app/api/vessel-details/route.ts`](https://github.com/omar1ramadan/fishy/blob/main/app/api/vessel-details/route.ts) (Vessel APIs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ui["Browser UI"]
  node_page["App shell<br/>next entry<br/>[page.tsx]"]
  node_layout["Layout<br/>[layout.tsx]"]
  node_map["Fishing map<br/>map view<br/>[FishingMap.tsx]"]
  node_monitor["Vessel monitor<br/>inspection panel<br/>[VesselMonitor.tsx]"]
  node_panel["Vessel panel<br/>detail panel<br/>[VesselPanel.tsx]"]
  node_list["Vessel list<br/>results list<br/>[VesselList.tsx]"]
  node_timeline["Timeline<br/>time control<br/>[TimelineSlider.tsx]"]
  node_filters["Geo filters<br/>filter controls<br/>[CountryFilter.tsx]"]
  node_overlay["Prediction overlay<br/>forecast ui"]
end

subgraph group_api["Next.js API"]
  node_api_vessels["Vessel APIs<br/>route cluster<br/>[route.ts]"]
  node_api_eez["EEZ APIs<br/>route cluster<br/>[route.ts]"]
  node_api_tiles["Tile APIs<br/>route cluster<br/>[route.ts]"]
  node_api_style["Style APIs<br/>route cluster<br/>[route.ts]"]
  node_api_predict["Predict path<br/>prediction proxy<br/>[route.ts]"]
end

subgraph group_ml["Python ML"]
  node_ml_server["Prediction server<br/>python service"]
  node_ml_model["LSTM model<br/>trained model<br/>[lstm_predictor.py]"]
  node_ml_pipeline["Training pipeline<br/>offline pipeline<br/>[train_v3.py]"]
end

subgraph group_ext["External systems"]
  node_gfw[("GFW API<br/>external api")]
  node_mapbox[("Mapbox<br/>external map service")]
end

node_page -->|"uses"| node_layout
node_page -->|"renders"| node_map
node_page -->|"composes"| node_monitor
node_monitor -->|"shows"| node_panel
node_monitor -->|"browses"| node_list
node_page -->|"filters time"| node_timeline
node_page -->|"filters geo"| node_filters
node_page -->|"overlays"| node_overlay
node_map -->|"loads tiles"| node_api_tiles
node_map -->|"loads EEZ"| node_api_eez
node_monitor -->|"queries"| node_api_vessels
node_timeline -->|"narrows"| node_api_vessels
node_filters -->|"resolves"| node_api_eez
node_api_vessels -->|"fetches from"| node_gfw
node_api_eez -->|"fetches from"| node_gfw
node_api_tiles -->|"proxies"| node_gfw
node_api_style -->|"styles"| node_mapbox
node_map -->|"renders with"| node_mapbox
node_api_predict -->|"calls"| node_ml_server
node_ml_server -->|"scores with"| node_ml_model
node_ml_pipeline -->|"trains"| node_ml_model
node_overlay -->|"consumes"| node_api_predict

click node_page "https://github.com/omar1ramadan/fishy/blob/main/app/page.tsx"
click node_layout "https://github.com/omar1ramadan/fishy/blob/main/app/layout.tsx"
click node_map "https://github.com/omar1ramadan/fishy/blob/main/app/components/FishingMap.tsx"
click node_monitor "https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselMonitor.tsx"
click node_panel "https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselPanel.tsx"
click node_list "https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselList.tsx"
click node_timeline "https://github.com/omar1ramadan/fishy/blob/main/app/components/TimelineSlider.tsx"
click node_filters "https://github.com/omar1ramadan/fishy/blob/main/app/components/CountryFilter.tsx"
click node_overlay "https://github.com/omar1ramadan/fishy/blob/main/app/components/PredictionOverlay.tsx"
click node_api_vessels "https://github.com/omar1ramadan/fishy/blob/main/app/api/vessel-details/route.ts"
click node_api_eez "https://github.com/omar1ramadan/fishy/blob/main/app/api/eez-boundary/route.ts"
click node_api_tiles "https://github.com/omar1ramadan/fishy/blob/main/app/api/tiles/route.ts"
click node_api_style "https://github.com/omar1ramadan/fishy/blob/main/app/api/generate-style/route.ts"
click node_api_predict "https://github.com/omar1ramadan/fishy/blob/main/app/api/predict-path/route.ts"
click node_ml_server "https://github.com/omar1ramadan/fishy/blob/main/ml/prediction_server.py"
click node_ml_model "https://github.com/omar1ramadan/fishy/blob/main/ml/models/lstm_predictor.py"
click node_ml_pipeline "https://github.com/omar1ramadan/fishy/blob/main/ml/train_v3.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_page,node_layout,node_map,node_monitor,node_panel,node_list,node_timeline,node_filters,node_overlay toneBlue
class node_api_vessels,node_api_eez,node_api_tiles,node_api_style,node_api_predict toneAmber
class node_ml_server,node_ml_model,node_ml_pipeline toneMint
class node_gfw,node_mapbox toneRose
```

## Components

### Browser UI

Next.js client-side dashboard and map interaction layer.

- [App shell](https://github.com/omar1ramadan/fishy/blob/main/app/page.tsx): next entry · Root application entry and shared layout for the dashboard. · `app/page.tsx`
- [Layout](https://github.com/omar1ramadan/fishy/blob/main/app/layout.tsx): next layout · Global document shell and app-wide composition. · `app/layout.tsx`
- [Fishing map](https://github.com/omar1ramadan/fishy/blob/main/app/components/FishingMap.tsx): map view · Primary geospatial interaction surface for vessels, EEZs, SAR, and infrastructure. · `app/components/FishingMap.tsx`
- [Vessel monitor](https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselMonitor.tsx): inspection panel · Vessel-centric analysis and detail workflow. · `app/components/VesselMonitor.tsx`
- [Vessel panel](https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselPanel.tsx): detail panel · Focused vessel details and actions. · `app/components/VesselPanel.tsx`
- [Vessel list](https://github.com/omar1ramadan/fishy/blob/main/app/components/VesselList.tsx): results list · Selectable vessel results and browsing surface. · `app/components/VesselList.tsx`
- [Timeline](https://github.com/omar1ramadan/fishy/blob/main/app/components/TimelineSlider.tsx): time control · Time navigation for track inspection and gap review. · `app/components/TimelineSlider.tsx`
- [Geo filters](https://github.com/omar1ramadan/fishy/blob/main/app/components/CountryFilter.tsx): filter controls · Country and EEZ selectors that constrain the viewport and queries. · `app/components/CountryFilter.tsx`
- [Prediction overlay](https://github.com/omar1ramadan/fishy/blob/main/app/components/PredictionOverlay.tsx): forecast ui · Renders predicted vessel path or cloud output on top of the map. · `app/components/PredictionOverlay.tsx`

### Next.js API

Server routes that fetch, shape, and proxy geospatial and vessel data.

- [Vessel APIs](https://github.com/omar1ramadan/fishy/blob/main/app/api/vessel-details/route.ts): route cluster · Vessel details, events, gaps, interaction, and nearby-EEZ analytics. · `app/api/vessel-details/route.ts`
- [EEZ APIs](https://github.com/omar1ramadan/fishy/blob/main/app/api/eez-boundary/route.ts): route cluster · EEZ boundaries, regions, tiles, reporting, and lookup services. · `app/api/eez-boundary/route.ts`
- [Tile APIs](https://github.com/omar1ramadan/fishy/blob/main/app/api/tiles/route.ts): route cluster · Map tiles, MVT layers, SAR tiles, and fixed-infrastructure rendering. · `app/api/tiles/route.ts`
- [Style APIs](https://github.com/omar1ramadan/fishy/blob/main/app/api/generate-style/route.ts): route cluster · Dynamic map styling for standard and SAR layers. · `app/api/generate-style/route.ts`
- [Predict path](https://github.com/omar1ramadan/fishy/blob/main/app/api/predict-path/route.ts): prediction proxy · Next.js boundary that forwards prediction requests to the ML service. · `app/api/predict-path/route.ts`

### Python ML

Separate prediction service plus offline training pipeline.

- [Prediction server](https://github.com/omar1ramadan/fishy/blob/main/ml/prediction_server.py): python service · Standalone inference service for vessel trajectory prediction. · `ml/prediction_server.py`
- [LSTM model](https://github.com/omar1ramadan/fishy/blob/main/ml/models/lstm_predictor.py): trained model · Sequence model used for prediction inference. · `ml/models/lstm_predictor.py`
- [Training pipeline](https://github.com/omar1ramadan/fishy/blob/main/ml/train_v3.py): offline pipeline · Fetches tracks, preprocesses gaps, builds sequences, and trains the model. · `ml/train_v3.py`

### External systems

Upstream APIs, map rendering, and data dependencies outside the repo.

- **GFW API**: external api · Global Fishing Watch data source for vessel and EEZ intelligence.
- **Mapbox**: external map service · Client-side map rendering and tiles/token-backed visualization.

## Connections

- App shell → Layout: uses · Application page is rendered within the shared layout shell.
- App shell → Fishing map: renders · Main dashboard centers on the geospatial map.
- App shell → Vessel monitor: composes · Primary vessel analysis workflow is assembled from dashboard panels.
- Vessel monitor → Vessel panel: shows · Inspection panel exposes selected vessel details.
- Vessel monitor → Vessel list: browses · List drives vessel selection and comparison.
- App shell → Timeline: filters time · Timeline controls the active window for analysis.
- App shell → Geo filters: filters geo · Country and EEZ controls scope the displayed data.
- App shell → Prediction overlay: overlays · Forecast layer is drawn on top of the map.
- Fishing map → Tile APIs: loads tiles · Map requests spatial tiles and vector layers from server routes.
- Fishing map → EEZ APIs: loads EEZ · Map and filters consume EEZ boundaries and region data.
- Vessel monitor → Vessel APIs: queries · Vessel-centric panels request events, gaps, and nearby-EEZ context.
- Timeline → Vessel APIs: narrows · Time selection affects vessel event and gap queries.
- Geo filters → EEZ APIs: resolves · Geo filters look up regions and EEZ metadata.
- Vessel APIs → GFW API: fetches from · Server routes proxy and transform upstream vessel intelligence.
- EEZ APIs → GFW API: fetches from · EEZ reporting and geometry are derived from upstream data.
- Tile APIs → GFW API: proxies · Tile layers are sourced or composed from upstream geospatial services.
- Style APIs → Mapbox: styles · Generated styles target the map rendering stack.
- Fishing map → Mapbox: renders with · Primary visualization surface depends on Mapbox.
- Predict path → Prediction server: calls · Web API forwards prediction requests to the inference service.
- Prediction server → LSTM model: scores with · Inference server uses the trained LSTM model.
- Training pipeline → LSTM model: trains · Offline pipeline produces the model artifacts used at runtime.
- Prediction overlay → Predict path: consumes · Prediction overlay visualizes route output from the API boundary.
