Services

• Backend: FastAPI + Uvicorn, Python 3.11+, entry core/api/main.py
• Database: PostgreSQL 15 + PostGIS 3.3 via SQLAlchemy 2.0 asyncio + Alembic migrations. Fallback to SQLite for local dev.
• Cache / Pub-sub: Redis 7, sensor event bus, vessel position cache, probability grid
• Drift subprocess: OpenDrift 1.14.9 (Python 3.12 via OPENDRIFT_PYTHON env var) + Gaussian analytical fallback
• Ocean data: CMEMS via copernicusmarine library + disk cache (~/.suezcanal/cache/). Open-Meteo for wind (no key required).
• Dashboard: React 18 + Vite 6. Dev port 5173, Docker port 3000.

API Domains (9 modules)

• alerts: distress creation, result retrieval and live status stream on /ws/events
• drift: trajectory computation (background task) + GeoJSON export
• anomaly: multi-sensor event query + WebSocket /api/v1/anomalies/live
• forensic: signed packet retrieval, verification, CSV/JSON export
• integrations: multi-protocol parse, chokepoint stats, vessel GeoJSON
• vessels: AIS registry stats and incremental updates
• ingest: Twilio SMS/WhatsApp + Telegram + generic webhook receivers
• probability: survival scoring, interception time, active signal priority queue
• weather: CMEMS / Open-Meteo point and grid endpoints

Database Schema (4 tables)

• alert_events: distress signals with lat/lon/status
• drift_results: GeoJSON trajectories, 6/12/24h cones, metadata
• forensic_events: append-only signed packets (Ed25519 + BLAKE3)
• anomaly_events: per-sensor detections with confidence, type, position

Drift Simulation Pipeline

Alert received → _process_drift() as FastAPI background task → DriftEngine.compute() → fetch wind from Open-Meteo (live, current position) + currents from CMEMS (cached) → build JSON payload → subprocess.run(opendrift_runner.py, timeout=180s) → parse GeoJSON result → store in DB → WebSocket broadcast → optional TimeZero push + forensic sign.

Sensor Correlation Weights

The correlation model keeps infrasound and seismic input at the top of the stack, follows with hydrophone, ADS-B and AIS anomaly signals, and keeps TID, GNSS spoofing and traffic lower in the ranking. Thresholds stay split between alert and urgent states for review.

Key Configuration Variables

Defined in core/config.py as Pydantic Settings. Key vars: DATABASE_URL, REDIS_URL, WITNESS_ENDPOINTS, SUEZCANAL_SIGNING_KEY, CMEMS_USERNAME/CMEMS_PASSWORD, AISSTREAM_KEY, OPENDRIFT_PYTHON, per-sensor enable flags (INFRASOUND_ENABLED, SEISMIC_ENABLED, GNSS_ENABLED...), MOCK=true for development without hardware or live APIs, TIMEZERO_ENABLED/TIMEZERO_HOST/TIMEZERO_PORT.

Mode 1: Docker Compose (Recommended)

Full stack: backend, dashboard, PostgreSQL+PostGIS, Redis in one compose. Requires Docker Desktop.

git clone https://github.com/suezcanalxyz/seacommons.git
cd seacommons
cp .env.example .env   # set CMEMS_USERNAME, CMEMS_PASSWORD, AISSTREAM_KEY
docker compose up -d

API → localhost:8000 · Dashboard → localhost:3000 · Swagger → localhost:8000/docs

Mode 2: MOCK Mode (No credentials needed)

Set MOCK=true in .env. Sensor drivers return synthetic data, OpenDrift falls back to the Gaussian model, no CMEMS or AISSTREAM keys required. Fastest way to evaluate the platform.

Mode 3: Local Dev (Backend + Dashboard)

pip install -e '.[dev]'
cd seacommons && npm install && npm run dev   # dashboard → :5173
uvicorn core.api.main:app --reload      # API → :8000

Note: the dev server stays running in the terminal by design. Once the page is visible, leave that process open and stop it manually with Ctrl+C only when you are done.

Mode 4: Real OpenDrift (Split Python Env)

OpenDrift requires Python 3.12 with specific netCDF4 dependencies, separate from the API env.

OPENDRIFT_PYTHON=/path/to/opendrift-env/bin/python
OPENDRIFT_PARTICLES=128
OPENDRIFT_TIMESTEP_SECONDS=900

Mode 5: Ship Edge Deployment

bash edge/firmware/firstboot.sh
docker compose -f edge/docker-compose.ship.yml up -d

Submit a Distress Alert

curl -X POST http://localhost:8000/api/v1/alert \
  -H "Content-Type: application/json" \
  -d '{
    "lat": 35.376,
    "lon": 14.429,
    "persons": 45,
    "vessel_type": "rubber_boat",
    "domain": "ocean_sar"
  }'

Returns {"event_id": "...", "status": "processing"}. Poll /api/v1/alert/{event_id} or connect to /ws/events.

Retrieve Drift Result

curl http://localhost:8000/api/v1/alert/{event_id}/geojson

Returns FeatureCollection: trajectory LineString + 6h/12h/24h cone Polygons + impact Point. All WGS-84.

Verify Forensic Packet

curl http://localhost:8000/api/v1/forensic/{event_id}/verify

Query Active Vessels

curl http://localhost:8000/api/v1/integrations/vessels/geojson
curl "http://localhost:8000/api/v1/anomalies?since_minutes=60&type=all"

Reading Order for Public Documentation

ARCHITECTURE.md → SCENARIOS.md → FORENSIC_FORMAT.md → VESSEL_INTEGRATION_PLAN.md → SIMULATION_DEMO_PLAN.md → BOM.md

Endpoint	Method	Purpose
/api/v1/alert	POST	Submit distress signal → triggers drift + forensic chain
/api/v1/alert/{id}	GET	Alert status and metadata
/api/v1/alert/{id}/geojson	GET	Drift result as GeoJSON FeatureCollection
/ws/events	WebSocket	Live alert status updates
/api/v1/drift	POST	Compute drift trajectory (any domain, no alert)
/api/v1/drift/{id}/geojson	GET	Trajectory + search cones as GeoJSON
/api/v1/anomalies	GET	Query anomalies (since_minutes, type, lat/lon/radius)
/api/v1/anomalies/live	WebSocket	Live multi-sensor correlation stream
/api/v1/forensic/{id}	GET	Retrieve signed forensic packet (full)
/api/v1/forensic/{id}/verify	GET	Verify Ed25519 signature + BLAKE3 hash integrity
/api/v1/forensic/export	GET	Export forensic log (JSON or CSV, date filter)
/api/v1/integrations/vessels/geojson	GET	All known vessel positions as GeoJSON
/api/v1/chokepoints	GET	Vessel counts at strategic chokepoints
/api/v1/probability/active	GET	Priority-ranked active SAR signals
/api/v1/probability/survival	POST	Compute survival probability for given conditions
/api/v1/weather	GET	Wind, wave and ocean conditions at position
/api/v1/ingest/twilio/sms	POST	Twilio SMS webhook receiver
/api/v1/ingest/twilio/whatsapp	POST	Twilio WhatsApp webhook receiver
/api/v1/ingest/telegram	POST	Telegram Bot API webhook receiver
/api/v1/ops/summary	GET	System health: services, vessel stats, open alerts
/health	GET	Service health check