TerraPulse AI is an agricultural intelligence and regenerative farming platform designed to empower farmers, agronomists, land managers, and carbon credit evaluators. By combining satellite land diagnostics, AI-driven plant and soil health analysis, and multi-year carbon sequestration forecasting, TerraPulse AI turns complex environmental data into actionable insights for sustainable land stewardship.
- Project Overview
- Key Features
- System Architecture
- Technology Stack
- Project Structure
- Getting Started
- Environment Variables
- Development Status
- Future Enhancements
- Contributing
- License
Global agricultural land faces severe degradation, loss of Soil Organic Carbon (SOC), unpredictable climate risks, and escalating crop disease outbreaks. At the same time, transitioning to regenerative practices (cover cropping, no-till, crop rotation) is often inhibited by a lack of accessible satellite monitoring tools and complex, unverified carbon credit estimation models.
TerraPulse AI provides an intuitive, high-performance platform that unifies real-time farm health diagnostics and predictive carbon modeling:
- Satellite Health Tracking: Monitor vegetation vigor (NDVI) and soil moisture levels across registered fields.
- AI Diagnostics: Scan plant leaves and soil samples for instant disease detection, severity ratings, and treatment guidance.
- Carbon Simulator: Simulate 3-year crop rotation scenarios to project SOC gains, crop resilience, and estimated voluntary carbon credits over a 5-year timeline.
-
Core Agronomic Metrics: Real-time visibility into average Soil Organic Carbon (SOC %), NDVI index, soil moisture percentage, and estimated annual carbon credits (
$tCO_2e/yr$ ). - Interactive Field Selector: Switch between registered farm parcels (e.g., North Valley Field, East Meadow) to inspect localized telemetry.
- Trend Charts: Visual tracking of historical NDVI and moisture trends powered by interactive Recharts line graphs.
- Disease & Advisory Feed: Instant alerts on recent field scans and prioritized regenerative recommendations.
- Dual-Layer Map Visualization: Toggle between Normalized Difference Vegetation Index (NDVI) and Soil Moisture Heatmap visual overlays.
- Multi-Satellite Source Selector: Inspect data resolution across Sentinel-2 (10m), PlanetScope (3m), and Landsat-9 (30m) providers.
- Agronomic Action Plans: Field-specific recommendations including cover crop selection (e.g., Crimson Clover, Hairy Vetch) and bio-fertilizers (e.g., Mycorrhizal Inoculants).
- Dual-Mode Diagnostics: Dedicated upload & analysis workflows for Plant Leaf Health and Soil Degradation.
- Interactive Scan Workflow: Step-by-step image upload, simulated neural network analysis, and diagnostic report generation.
- Comprehensive Diagnostic Reports:
- Disease/Condition identification with confidence score.
- Severity level assessment (e.g., Moderate, Severe).
- Symptom breakdown and root cause analysis.
- Localized treatment and prevention protocols.
- Soil organic matter estimation and nutrient deficiency breakdown.
-
Interactive Crop Rotation Builder: Configure 3-year crop sequences (e.g., Corn
$\rightarrow$ Soybeans$\rightarrow$ Crimson Clover) across custom acreage. - Soil Baseline Selector: Choose baseline soil types (e.g., Silt Loam, Clay Loam, Sandy Loam) and enter historical yield baselines.
-
Predictive Engine:
- Soil Organic Carbon (SOC %) trajectory over 5 years.
- Climate Resilience Score improvements.
-
Carbon Sequestration Rate (
$tCO_2e/\text{acre}/\text{year}$ ). -
Annual Carbon Credit Forecast (
$tCO_2e$ ) for voluntary carbon markets.
- Unified Global Locale: Immediate, client-side, page-reload-free language switching across the entire dashboard application.
- Regional Languages: Fully supports 5 major agricultural languages of India:
- English (
en-IN) - Hindi (
hi-IN) - Bengali (
bn-IN) - Marathi (
mr-IN) - Kannada (
kn-IN)
- English (
- Backend LLM Localization: Passes the selected language context to the backend Gemini AI generation prompts. Translates AI strategic analyses, RAG outputs, scanner descriptions, and copilot responses on-the-fly while strictly keeping JSON schemas in English to maintain visual compatibility.
- T-Hook Enhancements: Built-in default string parameter fallbacks on hook queries to guarantee zero unlocalized UI glitches.
┌────────────────────────────────────────────────────────┐
│ TerraPulse AI Web Client │
│ (React + Vite + Recharts + Lucide Icons) │
└───────────────┬───────────────────────────▲────────────┘
│ │
HTTP Requests WebSocket/Stream
│ │
▼ │
┌───────────────────────────────────────────┴────────────┐
│ FastAPI Application Server │
│ (Uvicorn + Pydantic Settings + Custom CORS) │
└───────────────┬────────────────────────────────────────┘
│
┌───────┼───────────────┬──────────────┐
▼ ▼ ▼ ▼
┌───────────┐┌─────────────┐┌──────────────┐┌───────────┐
│ Gemini ││ OpenRouter ││ Earth Engine ││ Firestore │
│ Service ││ API Service ││ Satellite ││ Database │
│ (Advisory)││ (Scanner) ││ Telemetry ││ Storage │
└───────────┘└─────────────┘└──────────────┘└───────────┘
Note on Architecture: The application operates in dual-mode (Toggleable between DEMO and LIVE mode from the Topbar).
- DEMO Mode: Front-end queries intercept requests to return high-fidelity local datasets instantly.
- LIVE Mode: Requests route to the production FastAPI backend. The backend uses OpenRouter (Gemma 4 free-tier multimodal model) for image scans and the official Google Gemini SDK for advisory diagnostics, falling back to mock schemas gracefully on API failures.
- Framework: React 18 (SPA Architecture)
- Build Tool: Vite 5
- Routing: React Router DOM v7
- Data Visualization: Recharts 3
- Iconography: Lucide React
- Styling: Vanilla CSS design tokens with organic green accents, pill selectors, custom interactive badges, and clean layouts.
- Framework: FastAPI (Python 3.10+)
- WSGI/ASGI Server: Uvicorn
- AI Integrations: Official
google-generativeaiSDK (Gemini) & OpenRouter API (google/gemma-4-26b-a4b-it:freemultimodal model). - Environment Management:
Pydantic-Settingsfor secure, type-safe config loading. - Database / Cache Adapters: Firestore & Local fallback engines.
- Testing: Complete
pytestsuite covering carbon calculations, telemetry aggregation, and risk analysis.
TerraPulse-AI/
├── Backend/ # Python Backend API & ML Engine
│ ├── main.py # ASGI Uvicorn server entrypoint
│ ├── requirements.txt # Python package dependencies
│ ├── Dockerfile # Containerization definition
│ ├── app/ # FastAPI application codebase
│ │ ├── main.py # FastAPI App instance and middlewares config
│ │ ├── config.py # Configuration schema and Pydantic settings loading
│ │ ├── routers/ # Endpoint handlers (scanner, advisory, simulator, copilot, satellite, voice)
│ │ ├── services/ # Business logic layer (Gemini, Speech synthesis, Carbon simulation, Risk engine)
│ │ ├── schemas/ # Request and response Pydantic models
│ │ └── utils/ # Helper utilities and audit loggers
│ └── tests/ # Pytest unit testing suite
│
├── Frontend/ # Vite + React Frontend Application
│ ├── public/ # Static public assets (favicons, icons)
│ ├── src/
│ │ ├── assets/ # Visual assets and logo images
│ │ ├── components/ # Reusable UI primitives, FarmMap, Layout sidebar/topbar
│ │ ├── data/ # Mock datasets and static parameter definitions
│ │ ├── hooks/ # Custom React state hooks (useAsync, useAuth, useTranslation)
│ │ ├── locales/ # JSON translation dictionaries (en-IN, hi-IN, bn-IN, mr-IN, kn-IN)
│ │ ├── pages/ # Primary views (Landing, Dashboard, FarmHealth, AIScanner, CarbonSimulator, AICopilot, ActionCenter, IndiaIntelligence)
│ │ ├── services/ # Decoupled service layer for safeFetch API endpoints
│ │ ├── styles/ # Modular CSS design system tokens and application layouts
│ │ └── main.jsx # Application entrypoint & React Router provider
│ ├── eslint.config.js # ESLint code hygiene rules
│ ├── index.html # HTML DOM container
│ ├── package.json # Node.js dependencies & scripts
│ └── vite.config.js # Vite build & plugin settings
│
├── .gitignore # Git untracked path rules
└── README.md # Project documentation
- Node.js: v18.0.0 or higher
- npm: v9.0.0 or higher
-
Navigate to the Frontend directory:
cd Frontend -
Install Node dependencies:
npm install
-
Start the local development server:
npm run dev
The application will be accessible at
http://localhost:5173. -
Build for production:
npm run build
The optimized production bundle will be generated in
Frontend/dist/. -
Preview the production build locally:
npm run preview
-
Navigate to the Backend directory:
cd Backend -
Create and activate a Python virtual environment:
- Windows:
python -m venv venv .\venv\Scripts\activate
- macOS / Linux:
python3 -m venv venv source venv/bin/activate
- Windows:
-
Install Python packages:
pip install -r requirements.txt
The frontend service layer supports environment configuration. Create a .env file in the Frontend/ directory based on .env.example:
# Frontend Environment Configuration (.env.example)
# Base URL for Backend REST API
VITE_API_BASE_URL=http://localhost:8000/api
# Enable mock data fallback when backend service is offline
VITE_ENABLE_MOCK_SERVICES=trueSecurity Note: Never commit
.envor files containing secret API keys, tokens, or credentials to version control.
| Component | Status | Details |
|---|---|---|
| UI/UX & Design System | ✅ Completed | Full responsive graphic design system with bold 2.5px black outlines & fresh organic green accents |
| Landing Page | ✅ Completed | Feature showcase, problem statement, CTA navigation |
| Executive Dashboard | ✅ Completed | Interactive metric summaries, Recharts graphs, field switcher |
| Farm Health Satellite View | ✅ Completed | Dual-layer NDVI / Soil Moisture map toggle & satellite provider selector |
| AI Disease & Soil Scanner | ✅ Completed | Interactive upload & diagnostic workflow powered by OpenRouter free-tier multimodal model (google/gemma-4-26b-a4b-it:free) |
| Carbon Simulator | ✅ Completed | 3-year crop rotation builder with 5-year SOC & carbon credit math engine |
| Service Layer Abstraction | ✅ Completed | Asynchronous service contracts (api.js) fully integrated with the FastAPI backend |
| Backend REST API | ✅ Completed | High-performance FastAPI server with 11 router endpoints, integrated config loaders, and schema validation |
| Live Satellite Proxy | ✅ Completed | Earth Engine Service telemetry computation and simulation for all registered farm fields |
| AI Advisory & Copilot | ✅ Completed | Gemini-powered local and regional agricultural advice & contextual chat system |
| Global Multilingual System | ✅ Completed | Unified localization supporting English, Hindi, Bengali, Marathi, and Kannada across all pages and AI prompts |
- Live Satellite Data Pipeline: Integration with Copernicus Sentinel-2 API for automated 5-day NDVI updates.
- IoT Telemetry Ingestion: Support for MQTT soil moisture & temperature sensor streams.
- PDF Certification Export: Exportable carbon sequestration verification reports for voluntary market auditors.
Contributions, issues, and feature requests are welcome!
- Fork the Repository.
- Create a Feature Branch:
git checkout -b feature/amazing-feature
- Commit your changes:
git commit -m "feat: add amazing feature" - Push to the Branch:
git push origin feature/amazing-feature
- Open a Pull Request.
This project is developed for hackathon demonstration and evaluation. Check the repository repository settings for specific license terms.