How omar1ramadan/fishy works
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: page.tsx App shell · FishingMap.tsx Fishing map · VesselMonitor.tsx Vessel monitor · route.ts Vessel APIs
Components 19
Browser UI
Next.js client-side dashboard and map interaction layer.
- App shell · Root application entry and shared layout for the dashboard.
app/page.tsx - Layout · Global document shell and app-wide composition.
app/layout.tsx - Fishing map · Primary geospatial interaction surface for vessels, EEZs, SAR, and infrastructure.
app/components/FishingMap.tsx - Vessel monitor · Vessel-centric analysis and detail workflow.
app/components/VesselMonitor.tsx - Vessel panel · Focused vessel details and actions.
app/components/VesselPanel.tsx - Vessel list · Selectable vessel results and browsing surface.
app/components/VesselList.tsx - Timeline · Time navigation for track inspection and gap review.
app/components/TimelineSlider.tsx - Geo filters · Country and EEZ selectors that constrain the viewport and queries.
app/components/CountryFilter.tsx - Prediction overlay · 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 · Vessel details, events, gaps, interaction, and nearby-EEZ analytics.
app/api/vessel-details/route.ts - EEZ APIs · EEZ boundaries, regions, tiles, reporting, and lookup services.
app/api/eez-boundary/route.ts - Tile APIs · Map tiles, MVT layers, SAR tiles, and fixed-infrastructure rendering.
app/api/tiles/route.ts - Style APIs · Dynamic map styling for standard and SAR layers.
app/api/generate-style/route.ts - Predict path · 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 · Standalone inference service for vessel trajectory prediction.
ml/prediction_server.py - LSTM model · Sequence model used for prediction inference.
ml/models/lstm_predictor.py - Training 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 · Global Fishing Watch data source for vessel and EEZ intelligence.
- Mapbox · Client-side map rendering and tiles/token-backed visualization.
Connections 22
- 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.