fallofpheonix · Copilot · Mar 17, 2026 · Mar 17, 2026 · Mar 24, 2026
diff --git a/API_REFERENCE.md b/API_REFERENCE.md
@@ -2,12 +2,12 @@
 
 The UDIE API is an authoritative HTTP contract exposed by the NestJS backend on `/api/v1`.
 
-## 🌐 Base URL
+## Base URL
 
 - **Local Development**: `http://localhost:3000/api/v1`
-- **Prefix Discovery**: Client-side logic in `APIClient.swift` dynamically probes `/api/v1` and `/api` to handle version drift.
+- **Prefix Discovery**: `APIClient.swift` dynamically probes `/api/v1` and `/api` to handle version drift.
 
-## 🏥 Health & Readiness
+## Health & Readiness
 
 ### `GET /health/live`
 Confirms the process is running. Returns `200 OK`.
@@ -20,7 +20,7 @@ Confirms the system is ready to serve queries. Reflects:
 
 ---
 
-## 📍 Events
+## Events
 
 ### `GET /events`
 Returns disruptions within a bounding box.
@@ -33,7 +33,7 @@ Returns disruptions within a bounding box.
 
 ---
 
-## 🏎 Route Risk
+## Route Risk
 
 ### `POST /risk`
 Computes the risk score for a polyline.
@@ -50,13 +50,13 @@ Computes the risk score for a polyline.
 ```
 
 **Response Fields:**
-- `riskScore`: Saturated score $[0, 1)$.
-- `riskLevel`: Categorical rating (LOW, MEDIUM, HIGH, CRITICAL).
+- `riskScore`: Saturated score in `[0, 1)`.
+- `riskLevel`: Categorical rating (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`).
 - `explanation`: Human-readable summary of contributing disruptions.
 
 ---
 
-## 📊 Dashboard & Intelligence
+## Dashboard & Intelligence
 
 ### `GET /city-dashboard`
 Aggregated metrics (hotspots, event counts, trend gradients) for city-level visualization.
@@ -66,8 +66,8 @@ Cell-level intelligence including historical weight and current decay state.
 
 ---
 
-## ⚙️ Constraints
+## Constraints
 
 - **Bounded Queries**: Geographic queries are limited to a maximum bounding box size (default 0.5 deg²).
 - **Contract-Valid Parameters**: Required query parameters must be provided; empty/default values result in `400 Bad Request`.
-- **Deterministic Latency**: Evaluation endpoints are optimized for sub-5ms responses via in-memory grid lookups.
+- **Deterministic Latency**: Evaluation endpoints target sub-5ms responses via in-memory grid lookups.
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
@@ -1,17 +1,17 @@
 # Architecture Reference
 
-UDIE follows a **Log-Derived Pattern**. The system distinguishes strictly between the immutable source of truth and versioned projections.
+UDIE follows a log-derived pattern. The system distinguishes strictly between the immutable source of truth and versioned projections.
 
-## 🏗 System Philosophy
+## System Philosophy
 
-- **Events Log = Authoritative State**: Every derived grid or view can be replayed from the event log.
-- **Bounded Request Logic**: Request-time logic is O(route\_cells), never O(historical\_events).
-- **Spatial Sovereignty**: The backend owns all intelligence; clients are thin observers.
+- **Events log = authoritative state.** Every derived grid or view can be replayed from the event log.
+- **Bounded request logic.** Request-time logic is O(route\_cells), never O(historical\_events).
+- **Spatial sovereignty.** The backend owns all intelligence; clients are thin observers.
 
-## 🧱 Core Subsystems
+## Core Subsystems
 
 ### 1. Ingestion Layer
-Normalizes signals from REST, WebSocket, and Kafka. Signals are validated against geographic bounds and appended to the `events_log`.
+Normalizes signals from REST and WebSocket transports. Signals are validated against geographic bounds and appended to the `events_log`.
 
 ### 2. Spatial Compute Engine
 Uses Uber H3 resolution 9 as the primary indexing unit. Aggregates event weights into decayed risk scores across a materialized `risk_cells` surface.
@@ -21,19 +21,16 @@ Uses Uber H3 resolution 9 as the primary indexing unit. Aggregates event weights
 - **Lifecycle Worker**: Manages temporal decay and event expiration.
 - **Snapshot Worker**: Captures periodic global grid states for analysis.
 
-## 🚦 Architecture Decisions (ADRs)
+## Architecture Decision Records
 
