Update README with detailed project overview and roadmap

README.md

@@ -1,103 +1,466 @@
-# ShockMap Intelligence Platform
-### *National Supply Chain Security & Disruption Command Center*
+# ShockMap
 
-**ShockMap** is a high-fidelity geospatial intelligence platform designed to secure India's critical import dependencies (Pharma APIs & Rare Earth Minerals). Built for the **Google Solution Challenge 2026**, it transforms unstructured global disruption signals into actionable procurement intelligence.
+**Real-time supply shock intelligence for India's critical import dependencies**
+
+ShockMap is an operator-facing intelligence platform built for the Google Solution Challenge 2026. It turns weak early signals from trade, news, and policy sources into a clear operational workflow:
+
+**detect -> assess -> decide -> act**
+
+The product is designed around a simple mission:
+
+> When a disruption hits an upstream source region, show Indian operators what is at risk, how the shock propagates, and what action changes the outcome in the next 72 hours.
 
 ---
 
-## ⚡ The 3-Engine Architecture
+## Why ShockMap
 
-ShockMap operates on a proprietary triple-engine workflow that bridges the gap between news and action:
+India depends heavily on external supply chains for critical industrial and health-system inputs. In the MVP, ShockMap focuses on two high-impact sectors:
 
-1.  **Engine 1: Signal Intelligence (NER & Extraction)**
-    *   Autonomous scanning of global trade news, policy shifts, and port telemetry via GDELT.
-    *   Entity extraction identifies provinces (e.g., Hebei), sectors (Pharma), and event types (Export Ban).
+- **Pharma**: essential medicines, APIs, intermediates, and upstream source regions
+- **Rare earths**: strategically important minerals used in EV, electronics, and advanced industry
 
-2.  **Engine 2: Propagation Intelligence (Graph Theory)**
-    *   Models the supply chain as a complex network of 60+ nodes and 70+ corridors.
-    *   Uses **Personalized PageRank** and **Louvain Community Detection** to calculate how a factory shutdown in China ripples through Indian manufacturing states.
+The core problem is not a lack of information. It is a lack of **early, structured, decision-ready intelligence**.
 
-3.  **Engine 3: Action Intelligence (Grounded RAG)**
-    *   Powered by **Gemini 2.0 Flash**.
-    *   Generates specific 72-hour action plans (e.g., "Secure 18 MT of PAP from SE Asia") grounded in NLEM policy and real-time telemetry.
+ShockMap closes that gap by combining live signal intake, graph-based propagation, and grounded action generation in one operator workflow.
 
 ---
 
-## 🚀 Key Features (The "WOW" Factors)
+## What the MVP Delivers
+
+The current MVP is built around a complete incident-response loop.
+
+### 1. Live shock feed
+- Ingests disruption signals into a structured shock feed
+- Tracks event type, province/region, sector, severity, source, and affected entities
+- Supports a **hybrid live + curated scenario mode** for reliable demos and consistent walkthroughs
+
+### 2. Shock propagation engine
+- Models upstream-to-downstream impact through a supply graph
+- Uses **NetworkX**, **Louvain communities**, and **Personalized PageRank**
+- Produces ranked affected nodes with risk, buffer pressure, substitutability, and cluster context
 
-*   **Geospatial Risk Heatmap**: Real-time visualization of supply nodes in China and absorption nodes in India.
-*   **Animated Propagation Graph**: WebGL-rendered supply network featuring **live particle flow** on disrupted corridors and **ripple-effect** shock simulations.
-*   **War Room Command Center**: Cinematic incident detail pages with stockout countdowns and multi-path response simulators.
-*   **AI Operator Analyst**: Natural language interface with streaming typewriter responses and evidence-backed citations.
+### 3. War room for every shock
+- Each shock opens into a decision surface, not just an alert
+- Surfaces:
+  - aggregate risk
+  - days to stockout
+  - exposure estimate
+  - top affected inputs
+  - source evidence
+  - recommended actions
+
+### 4. Action delta simulator
+- Lets the operator run response actions against a live scenario
+- Shows before/after impact such as:
+  - risk reduction
+  - stockout extension
+  - exposure change
+
+### 5. Grounded operator analyst
+- Natural-language query interface backed by Gemini Flash
+- Returns concise answers, citations, matched scenarios, and suggested entities to inspect next
+- Uses schema-constrained outputs, short timeouts, retrieval merging, and deterministic degradation
+
+### 6. Graph explorer
+- Interactive graph view for provinces, APIs, inputs, and downstream drugs
+- Highlights dependency corridors and the currently selected node's upstream/downstream links
+- Exposes state-level aggregate risk at a glance
 
 ---
 
