project readme

README.md

@@ -1,10 +1,97 @@
 ---
 title: Dispatch Console
-emoji: 😻
-colorFrom: yellow
-colorTo: indigo
+emoji: 🗺️
 sdk: docker
+app_port: 8080
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Dispatch Console (PoC-style, self-hosted)
+
+A production-ready, self-hosted alternative to hosted PoC dispatch consoles:
+live member map, GPS tracking, SOS alert workflow, push-to-talk intercom with
+server-enforced floor control, and member/talkgroup management.
+
+## Stack
+
+- **Backend** — Node.js, Express (REST API), `ws` (WebSocket: GPS, SOS, PTT signaling, audio relay), SQLite (`better-sqlite3`), JWT auth
+- **Frontend** — React 18 + Vite, Leaflet (OpenStreetMap), AudioWorklet capture / WebAudio playback
+- **Deploy** — Docker / docker-compose; also runnable directly and on HF Spaces (this repo)
+
+## Quickstart (local, no Docker)
+
+```bash
+# 1. backend
+cd server
+npm install
+npm start                     # listens on :8080
+
+# 2. frontend (dev server with proxy)
+cd ../web
+npm install
+npm run dev                   # http://localhost:5173
+
+# 3. simulated fleet (separate terminal)
+cd ../server
+npm run sim                   # 5 units: GPS every 5 s, SOS at 25 s, PTT turns
+```
+
+Default dispatcher: **admin / admin** (override with `ADMIN_PASSWORD` on first run; change it after first login).
+
+## Quickstart (Docker)
+
+```bash
+docker compose up --build -d  # http://localhost:8080
+```
+
+Data (SQLite + JWT secret) persists in `./data`.
+
+## Architecture
+
+```
+web (React+Vite)  ──HTTP /api/*──>  Express  ──>  SQLite (better-sqlite3)
+       |                                |
+       +--WebSocket /ws (JSON + PCM) --> Hub (realtime.js)
+                                          |- GPS ingestion -> members + gps_pings
+                                          |- SOS alerts -> broadcast + REST ack/resolve
+                                          +- PTT floor control + 16 kHz PCM audio relay
+```
+
+Devices (radios/phones) connect as WebSocket **device** clients
+(`{type:"auth", token, memberId}`); dispatch consoles connect as plain
+authenticated clients and see everything. Binary WebSocket frames carry audio:
+`[1 byte type=0x01][4 bytes groupId BE][4 bytes memberId BE][16 kHz mono Int16 LE PCM]`.
+Only the current floor holder may transmit; the server enforces one speaker per
+talkgroup and relays frames to everyone subscribed to that group.
+
+## REST API (JWT Bearer)
+
+| Method | Path | Purpose |
+|---|---|---|
+| POST | `/api/login` | get token |
+| GET | `/api/me` | current user |
+| GET/POST | `/api/groups` | talkgroups |
+| GET/POST | `/api/members` | list / create members |
+| PUT/DELETE | `/api/members/:id` | edit / delete |
+| GET | `/api/members/:id/trail` | GPS history |
+| GET | `/api/sos` | alert list (`?state=open`) |
+| POST | `/api/sos/:id/ack` / `/api/sos/:id/resolve` | SOS workflow |
+| GET | `/api/calls` | call log |
+
+## Limitations (v1, honest)
+
+- Audio is relayed 16 kHz PCM over WebSocket — fine for small fleets; move to
+  Opus + a media server (LiveKit/Janus) for scale and better quality.
+- Devices authenticate with any valid dispatcher token + memberId; per-device
+  credentials are the first thing to add before real deployment.
+- Single-node, single SQLite file; no clustering.
+- The fleet simulator needs a real browser (or device client) to produce audio;
+  it exercises GPS, SOS and floor events only.
+
+## Files
+
+- `server/src/realtime.js` — WebSocket hub: auth, GPS, SOS, PTT floor, audio relay
+- `server/src/routes.js` — REST CRUD + SOS workflow
+- `server/simulator.js` — simulated fleet for testing
+- `web/src/App.jsx` — state + realtime wiring
+- `web/src/audio.js` — AudioWorklet capture / playback / SOS alarm