Skip to content

Latest commit

 

History

History
186 lines (134 loc) · 7.07 KB

README.md

File metadata and controls

186 lines (134 loc) · 7.07 KB

🌱 Darukaa.Earth — Carbon & Biodiversity Geospatial Analytics Platform

Darukaa.Earth is a full-stack, enterprise-grade geospatial analytics dashboard for managing and visualizing carbon sequestration and biodiversity restoration projects.


🌟 Key Features

  • 🔐 JWT Authentication: Role-based registration and secure login system for administrators.
  • 📁 Project Management: Create, view, and monitor carbon offset projects with real-time portfolio metrics.
  • 🗺️ Geospatial Polygon Drawing: Interactive MapLibre GL JS / Mapbox GL JS map allowing administrators to draw geographical site boundaries directly on the map.
  • 📐 Geodesic Area Calculation: Dynamic hectare calculation for drawn multi-point polygon boundaries using Shapely + WGS84 latitude-scaling.
  • 📊 Time-Series Analytics: Interactive Chart.js charts tracking historical CO₂ sequestration, NDVI vegetation health, canopy coverage, and species richness over 24 months.
  • 🛡️ Automated Code Quality & Pre-commit Hooks: Prettier, ESLint, Black, Flake8 via Husky and lint-staged.
  • ⚙️ CI/CD Pipeline: GitHub Actions workflow and Render deployment blueprint.

🛠️ Tech Stack

Frontend

Layer Technology
Framework React 18, Vite
Mapping MapLibre GL JS, @mapbox/mapbox-gl-draw
Charting Chart.js 4, react-chartjs-2
Icons Lucide React
Styling Custom Glassmorphism CSS Design System

Backend

Layer Technology
Framework Python 3.11+, FastAPI, Uvicorn
Database PostgreSQL (Neon Cloud / PostGIS)
ORM SQLAlchemy 2.0, Shapely 2.0, Psycopg2
Security PyJWT, Passlib (bcrypt)

Code Quality & CI/CD

Tool Purpose
Husky + lint-staged Pre-commit automation
ESLint + Prettier JS/JSX formatting & linting
Black + Flake8 Python formatting & linting
Pytest Backend unit tests
GitHub Actions CI pipeline
Render.com Deployment target

🗄️ Geospatial Data — PostgreSQL & PostGIS Extension

The application uses PostgreSQL exclusively (with Neon Serverless PostgreSQL / PostGIS). Tables are managed in a dedicated darukaa_earth schema namespace. boundary_geojson is stored as a TEXT column containing serialized GeoJSON, and Shapely performs precise geodesic ellipsoidal area calculations.

In production (PostgreSQL), the recommended migration path is:

-- Enable PostGIS extension on the target database
CREATE EXTENSION IF NOT EXISTS postgis;

-- Upgrade the boundary column to a proper geometry type
ALTER TABLE sites
  ADD COLUMN boundary_geom GEOMETRY(Polygon, 4326);

-- Migrate existing JSON data
UPDATE sites
  SET boundary_geom = ST_GeomFromGeoJSON(boundary_geojson);

-- Geodesic area calculation using PostGIS (replaces Shapely)
SELECT
  id, name,
  ST_Area(boundary_geom::geography) / 10000.0 AS area_hectares
FROM sites;

Using GEOMETRY(Polygon, 4326) with SRID 4326 (WGS84) ensures:

  • Correct geodesic distance and area calculations
  • Interoperability with QGIS, ArcGIS, Mapbox, and MapLibre
  • Support for spatial index queries (ST_Intersects, ST_Within, ST_DWithin)

📊 Mock Data — Dataset Rationale

Why the Western Ghats, Kerala?

The seed data uses real geographic coordinates from two UNESCO World Heritage biodiversity hotspots in Kerala, India:

Site Coordinates Ecosystem Rationale
Anamalai Reserve Sector Alpha 76.85°E, 10.32°N – 76.89°E, 10.36°N Tropical Rainforest Part of the Anamalai Tiger Reserve; one of South Asia's most carbon-dense forests (~8.5 tCO₂/ha/yr)
Silent Valley Biodiversity Corridor 76.42°E, 11.08°N – 76.46°E, 11.12°N Tropical Rainforest Silent Valley National Park; globally significant biodiversity corridor (800+ plant species, 34 mammal species)

Why these sites?

  1. Scientific accuracy — The IPCC Sixth Assessment Report cites tropical moist forests in South/SE Asia as having the highest per-hectare carbon sequestration rates globally (6–12 tCO₂/ha/yr). Using real coordinates from these zones makes the synthetic analytics scientifically defensible.
  2. Data richness — NDVI data from NASA MODIS and Landsat-8 shows NDVI values of 0.65–0.90 for these zones, matching our seeded baseline of 0.65 + growth trend.
  3. Polygon plausibility — The bounding boxes (~4.4 km × 4.4 km ≈ ~1,940 ha each) are realistic for forest conservation project units and produce meaningful CO₂ tonnage numbers (>15,000 tCO₂e over 24 months).
  4. Geospatial compatibility — Kerala's coordinate range (8°N–13°N, 74°E–78°E) renders well on ESRI World Imagery and Dark Canvas basemaps with no tile authentication required.

Synthetic Analytics Generation

The 24-month time-series in geospatial.py uses these scientifically-grounded parameters:

Ecosystem CO₂ Rate (tCO₂/ha/yr) Base NDVI Base Species Richness
Tropical Rainforest 8.5 0.65 45
Mangrove & Wetland 11.2 0.58 35
Temperate Forest 6.2 0.52 28
Agroforestry 5.0 0.48 20

A 3.5% monthly compound growth factor and sinusoidal seasonal fluctuation (±8%) model realistic tropical forest recovery trajectories consistent with published afforestation monitoring data (Verra VCS Standard, Gold Standard MRV guidelines).


🚀 Quick Start Guide

1. Backend Setup

cd backend
python -m venv venv
# On Windows:
.\venv\Scripts\activate
# On macOS/Linux:
source venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

2. Frontend Setup

cd frontend
npm install
npm run dev

3. Pre-commit Hooks Setup

# From the repository root
npx husky install

🧪 Running Automated Tests

# Backend pytest suite
cd backend && python -m pytest tests/ -v

# Frontend linting
cd frontend && npm run lint

# Frontend formatting check
cd frontend && npm run format

🗺️ Map Interaction Guide

Action Result
Click project in sidebar Map flies to that project's polygon bounds; other project sites are dimmed
Click a site polygon on map Site details popup appears; analytics drawer auto-opens with time-series charts
Click site in project drawer Map zooms to exact polygon bounds
Draw polygon (admin only) Enter drawing mode; click 3+ points; click "Complete & Save"; polygon saved and rendered
Toggle map style Switch between dark canvas and satellite imagery basemaps

🏗️ CI/CD Pipeline

The GitHub Actions workflow (.github/workflows/ci.yml) runs on every push to main:

  1. Backend: Install deps → Run flake8 → Run pytest
  2. Frontend: Install deps → Run eslint → Build production bundle

On success, Render.com automatically deploys both the FastAPI backend and the Vite React frontend via the render.yaml blueprint.