-## 🛠️ Technical Stack
+## Current MVP Coverage
 
-*   **Frontend**: React 19, Vite, Leaflet (Geospatial), Sigma.js (WebGL Graph), Framer Motion.
-*   **Backend**: FastAPI, Pydantic v2, Python 3.11.
-*   **Intelligence**: Gemini 2.0 Flash (Action Gen), NetworkX (Propagation), GDELT (Live Signal Intake).
-*   **Geocoding**: Google Maps Platform (Primary) + Nominatim (Fallback).
+| Area | MVP Coverage |
+|---|---|
+| Essential medicines | 20 tracked medicines |
+| Pharma APIs | 25 API records in seed data |
+| Rare earth minerals | 8 critical minerals |
+| Live shock feed | `data/shocks.json` + curated scenario pack |
+| Graph mode | PageRank + Louvain production path |
+| Action intelligence | Grounded Flash-based plans with deterministic action output |
+| UI surfaces | Dashboard, Alerts, Shock Detail, War Room, Graph, Query |
 
 ---
 
-## 🌍 Deployment Guide
+## Product Experience
+
+### Dashboard
+The dashboard gives operators an immediate view of active shocks, sector activity, feed mode, and system status.
 
-ShockMap is production-ready and optimized for high-performance edge deployment.
+### Alerts
+The alerts surface is the real-time event feed for live shocks and scenario-backed incidents.
 
-### 1. Backend (Render)
-*   **Service Type**: Docker (Web + Background Worker)
-*   **Config**: Uses `render.yaml` for automatic infrastructure provisioning.
-*   **Environment**:
-    *   `GEMINI_API_KEY`: Required for Engine 3.
-    *   `GOOGLE_MAPS_API_KEY`: Required for Geospatial Intel.
-    *   `PORT`: 8080
+### Shock Detail / War Room
+This is the core MVP experience. A single incident page brings together:
+- shock summary
+- severity
+- top exposed inputs
+- evidence pack
+- propagation explanation
+- recommended actions
+- delta simulation
 
-### 2. Frontend (Netlify / Vercel)
-*   **Build Command**: `npm run build`
-*   **Publish Directory**: `dist`
-*   **Environment**:
-    *   `VITE_BACKEND_URL`: Points to your deployed Render API.
-    *   `VITE_GOOGLE_MAPS_API_KEY`: Client-side map rendering key.
+### Graph
+The graph page shows how disruptions travel through the network, which nodes are under the most pressure, and which states absorb the highest downstream risk.
+
+### Query
+The operator can ask plain-English questions such as:
+- "Which drugs are most exposed to Hebei shutdown?"
+- "What should procurement do in the next 72 hours?"
+- "Which nodes are highest risk in the current cluster?"
 
 ---
 
-## 💻 Local Development
+## MVP Demo Flow
 
-### Prerequisites
-*   Node.js 20+
-*   Python 3.11+
-*   Google Maps API Key
-*   Gemini API Key
+This is the cleanest walkthrough for judges, mentors, or users:
 