-- **ADR-001**: Event-Sourced Spatial Compute as the sole source of truth.
-- **ADR-002**: H3 Standard for discretized spatial addressing.
-- **ADR-003**: Precomputed Risk Surface to ensure sub-millisecond hot-path lookups.
-- **ADR-004**: Thin Clients to centralize intelligence authority.
-- **ADR-005**: Environment-Aware Base URL resolution for simulator vs physical device stability.
+- **ADR-001**: Event-sourced spatial compute as the sole source of truth.
+- **ADR-002**: H3 standard for discretized spatial addressing.
+- **ADR-003**: Precomputed risk surface to ensure sub-millisecond hot-path lookups.
+- **ADR-004**: Thin clients to centralize intelligence authority.
+- **ADR-005**: Environment-aware base URL resolution for simulator vs physical device stability.
 
-## ⚖️ Architectural Laws
+## Architectural Constraints
 
-All components must adhere to the **Laws of UDIE**, including:
-- **Law of Deterministic Rebuild**: $\text{state} = f(\text{logs})$.
-- **Law of Hot Path Isolation**: Evaluation cost $\perp$ event count.
-- **Law of Derived-Status Purity**: No manual mutation of materialized tables.
-
-Refer to [SYSTEM_DESIGN.md](file:///Users/fallofpheonix/Project/UDIE/SYSTEM_DESIGN.md) for detailed mathematical and theoretical foundations.
+- **Deterministic rebuild**: `state = f(logs)`. All derived state must be reproducible from the event log alone.
+- **Hot path isolation**: Evaluation cost must be independent of total event volume.
+- **Derived-state purity**: No manual mutation of materialized tables.
diff --git a/BACKEND_ARCHITECTURE.md b/BACKEND_ARCHITECTURE.md
diff --git a/CODEBASE_STRUCTURE.md b/CODEBASE_STRUCTURE.md
diff --git a/DATASETS.md b/DATASETS.md
diff --git a/DATA_PIPELINE.md b/DATA_PIPELINE.md
diff --git a/FRONTEND_ARCHITECTURE.md b/FRONTEND_ARCHITECTURE.md
diff --git a/INSTALLATION.md b/INSTALLATION.md
@@ -2,40 +2,39 @@
 
 Follow these steps to set up the UDIE ecosystem for local development and verification.
 
-## 📦 Prerequisites
+## Prerequisites
 
-- **Docker & Docker Compose**
-- **Node.js v18+ & npm**
-- **Python 3.10+** (pyenv recommended)
-- **Flutter SDK** (for mobile)
-- **PostgreSQL / PostGIS** (if running outside Docker)
+- Docker & Docker Compose
+- Node.js v18+ & npm
+- Python 3.10+ (pyenv recommended)
+- Flutter SDK (for mobile)
+- PostgreSQL / PostGIS (if running outside Docker)
 
-## 🚀 1. Backend Substrate (NestJS)
+## 1. Backend (NestJS)
 
 ```bash
 cd engine-backend
 npm install
-# Configure .env (see CONFIGURATION.md)
+cp .env.example .env   # edit as needed
 npm run db:migrate
 npm run dev
 ```
 
-## 🐍 2. Spatial Metrics Backend (Python)
+## 2. Spatial Metrics Backend (Python)
 
 ```bash
 cd udie_backend_py
 python -m venv .venv
 source .venv/bin/activate
 pip install -r requirements.txt
-python main.py
+uvicorn app.main:app --reload
 ```
 
-## 📱 3. Mobile Clients
+## 3. Mobile Clients
 
 ### iOS (Swift)
 ```bash
-cd UDIE
-open UDIE.xcodeproj
+open UDIE/UDIE.xcodeproj
 # Select Simulator/Device and Run
 ```
 
@@ -46,19 +45,15 @@ flutter pub get
 flutter run
 ```
 
-## 📊 4. Admin Dashboard
+## 4. Admin Dashboard
 
-```bash
-cd dashboard-admin
-npm install
-npm run dev
-```
+Open `dashboard-admin/index.html` directly in a browser or serve with any static file server.
 
-## 🐳 5. Full Stack (Docker)
+## 5. Full Stack (Docker)
 
 ```bash
 cd infra
-docker-compose up --build
+docker compose up --build
 ```
 
-Refer to [DEPLOYMENT_GUIDE.md](file:///Users/fallofpheonix/Project/UDIE/DEPLOYMENT_GUIDE.md) for production environment setup.
+See [CONFIGURATION.md](./CONFIGURATION.md) for environment variable reference.
diff --git a/MODEL_ARCHITECTURE.md b/MODEL_ARCHITECTURE.md