🌍 EnvisionGrid — City-Scale Environmental Risk Intelligence Platform

Predict, Alert, and Simulate environmental risks across urban zones using data-driven intelligence

---

📌 Overview

EnvisionGrid is a full-stack environmental monitoring platform that ingests violation reports, complaints, and optional IoT sensor data to generate real-time risk predictions for city grid zones. It features explainable risk scoring, automated alert generation, case management, hotspot detection, and policy simulation — all accessible through a REST API and an interactive Streamlit dashboard.

Design Philosophy: Sensor-Agnostic, Sensor-Enhanced. Core intelligence derives from violations + complaints data; IoT sensors boost prediction confidence but are never required.

---

🏗️ System Architecture

graph TD
    subgraph Data Ingestion
        A1[CSV/JSON Upload] --> ING[Ingestion Engine]
        A2[Arduino Edge Node] -.->|Optional| ING
    end

    subgraph Processing Pipeline
        ING --> DB[(SQLite Storage)]
        ING --> FE[Feature Engineering<br/>Rolling Windows]
        FE --> MODEL[Risk Model<br/>Deterministic Rules + Sigmoid]
    end

    subgraph Output Layer
        MODEL --> ALERTS[Alert Generation]
        MODEL --> EXPLAIN[Explainability Engine]
        ALERTS --> CASES[Case Management]
        MODEL --> HOT[Hotspot Detection]
        MODEL --> COV[Coverage Analysis]
    end

    subgraph Simulation
        SIM[Policy What-If Engine]
    end

    subgraph Interfaces
        API[FastAPI REST API]
        DASH[Streamlit Dashboard<br/>6 Interactive Tabs]
    end

    ALERTS --> API
    EXPLAIN --> API
    CASES --> API
    HOT --> API
    COV --> API
    SIM --> API
    API --> DASH

Loading

---

✨ Key Features

Feature	Description
📊 Risk Prediction	Multi-type environmental risk scoring per grid zone
🚨 Smart Alerts	Auto-generated alerts when risk thresholds are breached
📋 Case Management	Create and track investigation cases from alerts
🗺️ Hotspot Detection	Identify the highest-risk zones across the city
🔬 Explainability	Human-readable explanations of risk drivers
🧪 Policy Simulation	What-if analysis for intervention planning
📡 IoT Integration	Optional Arduino edge nodes for sensor data
📈 Coverage Analysis	Identify data gaps across the monitoring grid

---

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/coolss21/envision_grid.git
cd envision_grid

# 2. Install dependencies
pip install -r requirements.txt

# 3. Generate demo data
python sample_data/generate_demo_data.py

# 4. Start backend (Terminal 1)
uvicorn src.api:app --reload

# 5. Start dashboard (Terminal 2)
streamlit run frontend/app.py

# 6. (Optional) Run full automated demo
python scripts/demo_end_to_end.py

---

📂 Project Structure

envision_grid/
├── src/
│   ├── api.py              # FastAPI endpoints (16 routes)
│   ├── config.py           # Tunable parameters & thresholds
│   ├── db.py               # SQLite schema + helpers
│   ├── schemas.py          # Pydantic request/response models
│   ├── geo_grid.py         # Lat/lon → grid cell mapping
│   ├── ingest.py           # CSV/JSON data ingestion
│   ├── features.py         # Rolling-window feature engineering
│   ├── model_adapter.py    # Risk model with clean ML interface
│   ├── explain.py          # Human-readable risk explanations
│   ├── actions.py          # Recommended intervention actions
│   ├── alerts.py           # Alert generation & management
│   ├── cases.py            # Investigation case tracking
│   ├── hotspots.py         # Top risk zone detection
│   ├── coverage.py         # Data coverage gap analysis
│   └── simulate.py         # Policy what-if simulation
├── frontend/
│   ├── app.py              # Streamlit dashboard (6 tabs)
│   └── ui_components.py    # Reusable UI widgets
├── edge_node/
│   ├── serial_to_api_bridge.py   # Arduino → API bridge
│   ├── arduino_stub.ino          # Reference firmware
│   ├── sensor_payload_example.json
│   ├── wiring_diagram.md
│   └── README_EDGE_NODE.md
├── sample_data/
│   ├── generate_demo_data.py     # Synthetic data generator
│   └── scenario_timeline.json    # Early-signal demo scenario
├── scripts/
│   ├── demo_end_to_end.py        # Full automated demo
│   ├── reset_db.py               # Database reset utility
│   ├── run_backend.bat
│   └── run_frontend.bat
├── docs/
│   ├── ML_BLUEPRINT.md           # ML logic specification
│   └── API_SCHEMA.md             # Full API reference
├── .github/workflows/ci.yml     # Automated CI pipeline
├── requirements.txt
└── README.md

---

🔌 API Reference

Method	Endpoint	Description
GET	/health	Health check
GET	/grid/preview	Preview grid mapping for coordinates
POST	/ingest/violation-event	Ingest single violation event
POST	/ingest/violations	Batch upload violations CSV
POST	/ingest/complaints	Batch upload complaints CSV
POST	/ingest/sensor	Ingest single sensor reading
POST	/ingest/sensors	Batch upload sensor CSV
POST	/predict	Run risk prediction pipeline
GET	/predictions	Retrieve stored predictions
GET	/alerts	List generated alerts
POST	/cases	Create case from alert
GET	/cases	List investigation cases
PATCH	/cases/{id}	Update case status
GET	/hotspots	Get top risk zones
GET	/coverage	Data coverage report
POST	/simulate	Run policy what-if simulation

📋 Example curl Commands

# Health check
curl http://localhost:8000/health

# Ingest a violation event
curl -X POST http://localhost:8000/ingest/violation-event \
  -H "Content-Type: application/json" \
  -d '{"violation_id":"V001","timestamp":"2024-03-15T10:00:00","lat":40.72,"lon":-74.01,"violation_type":"industrial_emission","severity":4,"source":"Facility_13"}'

# Upload violations CSV
curl -X POST http://localhost:8000/ingest/violations -F "file=@sample_data/demo_violations.csv"

# Run prediction
curl -X POST http://localhost:8000/predict \
  -H "Content-Type: application/json" \
  -d '{"risk_type":"all","horizon_hours":72,"threshold":0.5,"use_sensors":true}'

# What-if simulation
curl -X POST http://localhost:8000/simulate \
  -H "Content-Type: application/json" \
  -d '{"risk_type":"all","horizon_hours":72,"adjustments":[{"grid_id":"40.71_-74.01","violation_type":"industrial_emission","factor":0.3}]}'

# Get hotspots & coverage
curl http://localhost:8000/hotspots
curl http://localhost:8000/coverage

---

🧩 Design Decisions

Decision	Choice	Rationale
Primary Signal	Violations + Complaints	Available immediately; no hardware required
Sensor Role	Confidence Booster	Validates predictions; doesn't replace core data
Model	Deterministic Placeholder	Stable & reproducible; clean interface for future ML
Storage	SQLite	Zero setup; single-file database
Geo-Binning	2-decimal lat/lon	~1.1km grid cells; city-scale granularity

---

📡 IoT Edge Node (Optional)

The edge_node/ directory contains everything needed to connect an Arduino-based sensor station:

• arduino_stub.ino — Reference firmware for temperature, humidity, and air quality sensors
• serial_to_api_bridge.py — Python bridge that reads serial data and POSTs to the API
• wiring_diagram.md — Hardware wiring reference

See edge_node/README_EDGE_NODE.md for full setup instructions.

---

📄 License

MIT — Built for the InnovateYou Hackathon.

Making cities smarter, one grid cell at a time.