-### Installation
-```bash
-# Clone the repository
-git clone https://github.com/dhruva137/pharmashield.git
-cd pharmashield
+1. Open the **Dashboard**
+2. Select a high-severity shock
+3. Enter the **War Room**
+4. Inspect propagation and evidence
+5. Run one response action in the simulator
+6. Show the risk delta and stockout extension
+7. Ask a question in **Query**
+
+This makes the system feel operational from end to end.
+
+---
+
+## 3-Engine Architecture
+
+```text
+ENGINE 1                ENGINE 2                    ENGINE 3
+Signal                  Shock                       Action
+Intelligence       ->   Propagation            ->   Intelligence
+(What happened)         (What it means)             (What to do)
+```
+
+### Engine 1: Signal Intelligence
+
+Engine 1 is responsible for turning unstructured event streams into structured shocks.
+
+Current MVP path:
+- event fetch and refresh pipeline
+- disruption keyword filtering
+- structured shock records persisted to `data/shocks.json`
+- Gemini Flash used for efficient structured extraction where available
+
+Typical extracted fields:
+- `shock_type`
+- `province`
+- `sector`
+- `severity`
+- `affected_entities`
+- `estimated_duration_days`
+
+### Engine 2: Shock Propagation
+
+Engine 2 is the production risk engine in the MVP.
+
+Current production method:
+- **Knowledge graph** for supply structure
+- **Louvain community detection** for co-propagating clusters
+- **Personalized PageRank** for directional shock spread
+- **Criticality modifiers** for substitutability, buffer pressure, and concentration
+
+Propagation formula:
+
+```text
+R_i = PR_i(shock) * (1 - S_i) * exp(-B_i / tau) * C_community
+```
+
+Where:
+- `PR_i(shock)` = PageRank influence from the shocked origin
+- `S_i` = substitutability
+- `B_i` = buffer days
+- `tau` = lead-time constant by sector
+- `C_community` = community amplification factor
+
+### Engine 3: Action Intelligence
+
+Engine 3 converts risk into decisions.
+
+Current MVP behavior:
+- retrieves grounded context from local policy and reference data
+- uses Gemini Flash for structured answer/action generation
+- returns citations, confidence, suggested entities, and next actions
+- preserves a deterministic operator experience through scenario-backed degradation
+
+---
+
+## Gemini Usage Strategy
+
+ShockMap uses Gemini Flash in a cost-aware, operator-safe way.
+
+### Design principles
+- **Flash-only routing** for MVP speed and cost control
+- **Schema-constrained generation** for stable JSON outputs
+- **Short timeout budget** to avoid hanging user flows
+- **Prompt minimization** to keep token usage tight
+- **Retrieval merge** across vector and lexical evidence
+- **Deterministic fallback** so the product remains usable even when external AI calls are slow
+
+### Where Gemini is used
+- Engine 1 extraction and normalization
+- Engine 3 query answering
+- Engine 3 action-plan generation
+
+This keeps Gemini central to the product while preserving a reliable operational UX.
+
+---
+
+## Research-Informed Product Direction
+
+ShockMap is built as a practical MVP now, with a clear path toward more advanced graph learning and causal response intelligence.
+
+The current production path is intentionally strong:
+- interpretable
+- stable
+- easy to validate
+- suitable for a judging demo
+
+The next phases extend that foundation into a more advanced learning system without changing the product workflow.
+
+---
+
+## Phase Roadmap
+
+### Phase 1: MVP Operations Layer
+- hybrid live shock feed
+- production graph propagation
+- war room
+- action simulation
+- grounded operator query
+- deployable frontend + backend surfaces
+
+### Phase 2: Regional Operations Expansion
+- state-level and corridor-level overlays
+- inventory and days-of-cover modeling
+- regional reallocation workflows
+- map-based incident command views
+- expanded sector templates beyond pharma and rare earths
+
+### Phase 3: GNN Propagation Layer
+- temporal graph learning on historical disruptions
+- node embeddings across provinces, APIs, inputs, and downstream products
+- learned propagation that augments or replaces the PageRank path
+- improved ranking under multi-origin and cascading shocks
+
+### Phase 4: Procurement and Policy Platform
+- procurement workflow integration
+- escalation playbooks
+- role-based action tracking
+- stakeholder notes and audit history
+- organization-level workspaces
+
+### Phase 5: Multi-Sector National Risk Platform
+- semiconductor inputs
+- solar and clean-energy dependencies
+- EV battery chain monitoring
+- defense and advanced-manufacturing inputs
+- cross-sector risk portfolio views
 
-# Start Backend
+---
+
+## GNN Roadmap
+
+The graph layer is already structured for a future GNN upgrade.
+
+### Planned graph design
+
+**Node types**
+- province
+- factory
+- input
+- API
+- drug
+- rare earth mineral
+- route / logistics node
+- supplier / buyer entity
+
+**Node features**
+- import concentration
+- current risk score
+- buffer days
+- substitutability
+- strategic priority
+- demand criticality
+- recent shock exposure
+- regulatory pressure
+
+**Edge features**
+- trade volume
+- lead time
+- dependency strength
+- route dependence
+- concentration and exclusivity
+
+**Training targets**
+- realized shortage severity
+- price spikes
+- fill-rate stress
+- procurement delays
+- duration to recovery
+
+### Planned inference outcome
+
+The GNN phase will learn propagation patterns from observed disruptions rather than relying only on static graph logic. The product experience remains the same, but the engine underneath becomes better at:
+- multi-hop shock attribution
+- hidden cluster coupling
+- non-linear escalation
+- time-aware recovery forecasting
+
+---
+
+## Scalability Design
+
+ShockMap is being shaped to scale from a demo system into a broader intelligence platform.
+
+### 1. Stateless serving layer
+- FastAPI backend stays stateless
+- frontend remains CDN-friendly and easy to cache
+- deployment can scale horizontally without application rewrites
+
+### 2. Separate ingestion from serving
+- ingestion jobs run on a schedule
+- serving reads normalized shock data
+- this keeps user-facing latency stable even as source count grows
+
+### 3. Layered storage model
+- raw source archive
+- normalized shock records
+- graph-ready feature tables
+- retrieval-ready citation corpus
+
+### 4. Cached graph snapshots
+- precompute community structure
+- cache graph responses for UI views
+- isolate heavy recomputation to background refresh cycles
+
+### 5. Retrieval layer growth
+- lexical fallback today
+- hosted vector retrieval at scale
+- sector-specific retrieval collections later
+
+### 6. Multi-tenant evolution
+- tenant-scoped sectors, alerts, and workspaces
+- org-specific configuration and alerting
+- audit trails for action workflows
+
+### 7. Observability and reliability
+- structured logs
+- engine health status
+- shock feed mode visibility
+- deterministic degradation under model or network pressure
+
+---
+
+## Repository Structure
+
+| Path | Purpose |
+|---|---|
+| `backend/app/` | FastAPI APIs, services, models, dependency injection |
+| `frontend/src/` | React UI surfaces and client-side workflow |
+| `ingestion/` | shock detection, scrapers, and signal intake |
+| `graph/` | graph-building utilities |
+| `data/seed/` | curated seed data, scenarios, policy snippets |
+| `data/shocks.json` | live structured shock feed |
+| `docs/` | architecture and data-source notes |
+
+---
+
+## Key API Surfaces
+
+| Endpoint | Purpose |
+|---|---|
+| `/healthz` | system status and engine health |
+| `/api/v1/sectors` | sector overview |
+| `/api/v1/shocks` | live shock feed |
+| `/api/v1/shocks/{id}` | shock detail |
+| `/api/v1/shocks/{id}/war-room` | incident command surface |
+| `/api/v1/shocks/{id}/simulate-action` | action delta simulation |
+| `/api/v1/graph` | graph snapshot and state risk |
+| `/api/v1/query` | operator analyst |
+| `/api/v1/engines` | engine diagnostics |
+
+---
+
+## Run Locally
+
+### Backend
+```bash
 cd backend
