diff --git a/docs/SDS.md b/docs/SDS.md
new file mode 100644
index 0000000..af27f54
--- /dev/null
+++ b/docs/SDS.md
@@ -0,0 +1,426 @@
+# Software Design Specification (SDS)
+
+**Project:** LifeLane — Smart Traffic Signal for Emergency Vehicles
+**Document version:** 1.0
+**Status:** MVP / proof of concept
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+This Software Design Specification describes *how* LifeLane is built: its
+architecture, module decomposition, key algorithms, data structures,
+interfaces, and the design decisions behind them. It is the design counterpart
+to the [Software Requirements Specification](SRS.md) (which defines *what* the
+system does) and expands on [docs/ARCHITECTURE.md](ARCHITECTURE.md) with a
+requirement-oriented, component-level view.
+
+### 1.2 Scope
+
+The design covers three deployable packages — `shared` (engine + simulator),
+`server` (REST + real-time transport + persistence), and `client` (React +
+Leaflet dashboard) — and the two client runtimes that let the same engine run
+either on a backend or entirely in the browser.
+
+### 1.3 Design goals
+
+1. **One engine, two homes.** The controller logic must run byte-for-byte
+   identically in Node and the browser.
+2. **Local, fast preemption.** Detection decisions are made per intersection,
+   off the central path.
+3. **Graceful degradation.** No single sensing channel is a single point of
+   failure.
+4. **Zero-dependency deployability.** No geocoding service, no API keys required
+   to run.
+5. **Interchangeable runtimes.** The UI is agnostic to whether a real backend is
+   present.
+
+---
+
+## 2. Architectural overview
+
+### 2.1 Layered model
+
+The design mirrors the three physical layers of a real deployment:
+
+| Physical layer | LifeLane realization |
+| --- | --- |
+| Onboard vehicle unit (GPS + siren + radio) | `shared/src/DeviceSimulator.js` |
+| Roadside/intersection controller (decision logic) | `shared/src/TrafficEngine.js` |
+| Central management + transport + dashboard | `server/` + `client/` |
+
+### 2.2 Package layout
+
+```
+shared/   Isomorphic traffic engine + device simulator (runs in Node and browser)
+server/   Express REST API + Socket.IO live state, SQLite (WAL) event log
+client/   React + Leaflet dashboard with two interchangeable runtimes:
+            - socketRuntime: real backend over REST + WebSocket
+            - localRuntime:  the same shared engine ticking in-browser
+```
+
+### 2.3 Runtime selection
+
+`client/src/runtime/createRuntime.js` probes `GET /api/health` on load. If it
+answers, the client builds a `socketRuntime`; otherwise it falls back to
+`localRuntime`. Both expose the identical interface:
+
+```
+{ network, state, events, mode, dispatch, recall, setAutoDispatch,
+  setRegion, canChangeRegion }
+```
+
+so every downstream component is oblivious to which is active. This is what
+makes the static GitHub Pages build fully interactive with no server.
+
+### 2.4 Component diagram
+
+```
+                       ┌─────────────────────────────────────────┐
+                       │                client/                   │
+                       │  App → useTrafficSystem → runtime         │
+                       │   MapView · ControlPanel · StatsPanel     │
+                       │   EventLog · Legend · Header              │
+                       └──────────────┬───────────────┬───────────┘
+                        socketRuntime  │               │ localRuntime
+                    (REST + Socket.IO) │               │ (in-browser tick)
+                                       ▼               ▼
+                       ┌───────────────────────┐   ┌───────────────────────┐
+                       │        server/        │   │   shared/ (in browser)│
+                       │ server.js routes.js   │   │  createTrafficSystem  │
+                       │ db.js (SQLite/WAL)    │   └───────────────────────┘
+                       └───────────┬───────────┘
+                                   ▼
+                       ┌───────────────────────────────────────────┐
+                       │                 shared/                    │
+                       │  createTrafficSystem(regionId):            │
+                       │   regions.js → network.js → TrafficEngine  │
+                       │   ← DeviceSimulator → EventBus → geo.js    │
+                       └───────────────────────────────────────────┘
+```
+
+---
+
+## 3. Module design (`shared/`)
+
+The `shared` package is the heart of the system and is deliberately free of any
+Node- or browser-specific API so it runs unmodified in both environments.
+
+### 3.1 `regions.js` — region catalog
+
+Holds the `REGIONS` catalog: for each region, a real-world lat/lng anchor, a
+grid step size, a city name, and per-axis street names. `listRegions()` enumerates
+them for the UI. Design intent: the grid *shape* (4×3) is fixed in code, but its
+*geography and labels* are data, so adding a city is a one-entry change with no
+logic touched (satisfies FR-2, FR-13). No live geocoding is used — every region
+is a small hand-anchored preset baked into the repo, keeping the system
+dependency- and key-free.
+
+### 3.2 `network.js` — topology and routing
+
+`buildNetwork(regionId)` resolves a region through `regions.js` and generates the
+intersection graph: 12 nodes with column/row coordinates, real lat/lng derived
+from the region anchor + step, and neighbor links. `findRoute()` does BFS over
+the neighbor graph to compute a vehicle's path (satisfies FR-1, FR-6).
+`listIntersectionIds()` / `listRegions()` are the lookup helpers the server
+validates dispatches against.
+
+### 3.3 `geo.js` — geodesy
+
+Haversine distance and point interpolation. Because distances are computed in
+real meters, the detection radii in `constants.js` are correct regardless of a
+region's lat/lng step size — the preemption logic never needs to know which city
+it is running in.
+
+### 3.4 `constants.js` — single source of tunables
+
+All detection, timing, and rate parameters live here (satisfies NFR-12):
+
+| Constant | Value | Role |
+| --- | --- | --- |
+| `DETECTION_RADIUS_M` | 350 m | GPS preemption trigger range |
+| `ACOUSTIC_RANGE_M` | 250 m | Siren preemption trigger range |
+| `EARLY_WARNING_RADIUS_M` | 750 m | "vehicle inbound" UI cue range |
+| `PASS_THRESHOLD_M` | 35 m | Distance considered "through" the intersection |
+| `CLEARANCE_DELAY_MS` | 2500 ms | All-red hold before resuming normal cycle |
+| `GPS_CONFIDENCE_TRIGGER` | 0.6 | Min GPS confidence to preempt |
+| `SIREN_CONFIDENCE_TRIGGER` | 0.75 | Min siren confidence to preempt |
+| `NS_GREEN_MS` / `EW_GREEN_MS` | 12000 ms | Normal green durations |
+| `ALL_RED_MS` | 1500 ms | Normal all-red transition |
+| `DEFAULT_VEHICLE_SPEED_MPS` | 14 m/s | ≈ 50 km/h cruising speed |
+| `TICK_MS` | 400 ms | Engine tick / broadcast cadence |
+| `AUTO_DISPATCH_MIN/MAX_MS` | 18000 / 40000 ms | Auto-dispatch interval bounds |
+| `MAX_EVENT_LOG` | 300 | In-memory event log cap |
+
+### 3.5 `TrafficEngine.js` — the controller
+
+The state machine and telemetry-fusion logic — layer 2. Each intersection is in
+one of four states:
+
+```
+ NORMAL CYCLING ──(GPS or siren trigger)──▶ PREEMPTED (green corridor)
+       ▲                                          │
+       │                              vehicle passes through
+       │                              (releaseIntersection)
+       │                                          ▼
+ NORMAL CYCLING ◀──(clearanceMs counts down)── ALL-RED CLEARANCE
+```
+
+Key methods:
+
+- **`ingestTelemetry(frame)`** — the fusion decision (satisfies FR-11). Computes
+  distance via `geo.js` and applies the OR-trigger:
+
+  ```
+  gpsTrigger   = distance <= DETECTION_RADIUS_M (350) AND gpsConfidence   >= 0.6
+  sirenTrigger = distance <= ACOUSTIC_RANGE_M   (250) AND sirenConfidence >= 0.75
+  preempt      = gpsTrigger OR sirenTrigger
+  ```
+
+  GPS has longer range but a lower confidence bar; siren is shorter-range but
+  demands higher confidence because false-positive sirens (other vehicles,
+  recordings) are a real concern. On a trigger, the approach axis is forced green,
+  `preempted` is set for the dashboard, and a `preemption` event is logged with
+  source + distance (FR-12).
+- **Early-warning flagging** — intersections within `EARLY_WARNING_RADIUS_M` are
+  marked `preparing` (FR-13), producing the rolling green-wave cue.
+- **Conflict handling** — a second vehicle approaching a still-preempted
+  intersection from a different axis logs a `conflict` event and holds priority
+  for the vehicle already in the intersection rather than flapping (FR-14).
+- **`releaseIntersection` / clearance** — once a vehicle is within
+  `PASS_THRESHOLD_M`, the intersection holds all-red for `CLEARANCE_DELAY_MS`
+  before resuming normal cycling (FR-15), mirroring the real safety rule that
+  cross-traffic isn't released the instant the vehicle clears.
+- **`getSnapshot()`** — returns only fields that change per tick (phase timers,
+  preemption flags, vehicle positions), *not* static topology. This keeps
+  steady-state broadcast volume proportional to live activity (NFR-2).
+- **`getEvents(limit)`** — returns the capped in-memory event log.
+
+### 3.6 `DeviceSimulator.js` — the simulated fleet (layer 1)
+
+Plays the role of real onboard hardware: it moves each dispatched vehicle along
+its route, fabricates GPS and siren confidence with realistic noise/dropout, and
+calls `engine.ingestTelemetry()` every tick. Public operations: `dispatch()`
+(FR-6), `recall()` (FR-7), and `setAutoDispatch()` (FR-8), the last driving
+periodic randomized dispatches within the auto-dispatch interval bounds.
+
+### 3.7 `EventBus.js` and `index.js`
+
+`EventBus.js` is a minimal pub/sub used to surface `log` events out of the
+engine. `index.js` exposes `createTrafficSystem(regionId)`, the factory that
+wires region → network → engine → simulator → bus together; both the Node server
+and the browser `localRuntime` call this same factory.
+
+---
+
+## 4. Module design (`server/`)
+
+### 4.1 `server.js` — composition and transport
+
+Wires Express + Socket.IO around a `createTrafficSystem(REGION_ID)` instance,
+runs the `TICK_MS` tick loop, and on each tick broadcasts a trimmed state
+snapshot plus re-broadcasts every engine `log` event. Security middleware
+installed here: `helmet` with a CSP scoped to allow OSM tile loading and
+same-origin XHR/WebSocket only (NFR-7), `compression`, and a CORS allowlist
+derived from `CORS_ORIGIN` applied to both Express and the Socket.IO handshake
+(NFR-8). A global rate limiter (300 req/min) covers all of `/api` (NFR-9).
+
+### 4.2 `routes.js` — REST surface
+
+Defines the read endpoints (`/health`, `/regions`, `/network`, `/state`,
+`/events`, `/history`) and write endpoints (`/dispatch`, `/recall/:id`,
+`/auto-dispatch`, `/telemetry`). Design details:
+
+- A stricter `writeLimiter` (60 req/min) plus `requireApiKey` guard the four
+  write endpoints (NFR-9, NFR-10).
+- `/dispatch` validates `startId`/`endId` against `listIntersectionIds()` and
+  returns 400 for unknown ids or an uncomputable route (FR-6).
+- `/telemetry` is the ingestion contract real hardware would POST; it requires a
+  `vehicleId` and numeric `lat`/`lng` and rejects malformed frames with 400
+  (FR-10). The simulator just happens to be the only caller in the demo.
+- `/events` and `/history` clamp their `limit` query (≤ 300 and ≤ 500
+  respectively) to bound response size.
+
+### 4.3 `auth.js` — optional API-key gate
+
+`requireApiKey` checks an `x-api-key` header against `TRAFFIC_API_KEY`. When the
+variable is unset it is a deliberate no-op so the demo needs no configuration; a
+real deployment sets it to require the header on every write (NFR-10).
+
+### 4.4 `db.js` — durable event log
+
+Persists the event log to SQLite via `node:sqlite` in WAL mode, so `GET /history`
+survives restarts and reads are not blocked by concurrent writes (FR-22, NFR-5).
+The database path is `DATA_DIR`.
+
+---
+
+## 5. Module design (`client/`)
+
+### 5.1 Runtimes
+
+- **`createRuntime.js`** — probes `/api/health` and constructs the appropriate
+  runtime (FR-21). It normalizes both into one interface so components never
+  branch on transport.
+- **`socketRuntime.js`** — REST for commands, Socket.IO for live `network` /
+  `state` / `events`. It maps Socket.IO `connect`/`disconnect` into a
+  `reconnecting` mode so a dropped connection is visible rather than stale
+  (FR-20, NFR-6). It does not implement `setRegion` (a backend's region is fixed).
+- **`localRuntime.js`** — runs the same `createTrafficSystem()` on a `setInterval`
+  tick inside the tab; state lives only in the tab. It implements `setRegion()`,
+  which tears down and rebuilds the engine and re-emits `network`/`state`/`events`
+  so the dashboard redraws against the new city (FR-4).
+
+### 5.2 Hook and components
+
+- **`useTrafficSystem.js`** — the React hook bridging the active runtime into
+  component state.
+- **`MapView.jsx`** — renders roads as Leaflet polylines and intersections as
+  `divIcon` markers colored by state; vehicles are 🚑 `divIcon` markers hoisted
+  to a single shared icon instance (rather than allocated per marker per render)
+  for efficiency. A `RecenterOnChange` helper calls `useMap().setView()` whenever
+  the computed center changes, because `MapContainer` only honors `center`/`zoom`
+  on first mount — without it, switching regions would strand the viewport over
+  the old city (FR-16, NFR-15).
+- **`ControlPanel.jsx`** — dispatch/recall/auto-dispatch controls, and a region
+  `<select>` (backed by `listRegions()`) rendered **only** when the active runtime
+  exposes `setRegion` / `canChangeRegion` — i.e. only in `localRuntime` (FR-17,
+  FR-4).
+- **`StatsPanel.jsx`** — active emergencies, corridors open, total preemptions,
+  average detection lead time (FR-18).
+- **`EventLog.jsx`** — the real-time event stream (FR-19).
+- **`Legend.jsx`**, **`Header.jsx`**, **`AboutModal.jsx`** — legend, mode badge
+  (FR-20), and about dialog.
+
+### 5.3 Payload merge strategy
+
+`getSnapshot()` sends only tick-varying fields; static fields (intersection
+id/name/lat/lng/neighbors, region/city name) are sent once in the `network`
+payload and merged back by id on the client (`MapView.mergeIntersections`). This
+bounds steady-state Socket.IO traffic to what is actually live (NFR-2).
+
+---
+
+## 6. Data design
+
+### 6.1 Key structures
+
+- **Region:** `{ id, cityName, streets{ ns[], ew[] }, origin{lat,lng}, step }`.
+- **Intersection (static):** `{ id, name, lat, lng, col, row, neighbors[] }`.
+- **Intersection (dynamic, per snapshot):** phase/axis, `preempted`,
+  `preparing`, clearance countdown, timers.
+- **Vehicle:** `{ id, label, route[], position, speed, gpsConfidence,
+  sirenConfidence, status }`.
+- **Event:** `{ type, ts, ...typeSpecific }` where type ∈ { dispatch, recall,
+  `preemption` (source, distance), `conflict`, clearance, … }.
+
+### 6.2 Persistence
+
+The in-memory log is a ring capped at `MAX_EVENT_LOG` (300). The durable log is
+an append in SQLite (WAL) keyed by timestamp; `GET /history` reads the most
+recent rows (bounded to 500).
+
+---
+
+## 7. Interface design
+
+### 7.1 REST
+
+| Method | Path | Auth | Purpose |
+| --- | --- | --- | --- |
+| GET | `/api/health` | none | Liveness + uptime; used for runtime probing |
+| GET | `/api/regions` | none | Active region id + catalog |
+| GET | `/api/network` | none | Static topology for the active region |
+| GET | `/api/state` | none | Current tick snapshot |
+| GET | `/api/events` | none | Recent in-memory events (≤ 300) |
+| GET | `/api/history` | none | Durable events from SQLite (≤ 500) |
+| POST | `/api/dispatch` | write | Dispatch a vehicle; validates ids/route |
+| POST | `/api/recall/:id` | write | Recall a vehicle |
+| POST | `/api/auto-dispatch` | write | Toggle auto-generation |
+| POST | `/api/telemetry` | write | Ingest a telemetry frame (hardware contract) |
+
+"write" = `writeLimiter` (60 req/min) + `requireApiKey` (no-op unless
+`TRAFFIC_API_KEY` is set).
+
+### 7.2 Real-time
+
+A Socket.IO channel emits `network` (once / on region change), `state` (every
+tick), and `events` (as they occur). The client tracks `connect`/`disconnect`
+to derive the `reconnecting` mode.
+
+### 7.3 Configuration
+
+`PORT`, `DATA_DIR`, `REGION_ID`, `CORS_ORIGIN`, `TRAFFIC_API_KEY`,
+`VITE_BACKEND_URL` — all defaulted for zero-config local dev.
+
+---
+
+## 8. Deployment design
+
+The one codebase supports three shapes (commands in the README):
+
+1. **Static (GitHub Pages)** — `client` only, built with `vite build --mode
+   demo` (subpath base), running `localRuntime`. Zero infrastructure.
+2. **Docker Compose** — `server` (Express/Socket.IO/SQLite) + `client` (nginx
+   reverse-proxying `/api` and `/socket.io`). Healthchecks gate client startup on
+   server health; event history persists to a named volume. This is the shape a
+   real municipal pilot would run.
+3. **Single Node process** — `npm run build` then `npm start`; the server serves
+   the prebuilt `client/dist` directly.
+
+---
+
+## 9. Error handling and resilience
+
+- Invalid dispatch ids or uncomputable routes → HTTP 400 with a descriptive
+  message; malformed telemetry → HTTP 400 (FR-6, FR-10).
+- Rate-limit breaches → 429 with a "slow down" message.
+- Dropped backend connection → client `reconnecting` state, not a silent freeze
+  (NFR-6).
+- Single-channel sensor noise → still preemptable via the other channel (NFR-4).
+- Server restart → durable history intact via WAL SQLite (NFR-5).
+
+---
+
+## 10. Testing strategy
+
+- **`shared/test/engine.test.js`** exercises the controller directly — grid
+  topology, BFS routing, vehicle movement, preemption on *both* the GPS and siren
+  channels, and clearance/resume — with no HTTP or browser (NFR-16).
+- **`server/test/api.test.js`** spins up a real `http.Server` on an ephemeral
+  port and drives it with `fetch`, covering the REST contract including dispatch,
+  recall, telemetry ingestion, and validation errors (NFR-17).
+- The dashboard is additionally verified by hand in a headless browser: map/
+  markers render, dispatch produces a moving marker, preemption turns an
+  intersection green with stats and the event log updating live, and demo-mode
+  region switching recenters and redraws end-to-end.
+
+---
+
+## 11. Design rationale (selected decisions)
+
+| Decision | Rationale |
+| --- | --- |
+| OR-fusion of GPS **or** siren | Neither channel is a single point of failure; each covers the other's blind spots (urban canyon vs. acoustic occlusion). |
+| Isomorphic `shared` package | Lets the static demo run the *exact* production engine in-browser, so the public demo is honest, not a mock. |
+| Snapshot carries only tick-varying fields | Keeps Socket.IO volume proportional to live activity as grids grow. |
+| Region as data, grid shape as code | Adding a city is one catalog entry; preemption logic stays city-agnostic because distances are in real meters. |
+| Fixed region per backend, live switch only in demo | Matches a real municipal deployment (one controller, one city) while keeping the demo explorable. |
+| Optional, single-secret API key | Frictionless demo by default, lockable for a real deployment without adding an auth service. |
+
+---
+
+## 12. Traceability to requirements
+
+| Requirement group | Design element |
+| --- | --- |
+| FR-1–FR-4 (network/regions) | `regions.js`, `network.js`, `localRuntime.setRegion` |
+| FR-5, FR-11–FR-15 (cycling, fusion, corridor, conflict, clearance) | `TrafficEngine.js` |
+| FR-6–FR-9 (dispatch/telemetry) | `DeviceSimulator.js` |
+| FR-10, FR-22–FR-24 (ingestion, persistence, API) | `routes.js`, `db.js`, `auth.js` |
+| FR-16–FR-21 (dashboard/runtime) | `client/` components + runtimes |
+| NFR-1–NFR-3 (performance) | `TICK_MS` tick loop, `getSnapshot()` trimming, local decisions |
+| NFR-7–NFR-10 (security) | `server.js` (helmet/CORS/global limit), `routes.js` (writeLimiter), `auth.js` |
+| NFR-11–NFR-13 (portability) | isomorphic `shared`, `constants.js`, `regions.js` |
diff --git a/docs/SRS.md b/docs/SRS.md
new file mode 100644
index 0000000..440d125
--- /dev/null
+++ b/docs/SRS.md
@@ -0,0 +1,356 @@
+# Software Requirements Specification (SRS)
+
+**Project:** LifeLane — Smart Traffic Signal for Emergency Vehicles
+**Document version:** 1.0
+**Status:** MVP / proof of concept
+
+---
+
+## 1. Introduction
+
+### 1.1 Purpose
+
+This Software Requirements Specification defines the functional and
+non-functional requirements for **LifeLane**, an IoT-enabled traffic-control
+system that detects approaching emergency vehicles (ambulances, fire, police)
+and opens a real-time *green corridor* through the intersections ahead of the
+vehicle, then clears the corridor and resumes normal signal cycling once the
+vehicle has passed.
+
+It is intended for developers, testers, reviewers, and any stakeholder
+evaluating the system's scope, behavior, and constraints. It describes *what*
+the system does; the companion [Software Design Specification](SDS.md)
+describes *how* it is built.
+
+### 1.2 Scope
+
+LifeLane is a complete, runnable simulation of an emergency-vehicle signal
+preemption system. It comprises:
+
+- An isomorphic traffic-control engine (the intersection controller logic).
+- A simulated fleet of emergency vehicles broadcasting GPS + siren telemetry.
+- A Node/Express/Socket.IO backend exposing a REST + real-time transport and a
+  persistent event log.
+- A React + Leaflet control-room dashboard.
+
+The same detection/preemption logic that would drive real roadside controllers
+drives this demo; the only difference is the telemetry source (simulated vs.
+real hardware). The system is explicitly a **proof of concept**, not a
+production traffic-control product — see §7 for out-of-scope items.
+
+### 1.3 Definitions and abbreviations
+
+| Term | Meaning |
+| --- | --- |
+| **Green corridor** | A sequence of intersections preempted to green along an emergency vehicle's route. |
+| **Preemption** | Forcing an intersection's signal to green on the vehicle's approach axis, overriding the normal cycle. |
+| **Telemetry frame** | A message carrying a vehicle's id, position, speed, and per-channel confidence scores. |
+| **Fusion** | Combining GPS and siren detection channels into a single preemption decision. |
+| **Clearance** | An all-red hold applied after a vehicle passes, before cross-traffic is released. |
+| **Region** | A hand-anchored city preset (coordinates + street names) the engine builds a grid from. |
+| **Runtime** | The client-side adapter that either talks to the backend (`socketRuntime`) or runs the engine in-browser (`localRuntime`). |
+| GNSS/GPS | Global navigation satellite positioning. |
+| V2I / DSRC / C-V2X | Vehicle-to-infrastructure radio transports (conceptual hardware layer). |
+
+### 1.4 References
+
+- [README.md](../README.md) — project overview and operating instructions.
+- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — system design and data flow.
+- [Software Design Specification](SDS.md) — design counterpart to this document.
+
+---
+
+## 2. Overall description
+
+### 2.1 Product perspective
+
+A production deployment of this class of system has three physical layers, all
+of which LifeLane models:
+
+1. **Onboard vehicle unit** — GPS/GNSS receiver, microphone array + siren
+   classifier, and a cellular/DSRC radio broadcasting telemetry frames. In
+   LifeLane this is the `DeviceSimulator`.
+2. **Roadside / intersection controller** — runs the normal signal cycle and
+   independently decides whether to preempt based on nearby telemetry. This is
+   the `TrafficEngine`.
+3. **Central traffic-management system** — aggregates telemetry and
+   intersection state for dispatch and operator dashboards; it observes and
+   coordinates but does not make preemption decisions. This is the `server`
+   plus the `client` dashboard.
+
+The system is self-contained: it requires no external geocoding or map-data
+service, and no API keys, to run.
+
+### 2.2 Product functions (summary)
+
+- Generate and normally cycle a signalized intersection grid for a chosen city
+  region.
+- Dispatch emergency vehicles, compute their routes, and stream telemetry.
+- Fuse GPS and siren telemetry per intersection and preempt to a green corridor
+  when detection thresholds are met.
+- Clear the corridor and resume normal cycling after passage.
+- Present a live operator dashboard (map, controls, rolling stats, event log).
+- Persist an event log that survives restarts.
+- Accept externally-posted telemetry via a documented ingestion API.
+
+### 2.3 User classes
+
+| User class | Description | Primary needs |
+| --- | --- | --- |
+| **Control-room operator** | Watches the network, dispatches/recalls vehicles, toggles auto-generation. | Clear live map, responsive controls, readable event log and stats. |
+| **Integrator / roadside hardware** | Posts real telemetry to the ingestion endpoint. | Stable, documented `/api/telemetry` contract; optional API-key auth. |
+| **Developer / maintainer** | Runs, tests, and extends the system. | Deterministic engine, tests, tunable constants, clear module boundaries. |
+| **Demo visitor** | Explores the public static build. | Zero-setup, fully interactive in-browser experience. |
+
+### 2.4 Operating environment
+
+- **Runtime:** Node.js ≥ 22 (server + tooling); modern evergreen browser
+  (dashboard).
+- **Storage:** SQLite (WAL mode) via `node:sqlite` for the event log.
+- **Deployment shapes:** static GitHub Pages build (client only), Docker
+  Compose (server + nginx-served client), or a single Node process serving both.
+
+### 2.5 Constraints
+
+- The `shared` engine package must contain **no Node- or browser-specific
+  APIs** so it runs unmodified in both environments.
+- A backend instance serves exactly **one region**, fixed at startup via
+  `REGION_ID`; there is no runtime endpoint to change it.
+- Preemption decisions must be made **locally** at each intersection and be
+  fast; the central layer must not be on the decision path.
+
+### 2.6 Assumptions and dependencies
+
+- Detection radii and confidence thresholds are reasonable defaults, not
+  field-calibrated values.
+- The simulated telemetry stands in for real onboard hardware speaking the same
+  ingestion contract.
+- Grids are procedurally generated from region presets, not surveyed road
+  geometry.
+
+---
+
+## 3. Functional requirements
+
+Requirements are grouped by capability. Each has a stable identifier (FR-n).
+
+### 3.1 Network and regions
+
+- **FR-1 — Grid generation.** The system shall build a signalized intersection
+  grid (4 columns × 3 rows = 12 intersections) from a data-driven region preset,
+  using the region's real-world latitude/longitude anchor, step size, and street
+  names.
+- **FR-2 — Region catalog.** The system shall ship multiple real-world-anchored
+  region presets (e.g. T. Nagar/Chennai as default, Midtown Manhattan, Sydney
+  CBD) plus a fixture region used by tests, and expose the catalog via
+  `GET /api/regions`.
+- **FR-3 — Fixed region per backend.** A backend instance shall serve a single
+  region selected at startup via `REGION_ID` and shall not expose a runtime
+  endpoint to change it.
+- **FR-4 — Live region switching (demo only).** The standalone/in-browser
+  runtime shall allow switching regions live, tearing down and rebuilding the
+  engine and redrawing the dashboard against the new city.
+
+### 3.2 Normal signal operation
+
+- **FR-5 — Normal cycling.** Each intersection shall cycle its phases on fixed
+  timers, alternating north–south green and east–west green with an all-red
+  transition, when not preempted.
+
+### 3.3 Dispatch and telemetry
+
+- **FR-6 — Dispatch.** The system shall dispatch an emergency vehicle,
+  computing a route across the grid between a start and end intersection
+  (defaulting sensibly when unspecified), and reject a dispatch for which no
+  route can be computed.
+- **FR-7 — Recall.** The system shall allow an in-flight vehicle to be recalled
+  (removed) by id.
+- **FR-8 — Auto-dispatch.** The system shall support an auto-generation mode
+  that periodically dispatches vehicles at randomized intervals, toggleable on
+  and off.
+- **FR-9 — Telemetry streaming.** For each active vehicle, the system shall
+  stream telemetry frames (id, position, speed, GPS confidence, siren
+  confidence) toward the intersections ahead of it on each tick.
+- **FR-10 — External telemetry ingestion.** The system shall accept telemetry
+  posted by external clients at `POST /api/telemetry`, requiring at minimum a
+  `vehicleId` and numeric `lat`/`lng`, and reject malformed frames with a 400.
+
+### 3.4 Detection and preemption
+
+- **FR-11 — Dual-channel fusion.** Each intersection shall independently fuse
+  GPS and siren telemetry and preempt when **either** channel authorizes it:
+  - GPS trigger: distance ≤ `DETECTION_RADIUS_M` (350 m) **and** GPS confidence
+    ≥ `GPS_CONFIDENCE_TRIGGER` (0.6);
+  - Siren trigger: distance ≤ `ACOUSTIC_RANGE_M` (250 m) **and** siren
+    confidence ≥ `SIREN_CONFIDENCE_TRIGGER` (0.75).
+- **FR-12 — Green corridor.** On preemption, the intersection shall force its
+  approach axis green, mark itself preempted for the dashboard, and log a
+  `preemption` event recording the detection source and distance.
+- **FR-13 — Early warning.** Any intersection within `EARLY_WARNING_RADIUS_M`
+  (750 m) of an inbound vehicle shall be flagged `preparing` so the dashboard
+  can show a "vehicle inbound" cue ahead of actual preemption.
+- **FR-14 — Conflict handling.** If a second vehicle approaches a still-preempted
+  intersection from a different axis, the system shall log a `conflict` event and
+  hold priority for the vehicle already in the intersection rather than flapping
+  the signal.
+- **FR-15 — Clearance and resume.** After a vehicle passes through (within
+  `PASS_THRESHOLD_M`, 35 m), the intersection shall hold all-red for
+  `CLEARANCE_DELAY_MS` (2.5 s) before resuming normal cycling.
+
+### 3.5 Dashboard and observability
+
+- **FR-16 — Live map.** The dashboard shall render the intersection grid and
+  moving vehicle markers, coloring intersections by state (normal, preparing,
+  preempted, clearance).
+- **FR-17 — Controls.** The dashboard shall provide controls to dispatch a
+  vehicle, recall vehicles, toggle auto-dispatch, and (in demo mode only) switch
+  regions.
+- **FR-18 — Rolling stats.** The dashboard shall display live aggregate stats:
+  active emergencies, corridors open, total preemptions, and average detection
+  lead time.
+- **FR-19 — Event log.** The dashboard shall show a real-time, capped event log
+  (up to `MAX_EVENT_LOG`, 300 entries in memory).
+- **FR-20 — Connection status.** The dashboard shall display the active mode
+  (live / demo / reconnecting), reflecting Socket.IO connect/disconnect events.
+- **FR-21 — Runtime auto-detection.** The client shall probe `/api/health` on
+  load and use the real backend when present, otherwise transparently fall back
+  to the in-browser engine — presenting the same interface to all UI components.
+
+### 3.6 Persistence and API surface
+
+- **FR-22 — Event persistence.** The backend shall persist the event log to
+  SQLite (WAL mode) so that `GET /api/history` survives a server restart.
+- **FR-23 — Read API.** The backend shall expose read endpoints: `GET /network`,
+  `GET /regions`, `GET /state`, `GET /events`, `GET /history`, `GET /health`.
+- **FR-24 — Write API.** The backend shall expose write endpoints: `POST
+  /dispatch`, `POST /recall/:id`, `POST /auto-dispatch`, `POST /telemetry`.
+
+---
+
+## 4. Non-functional requirements
+
+### 4.1 Performance
+
+- **NFR-1.** The engine shall advance and broadcast state on a fixed tick of
+  `TICK_MS` (400 ms).
+- **NFR-2.** Steady-state real-time payloads shall carry only fields that change
+  per tick; static network data shall be transmitted once and merged client-side
+  by id, keeping broadcast volume proportional to live activity.
+- **NFR-3.** Preemption decisions shall be computed locally per intersection so
+  that detection latency does not depend on central round-trips.
+
+### 4.2 Reliability and availability
+
+- **NFR-4.** Detection shall degrade gracefully: a single noisy channel (GPS
+  multipath, siren occlusion) shall not by itself prevent preemption, because
+  either channel can independently authorize it.
+- **NFR-5.** The event log shall survive server restarts via WAL-mode SQLite,
+  and reads shall not be blocked by concurrent writes.
+- **NFR-6.** The client shall detect a dropped backend connection and surface a
+  `reconnecting` state rather than silently going stale.
+
+### 4.3 Security
+
+- **NFR-7.** The backend shall run behind `helmet` with a Content-Security-Policy
+  scoped to the tile source and same-origin XHR/WebSocket only.
+- **NFR-8.** The backend shall enforce a CORS allowlist derived from
+  `CORS_ORIGIN` for both HTTP and the Socket.IO handshake.
+- **NFR-9.** The backend shall apply two tiers of rate limiting: a global limit
+  (300 req/min) across `/api` and a stricter limit (60 req/min) on write
+  endpoints.
+- **NFR-10.** When `TRAFFIC_API_KEY` is set, all write endpoints shall require a
+  matching `x-api-key` header; when unset, write auth is a no-op (demo default).
+
+### 4.4 Portability and maintainability
+
+- **NFR-11.** The `shared` engine shall run identically in Node and the browser
+  with no environment-specific APIs.
+- **NFR-12.** All tunable detection/timing parameters shall live in a single
+  module (`shared/src/constants.js`).
+- **NFR-13.** Adding a new region shall require only adding one entry to the
+  region catalog, with no changes to the grid or preemption logic.
+
+### 4.5 Usability
+
+- **NFR-14.** The public static deployment shall be fully interactive with zero
+  backend and zero configuration.
+- **NFR-15.** The dashboard shall recenter and redraw correctly when the region
+  changes so the viewport is never left over the previous city.
+
+### 4.6 Testability
+
+- **NFR-16.** The controller logic shall be testable directly (no HTTP or
+  browser) — grid topology, routing, movement, both preemption channels, and
+  clearance/resume.
+- **NFR-17.** The REST contract shall be testable against a real HTTP server
+  instance on an ephemeral port.
+
+---
+
+## 5. External interface requirements
+
+### 5.1 User interface
+
+A single-page control-room dashboard: a Leaflet map centered on the active
+region, a sidebar with dispatch/recall/auto-dispatch controls (and a region
+picker in demo mode), a rolling stats panel, a legend, and a scrollable event
+log. A header badge shows the live/demo/reconnecting mode.
+
+### 5.2 Application programming interface
+
+REST endpoints under `/api` (read: `health`, `regions`, `network`, `state`,
+`events`, `history`; write: `dispatch`, `recall/:id`, `auto-dispatch`,
+`telemetry`) plus a Socket.IO channel broadcasting `network`, `state`, and
+`events`. The `POST /api/telemetry` frame is the ingestion contract real onboard
+hardware would speak:
+
+```json
+{ "vehicleId": "ext-1", "lat": 13.0418, "lng": 80.2341, "status": "en-route" }
+```
+
+### 5.3 Configuration interface
+
+Environment variables (all with working defaults): `PORT`, `DATA_DIR`,
+`REGION_ID`, `CORS_ORIGIN`, `TRAFFIC_API_KEY`, and the build-time
+`VITE_BACKEND_URL`. See the README's configuration table for details.
+
+---
+
+## 6. Data requirements
+
+- **Region preset:** id, city name, per-axis street names, lat/lng origin, step
+  size.
+- **Intersection:** id, name, lat/lng, column/row, neighbors, phase state,
+  preemption flags, timers.
+- **Vehicle:** id, label, route, position, speed, per-channel confidence,
+  status.
+- **Event:** type (`preemption`, `conflict`, dispatch/recall, clearance, …),
+  timestamp, and type-specific fields (detection source, distance, ids). The
+  in-memory log is capped at `MAX_EVENT_LOG` (300); the durable log is stored in
+  SQLite and queried via `GET /history` (bounded to 500 rows per request).
+
+---
+
+## 7. Out of scope (known limitations)
+
+The following are explicitly **not** required of this MVP and are documented as
+future hardening work:
+
+- Real onboard GPS/siren hardware integration and stale-telemetry fallback.
+- Surveyed road networks, real signal-phase plans, and lane data.
+- Full multi-vehicle conflict arbitration beyond first-come priority.
+- Multi-agency authentication/authorization and a tamper-evident audit trail
+  (the single shared `TRAFFIC_API_KEY` is demo-grade).
+- Operational metrics/alerting for controller health and missed detections.
+- Field calibration of detection radii and confidence thresholds against real
+  sensor noise and city traffic.
+
+---
+
+## 8. Traceability
+
+Each functional requirement in §3 maps to concrete modules described in the
+[Software Design Specification](SDS.md): FR-1–FR-4 to `regions.js`/`network.js`;
+FR-5, FR-11–FR-15 to `TrafficEngine.js`; FR-6–FR-9 to `DeviceSimulator.js`;
+FR-10, FR-22–FR-24 to `server/src/routes.js` and `db.js`; FR-16–FR-21 to the
+`client/` components and runtimes.