shield137/shockmap-api

ShockMap

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.

Why ShockMap

India depends heavily on external supply chains for critical industrial and health-system inputs. In the MVP, ShockMap focuses on two high-impact sectors:

• —Pharma: essential medicines, APIs, intermediates, and upstream source regions
• —Rare earths: strategically important minerals used in EV, electronics, and advanced industry

The core problem is not a lack of information. It is a lack of early, structured, decision-ready intelligence.

ShockMap closes that gap by combining live signal intake, graph-based propagation, and grounded action generation in one operator workflow.

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

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

Current MVP Coverage

Product Experience

Dashboard

The dashboard gives operators an immediate view of active shocks, sector activity, feed mode, and system status.

Alerts

The alerts surface is the real-time event feed for live shocks and scenario-backed incidents.

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

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?"

MVP Demo Flow

This is the cleanest walkthrough for judges, mentors, or users:

1. 1.Open the Dashboard
2. 2.Select a high-severity shock
3. 3.Enter the War Room
4. 4.Inspect propagation and evidence
5. 5.Run one response action in the simulator
6. 6.Show the risk delta and stockout extension
7. 7.Ask a question in Query

This makes the system feel operational from end to end.

3-Engine Architecture

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:

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

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

Key API Surfaces

Run Locally

Backend

cd backend
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Backend URLs:

• —API: http://localhost:8000
• —Docs: http://localhost:8000/docs
• —Health: http://localhost:8000/healthz

Frontend

cd frontend
npm install
npm run dev

Frontend URL:

• —App: http://localhost:5173

Optional ingestion refresh

python -m ingestion.shock_detector --once

Environment Variables

Tech Stack

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.