+python -m venv venv
+venv\Scripts\activate
 pip install -r requirements.txt
-uvicorn app.main:app --host 0.0.0.0 --port 8080 --reload
+uvicorn app.main:app --reload
+```
+
+Backend URLs:
+- API: `http://localhost:8000`
+- Docs: `http://localhost:8000/docs`
+- Health: `http://localhost:8000/healthz`
 
-# Start Frontend
-cd ../frontend
+### Frontend
+```bash
+cd frontend
 npm install
 npm run dev
 ```
 
+Frontend URL:
+- App: `http://localhost:5173`
+
+### Optional ingestion refresh
+```bash
+python -m ingestion.shock_detector --once
+```
+
 ---
 
-## 📊 MVP Coverage
-*   **20+** Essential Medicines (NLEM)
-*   **25+** Critical Pharma APIs
-*   **8** Strategic Rare Earth Minerals
-*   **52** International Supply Corridors
-*   **15** Indian Manufacturing States
+## Environment Variables
+
+| Variable | Purpose |
+|---|---|
+| `GEMINI_API_KEY` | Gemini Flash access for extraction and action intelligence |
+| `QDRANT_URL` | hosted vector store endpoint |
+| `QDRANT_API_KEY` | vector store authentication |
+| `DEMO_MODE` | enables curated scenario mode |
+| `ENABLE_GNN` | toggles the future GNN path |
+| `ALLOWED_ORIGINS` | frontend origins for the API |
 
 ---
 
-### Google Solution Challenge 2026
-*Developed by Dhruva P Gowda*
-*MIT License*
+## Tech Stack
+
+| Layer | Stack |
+|---|---|
+| Backend | FastAPI, Pydantic v2, Python |
+| Graph | NetworkX, python-louvain, criticality scoring |
+| AI | Gemini Flash |
+| Retrieval | Qdrant + lexical fallback |
+| Frontend | React 19, Vite |
+| Ingestion | Python schedulers, source fetchers, structured normalization |
+
+---
+
+## Positioning
+
+ShockMap is not just an alert dashboard.
+
+It is a **decision engine for upstream supply shocks**:
+- detect the disruption
+- map the downstream exposure
+- simulate the response
+- act with evidence
+
+That is the MVP.
+
+---
+
+## License
+
+MIT
+
+Built for the **Google Solution Challenge 2026**.