Skip to content
BranchesTags

Repository files navigation

⚓ Fleet Command — Real-Time Ship Tracking System

A real-time maritime fleet tracking and command system for the Strait of Hormuz. Features live ship simulation, AI-powered distress analysis, weather-aware routing, and role-based operations for Command and Captain roles.

How to Run Locally

Prerequisites

  • Node.js 20+
  • npm
  • Supabase project (for persistence)
  • Clerk account (for authentication)
  • Groq API key (for AI analysis)

1. Backend (start first)

cd backend
npm install
node index.js

Expected output:

🚀 Backend listening on http://localhost:4000
🔌 WebSocket at ws://localhost:4000/ws
💚 Health check at http://localhost:4000/health
🚢 Simulator started — 15 ships, tick 1000ms
🌊 Weather service started (5-min refresh)

2. Frontend (start second)

cd frontend
npm install
npm run dev

Opens on http://localhost:3000

3. Access

  • Open http://localhost:3000 → Sign in with Clerk
  • Navigate to /command for Command dashboard
  • Navigate to /captain for Captain view

Required Environment Variables

Backend (backend/.env)

PORT=4000
FRONTEND_URL=http://localhost:3000
CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
SUPABASE_URL=
SUPABASE_SERVICE_ROLE_KEY=
GROQ_API_KEY=

Frontend (frontend/.env.local)

NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=
CLERK_SECRET_KEY=
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up
NEXT_PUBLIC_SUPABASE_URL=
NEXT_PUBLIC_SUPABASE_ANON_KEY=
NEXT_PUBLIC_BACKEND_URL=http://localhost:4000
NEXT_PUBLIC_WS_URL=ws://localhost:4000/ws

Supabase Setup SQL

Run the following in the Supabase SQL Editor:

create table ship_snapshots (
  id uuid default gen_random_uuid() primary key,
  snapshot_time timestamptz default now(),
  ships_data jsonb not null,
  created_at timestamptz default now()
);

create table alerts (
  id uuid default gen_random_uuid() primary key,
  type text not null,
  ship_id text not null,
  message text,
  severity text default 'medium',
  acknowledged boolean default false,
  created_at timestamptz default now()
);

create table directives (
  id uuid default gen_random_uuid() primary key,
  ship_id text not null,
  issued_by text,
  type text not null,
  payload jsonb,
  status text default 'pending',
  created_at timestamptz default now()
);

create table distress_messages (
  id uuid default gen_random_uuid() primary key,
  ship_id text not null,
  raw_message text,
  ai_analysis jsonb,
  created_at timestamptz default now()
);

Tech Stack

Layer Technology
Frontend Next.js 16 (App Router), React, TypeScript, Tailwind CSS
Map Leaflet + react-leaflet
Auth Clerk (RBAC: command / captain)
Backend Node.js, Express, WebSocket (ws library)
Database Supabase (PostgreSQL)
AI Groq API (LLaMA 3.3 70B)
Weather Open-Meteo (free, no API key)

Architecture

┌─────────────┐     WebSocket      ┌─────────────────┐
│  Frontend   │◄──────────────────►│    Backend       │
│  Next.js    │    (STATE_UPDATE,   │  Express + WS    │
│  Port 3000  │     ALERT, etc.)   │  Port 4000       │
└─────────────┘                    └──────┬──────────┘
                                          │
                                   ┌──────┴──────┐
                                   │  Simulator   │
                                   │  Engine      │
                                   │  (1Hz tick)  │
                                   └──────┬──────┘
                                          │
                              ┌───────────┼───────────┐
                              ▼           ▼           ▼
                         Supabase    Open-Meteo    Groq AI
                         (persist)   (weather)    (NLP)

Features

Core

  • 15 ships simulating in the Strait of Hormuz with realistic positions and routes
  • A* grid-based pathfinding constrained to navigable water polygon
  • 1Hz simulation tick with position updates, fuel depletion, and status management
  • WebSocket real-time sync (< 500ms latency, 5+ simultaneous clients)
  • 60fps interpolated ship movement on map (requestAnimationFrame)

Ship Statuses

  • normal — ship en route to destination
  • rerouting — recalculating path around zones
  • distressed — captain escalated emergency
  • stopped — manually held or out of fuel
  • stranded — no valid route to destination
  • arrived — reached destination port
  • insufficient_fuel — predicted to run out before arrival (continues moving)
  • out_of_fuel — fuel depleted (stops moving)

