SurakshaSetu

Intelligent Hazard-Based Red-Zone Identification, Carrying-Capacity Assessment, and Relocation Prioritisation for Vulnerable Habitations

SurakshaSetu is a working React + TypeScript and FastAPI MVP for district disaster-management officials. It combines explainable hazard risk, population exposure, candidate-site capacity, access context, official warnings and field observations in one responsive decision-support interface.

Safety boundary: SurakshaSetu never issues evacuation, relocation, or land-acquisition orders. Every priority and route recommendation is provisional and displays Official verification required. Final action must be verified and authorised by DDMA, SDMA, or another competent authority.

The default pilot is Rudraprayag, Uttarakhand because the synthetic demonstration focuses on landslide, rainfall, flood and road-isolation conditions. The interface also demonstrates district selection. Every included operational record is clearly labelled synthetic.

What works

• React + TypeScript responsive command dashboard with district selector.
• Interactive SVG GIS demonstration with habitation inspection, layer state and provisional route analysis.
• Explainable village risk profiles with component scores, confidence and source lineage.
• Candidate-site comparison where effective capacity is the minimum essential constraint and land verification can force availability to zero.
• Filterable relocation-priority queue with verification status.
• Mobile field survey with dynamic score preview, consent, no Aadhaar field, device-local offline draft and later submission flow.
• Controlled data-upload preview for CSV, GeoJSON, Shapefile ZIP and GeoTIFF.
• FastAPI endpoints for static risk, immediate priority, capacity, villages, alerts and source metadata.
• PostGIS schema covering every requested core entity, provenance, audit and rollback metadata.
• Schema-compatible mock adapters for credential-controlled sources.
• Synthetic GeoJSON and CSV import templates.
• Automated scoring and capacity tests.
• Docker Compose for React/Nginx, FastAPI and PostGIS.

Repository layout

frontend/                 React 19 + TypeScript + Vite UI
backend/app/              FastAPI app, scoring, capacity and adapters
backend/tests/            Calculation tests
database/migrations/      PostGIS schema
data/sample/              Clearly marked synthetic GeoJSON
data/templates/           Local-government import CSV templates
docs/                     API reference and data dictionary
docker-compose.yml        Full local deployment
.env.example              Configuration template without secrets

Quick start

Option A — Docker (complete stack)

1. Copy .env.example to .env and change the local database password.
2. From the repository root run:

docker compose up --build

Open:

• Application: http://localhost:8080
• API documentation: http://localhost:8000/docs
• API health: http://localhost:8000/health

The initial SQL migration is mounted into the PostGIS image and runs on the first database creation.

Option B — frontend only

cd frontend
corepack enable
pnpm install
pnpm build

Deploy the generated frontend/dist/ directory to Cloudflare Pages, Netlify, Vercel static hosting, S3/CloudFront, Nginx or any other static host. This mode uses the bundled synthetic demonstration records and all UI calculations remain functional.

Option C — local development

Frontend:

cd frontend
pnpm install
pnpm dev

Backend:

cd backend
python -m venv .venv
# Windows: .venv\Scripts\activate
# macOS/Linux: source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload

Demonstration workflow

1. Open Overview and inspect the Orange rainfall alert, exposed population, risk counts and data confidence.
2. Click Phata or Ukhimath on the map. Review the component score, vulnerable groups, shelter and source lineage.
3. Open Risk map, toggle layers and calculate the provisional safe route. Observe the field-verification warning.
4. Open Site capacity, compare sites and select Kund Plateau A. Water is the bottleneck even though housing capacity is higher. Select Tilwara Expansion to see unverified land yield zero available capacity.
5. Open Priority queue and filter Critical + Pending cases. Review the official-verification status.
6. Open Field survey, enter danger/access/vulnerability observations and watch the explainable priority preview change. Save an offline draft, then submit it for verification.
7. Open Data management and choose a supported file to see a validation-preview result; no data is committed by the demonstration UI.
8. Open http://localhost:8000/docs and run the score/capacity APIs with the default district_officer demo role.

Methodology

Static risk is normalised to 0–100:

40% hazard probability/intensity
25% exposed population/buildings
20% social vulnerability
15% infrastructure/access weakness

Default display classes are Low 0–24, Moderate 25–49, High 50–74, Very High 75–100. District and hazard thresholds are designed to be configurable. Official classifications always take precedence.

Immediate review priority uses 25% active warning, 25% observed danger, 20% household vulnerability, 15% building weakness and 15% isolation. Each response includes its factor contributions and verification requirement.

Candidate-site capacity is:

Effective Receiving Capacity = minimum(housing, water, sanitation, health, school, road access)
Available Capacity = Effective Capacity − Current Population − Allocated Relocatees

If land availability is not legally verified, available capacity is zero regardless of infrastructure estimates.

Data adapters

The adapter contract stores source organisation/URL, dataset version, collection/import dates, geographic resolution, update frequency, licence/restrictions, confidence and last verification date. ImdWarningMockAdapter demonstrates the live-alert schema without scraping or credentials.

Production adapters should use authorised APIs, downloads, WMS/WFS or documented manual imports for LGD, Census, Survey of India, Bhuvan, GSI, IMD, NDEM/CWC, INCOIS, NCS, FSI, PMGSY, UDISE+, IDRN, CGWB and authorised state/revenue sources. Credentials are intentionally absent. Never scrape protected websites.

Security and ethics

• Demo roles: public aggregate, field surveyor, district officer, data manager and administrator.
• Replace the demo header with signed SSO/OIDC tokens before production.
• Keep household records encrypted at rest and in transit; apply row-level permissions and retention rules.
• Store opaque household references, not Aadhaar.
• Record consent and keep photographs in protected object storage rather than the database.
• Audit reads and writes of restricted records.
• Validate land ownership/legal availability with the Revenue Department before displaying availability.
• Treat route results as provisional until field verified.

Limitations

• Included boundaries, hazards, alerts, population, routes and sites are synthetic, not operational intelligence.
• The browser map is a framework-native interactive demonstration, not a replacement for authoritative MapLibre/PostGIS layers. The data model and import surface are ready for that integration.
• Live feeds require registrations, credentials and source-specific authorisation.
• Census 2011 must be supplemented with verified current aggregates from authorised local sources.
• Offline drafts use device storage in the MVP; production should use encrypted IndexedDB plus a conflict-aware sync queue.

Tests

cd backend
python -m unittest discover -s tests -v

The test suite verifies score weights and class boundaries, limiting-constraint capacity, zero capacity for legally unverified sites, and non-negative available capacity.

See API reference and data dictionary.