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

Infrasound 0.28 · Seismic 0.22 · Hydrophone 0.12 · ADS-B 0.10 · AIS anomaly 0.08 · Ionospheric TID 0.08 · GNSS spoofing 0.07 · Traffic 0.05. 120-second sliding window. Alert threshold: 0.55. Urgent escalation: 0.80.

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 Technical Materials

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