🌊 Subterra

India's First Real-Time Groundwater Intelligence Platform

Empowering farmers, policymakers, and researchers with AI-powered water predictions and actionable insights.

---

What is Subterra?

Subterra is a mobile-first, AI-powered groundwater management platform designed for India. It connects to 5,260+ DWLR (Digital Water Level Recorder) stations across the country and uses machine learning to predict water levels up to 30 days ahead.

Key Features

Feature	Description
30-Day Predictions	ML-powered water level forecasting using Temporal Fusion Transformer
Real-Time Monitoring	Live data from India-WRIS DWLR network
Crop Planner	AI-optimized irrigation schedules based on predicted water availability
Water Budget Tool	Calculate sustainable usage limits with ML predictions
Community View	See nearby wells and collective water usage trends
Multilingual	Support for 10+ Indian languages
Offline Mode	Works without internet, syncs when connected
SMS Alerts	Low-connectivity users get critical updates via SMS

---

Architecture

┌─────────────────────────────────────────────────────────────────────┐
│                          CLIENT LAYER                               │
├─────────────────────┬─────────────────────┬─────────────────────────┤
│   Flutter App       │    React PWA        │    Research Portal      │
│   (Android/iOS)     │    (Web Frontend)   │    (Researchers)        │
└─────────┬───────────┴─────────┬───────────┴─────────┬───────────────┘
          │                     │                     │
          └──────────────┬──────┴──────────┬──────────┘
                         │   GraphQL API   │
                         ▼                 ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         BACKEND (Node.js)                           │
├─────────────────────────────────────────────────────────────────────┤
│  Controllers  │  Services  │  GraphQL Resolvers  │  Middleware      │
└───────┬───────┴─────┬──────┴──────────┬─────────┴────────┬──────────┘
        │             │                  │                  │
        ▼             ▼                  ▼                  ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐
│  Firestore  │ │    Redis    │ │  India-WRIS │ │    ML Service       │
│  (Storage)  │ │   (Cache)   │ │    API      │ │  (TFT Inference)    │
└─────────────┘ └─────────────┘ └─────────────┘ └──────────┬──────────┘
                                                          │
                                               ┌──────────▼──────────┐
                                               │   Gemini API        │
                                               │   (AI Insights)     │
                                               └─────────────────────┘

---

The ML Model: Temporal Fusion Transformer (TFT)

We chose TFT because groundwater prediction isn't just about looking at past water levels. It's about understanding complex relationships between:

• Historical water levels
• Rainfall patterns
• Temperature and humidity
• Seasonal cycles
• Geographic location

TFT handles all of this beautifully. See docs/ML_MODEL.md for full details.

Quick Summary

Aspect	Details
Lookback Window	90 days of history
Forecast Horizon	30 days ahead
Output	Quantile predictions (10th, 50th, 90th percentile)
Features	Water level, rainfall, temperature, location, well depth
Model Size	~2MB

---

Project Structure

subterra/
├── backend/                 # Node.js + Express + GraphQL API
│   ├── src/
│   │   ├── config/          # Firebase, Redis configuration
│   │   ├── controllers/     # Business logic controllers
│   │   ├── services/        # External API integrations
│   │   ├── graphql/         # Schema and resolvers
│   │   └── middleware/      # Auth, logging, error handling
│   └── ml/                  # Python ML components
│       ├── train_tft.py     # TFT training script
│       ├── inference/       # FastAPI inference service
│       ├── checkpoints/     # Trained model weights
│       └── data/            # Training dataset
│
├── frontend/                # React PWA (Web interface)
│   └── src/
│       ├── pages/           # Page components
│       ├── components/      # Reusable UI components
│       └── lib/             # GraphQL queries, utilities
│
├── lib/                     # Flutter app (Mobile)
│   ├── core/                # App core (theme, routes)
│   ├── data/                # Data layer (APIs, models)
│   └── features/            # Feature modules
│
└── docs/                    # Documentation
    ├── ML_MODEL.md          # TFT model documentation
    ├── DATA_PIPELINE.md     # How we collect and process data
    ├── API_REFERENCE.md     # GraphQL API documentation
    └── ARCHITECTURE.md      # System architecture

---

Quick Start

Prerequisites

• Node.js 18+
• Python 3.10+
• Docker (optional)
• Firebase project (for Firestore)
• Redis (for caching)

1. Clone and Setup

git clone https://github.com/your-repo/subterra.git
cd subterra

2. Backend Setup

cd backend
npm install
cp .env.example .env
# Edit .env with your API keys
npm run dev

3. ML Service Setup

cd backend/ml
pip install -r requirements_train.txt
python inference/service.py
# Runs on http://localhost:8000

4. Frontend Setup

cd frontend
npm install
npm run dev
# Runs on http://localhost:5173

Docker (Alternative)

docker-compose up --build

---

Environment Variables

# API Keys
GEMINI_API_KEY=your_gemini_api_key
MSG91_AUTH_KEY=your_msg91_key
MSG91_SENDER_ID=SBTRRA

# Firebase
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_CLIENT_EMAIL=your_client_email
FIREBASE_PRIVATE_KEY=your_private_key

# Redis
REDIS_URL=redis://localhost:6379

# ML Service
ML_SERVICE_URL=http://localhost:8000

---

Data Sources

Source	Data Type	Update Frequency
India-WRIS	DWLR water levels	Every 6 hours
NASA POWER	Rainfall, temperature	Daily
Firestore	User data, alerts	Real-time

---

Screenshots

Home	Map	Crop Planner	Water Budget

---

Documentation

• ML Model Details - How TFT works and why we chose it
• Data Pipeline - How we collect and process data
• API Reference - GraphQL queries and mutations
• Architecture - System design with diagrams

---

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

---

Acknowledgments

• India-WRIS for providing open access to DWLR data
• NASA POWER for weather data
• All the farmers and communities who inspired this project