Weather Intelligence

  • Real-time weather from Open-Meteo (wind speed + wave height)
  • 5×5 grid overlay on map showing adverse conditions
  • Adverse threshold: wind > 25 kn OR wave > 2.5m
  • 30% fuel burn penalty in adverse weather cells
  • Storm icon indicator on affected ships
  • Refreshes every 5 minutes with fallback data

Alerts & Prioritization

  • Geofence breach — ship enters restricted zone (< 1 second detection)
  • Proximity warning — ships within 2 km (hysteresis clears at 2.5 km)
  • Fuel prediction — alerts when ship can't reach destination with remaining fuel
  • Zone prediction — alerts when ship will enter restricted zone within 5 minutes
  • Stranded — no valid path exists
  • Priority scoring: base type score × severity multiplier + urgency bonuses
  • Audio alert (440Hz Web Audio tone) on new alerts

AI Integration (Groq / LLaMA 3.3 70B)

  • POST /api/ai/analyze-distress — structured distress message analysis
  • POST /api/ai/fleet-advisor — proactive fleet management suggestions
  • AI analysis includes: severity, category, injury count, damage estimate, recommended action
  • Results saved to Supabase and displayed in real-time

Role-Based Access (Clerk)

  • Command — full fleet overview, draw zones, issue directives, AI advisor
  • Captain — own ship status, directives inbox, distress composer
  • Roles from Clerk publicMetadata.role ("command" | "captain")

Playback & History

  • 60-minute history at 30-second snapshot resolution
  • Timeline scrubber with play/pause and speed controls (1×/2×/5×)
  • Event dots on timeline for alert visualization
  • "PLAYBACK MODE" banner when scrubbing, "Live" button to return

API Endpoints

Method Path Description
GET /health Server status, ship count, client count
GET /api/ships Current state of all 15 ships
GET /api/alerts All alerts (prioritized)
GET /api/directives All directives from Supabase
GET /api/weather Current weather grid and adverse cells
GET /api/history Last 60 min snapshots at 30s resolution
POST /api/ai/analyze-distress AI distress message analysis
POST /api/ai/fleet-advisor AI fleet management suggestions

WebSocket Messages

Direction Type Description
Server→Client INIT_STATE Full fleet state on connect
Server→Client INIT_ALERTS Unacknowledged alerts on connect
Server→Client STATE_UPDATE Periodic ship positions + weather
Server→Client ALERT New alert fired
Server→Client ALERT_ACKNOWLEDGED Alert was acknowledged
Server→Client DIRECTIVE_ISSUED New directive issued
Server→Client CAPTAIN_RESPONDED Captain response to directive
Server→Client ZONE_ADDED New restricted zone
Server→Client ZONE_REMOVED Zone removed
Client→Server ACKNOWLEDGE_ALERT Acknowledge an alert
Client→Server ISSUE_DIRECTIVE Issue directive to ship
Client→Server ADD_ZONE Create restricted zone
Client→Server REMOVE_ZONE Remove restricted zone
Client→Server CAPTAIN_RESPONSE ACCEPT or ESCALATE_DISTRESS

Documented Assumptions / Not Implemented

1. Docker / docker compose — not implemented. Run backend and frontend manually (see above).
2. Railway deploy — not implemented. System runs locally only.
3. Real coastline data — not used. A simplified navigable water polygon is used as specified.
4. Multiple route options (bonus) — not implemented.
5. Ship-to-ship assistance (bonus) — not implemented.
6. AI fleet advisor proactive suggestions (bonus) — partially implemented via /api/ai/fleet-advisor endpoint.
7. Predictive alerts (bonus) — implemented via 5-minute projection in tick loop.

Bonus Features Implemented

Feature Status Details
Predictive zone alerts ✅ Full 5-minute forward projection, fires alert with ETA
Predictive fuel alerts ✅ Full Distance-short calculation, severity-based
Proximity hysteresis ✅ Full Warn at < 2km, clear at > 2.5km, no flapping
Weather integration ✅ Full Open-Meteo real data, 5×5 grid, fuel penalty
AI distress analysis ✅ Full Groq LLaMA 3.3 70B, structured JSON output
AI fleet advisor ✅ Partial Endpoint works, UI panel for accept/dismiss
Playback timeline ✅ Full 60min history, scrub, speed controls, event dots
Audio alerts ✅ Full Web Audio API, 440Hz tone on new alerts

About

web-development-error-404 created by GitHub Classroom

web-development-error-404.vercel.app

Resources

Readme
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages