Production-grade, containerized pipeline for geospatial land-risk analysis.
The system combines:
- Go backend API for orchestration, validation, and reporting
- Python ML microservice (XGBoost + satellite feature extraction)
- React frontend dashboard with map-driven input and diagnostics
- PostgreSQL for report/trace persistence
- Redis for caching and latency optimization
Land-risk assessment often requires combining heterogeneous signals: geospatial context, satellite observations, engineered features, and deterministic policy rules. This repository implements an end-to-end system that turns those inputs into:
- A risk class and confidence score
- A technical explanation trail
- A citizen-friendly summary
- Downloadable JSON/PDF reports and trace artifacts
flowchart LR
U[User] --> F[React Frontend]
F --> B[Go Backend API]
B --> K[KGIS / Geospatial APIs]
B --> M[Python ML Service]
B --> R[(Redis Cache)]
B --> P[(PostgreSQL)]
B --> O[OpenRouter Summary API Optional]
M --> S[Satellite Data Sources]
- Multi-input analysis request handling:
- latitude + longitude
- or villageId + surveyNumber
- Resilient KGIS ingestion with retry/timeout handling
- Feature engineering for model inference
- Satellite feature extraction (
ndvi,vegetation_density,water_overlap_ratio) - Rule-based validation and confidence adjustment
- Deterministic high-risk override for high water overlap conditions
- Full trace and latency metrics persistence
- PDF report generation
- Optional plain-language summary generation via OpenRouter
.
├── backend-go/ # Go API service, orchestration, persistence, reporting
├── ml-service-python/ # FastAPI ML inference + satellite feature service
├── frontend-react/ # React + Leaflet client app
├── postgres/ # PostgreSQL init scripts
├── redis/ # Redis configuration
├── tests/integration/ # End-to-end smoke test script
├── docs/ # Evaluation notes and final report artifacts
├── docker-compose.yml # Multi-service stack definition
└── Makefile # Developer and CI-friendly commands
- Docker Engine with Docker Compose plugin
- GNU Make
Optional for local, non-containerized development:
- Go 1.22+
- Python 3.11+
- Node.js 20+
- Create runtime environment file.
cp .env.local .env-
Optionally update credentials and API settings in
.env. -
Build and start the full stack.
make upThis command:
-
Builds/starts all services.
-
Runs database migrations.
-
Seeds sample data.
-
Verify health.
curl -fsS http://127.0.0.1:18080/healthDefaults come from .env.local.
| Service | URL |
|---|---|
| Frontend | http://127.0.0.1:13000 |
| Backend API | http://127.0.0.1:18080 |
| ML Service | http://127.0.0.1:18000 |
| PostgreSQL | 127.0.0.1:15432 |
| Redis | 127.0.0.1:6379 |
make build
make up
make down
make restart
make logs
make clean
make migrate
make seed
make test
make integration-testBase URL: http://127.0.0.1:18080
Request examples:
{
"latitude": 12.9716,
"longitude": 77.5946,
"surveyType": "parcel"
}{
"villageId": "V123",
"surveyNumber": "S456",
"surveyType": "parcel"
}Response shape:
{
"report": {
"id": "<report-id>",
"riskClass": "Low|Medium|High",
"confidence": 0.0,
"citizenSummary": {
"overview": "...",
"keyPoints": [],
"nextSteps": [],
"disclaimer": "...",
"source": "model|fallback"
}
},
"cacheHit": false
}Returns persisted report metadata and full payload.
Returns PDF report bytes as file download.
Returns trace payload and stored metrics for auditing.
Health endpoint for backend service.
Base URL: http://127.0.0.1:18000
Input:
{
"features": [0.1, 0.2, 0.3, 0.4, 0.1, 1.0, 3.0, 0.7, 1520.0, 0.0]
}Input supports either coordinates or geometry.
{
"latitude": 12.9716,
"longitude": 77.5946
}Health endpoint for ML service.
- Request validation and deduplication.
- Concurrent/optimized KGIS pulls.
- Preprocessing and feature engineering.
- Satellite feature extraction.
- ML inference.
- Rule-based validation and confidence/risk adjustment.
- Report generation + optional citizen summary.
- Persistence of report, trace, and latency metrics.
- Cache write for repeated-input acceleration.
Main runtime config is in .env (copy from .env.local).
Important variables:
| Variable | Purpose | Default |
|---|---|---|
BACKEND_PORT |
Backend published port | 18080 |
ML_SERVICE_PORT |
ML service published port | 18000 |
FRONTEND_PORT |
Frontend published port | 13000 |
DATABASE_URL |
Backend PostgreSQL DSN | postgres://landrisk:landrisk@postgres:5432/landrisk?sslmode=disable |
REDIS_URL |
Backend Redis URL | redis://redis:6379/0 |
ML_SERVICE_URL |
Backend to ML service URL | http://ml-service:8000 |
KGIS_BASE_URL |
Upstream geospatial endpoint base | https://kgis.ksrsac.in:9000 |
REQUEST_TIMEOUT_SECONDS |
End-to-end backend timeout | 25 |
ML_TIMEOUT_SECONDS |
ML call timeout | 10 |
KGIS_TIMEOUT_SECONDS |
KGIS call timeout | 8 |
OPENROUTER_API_KEY |
Optional LLM key for citizen summaries | empty |
OPENROUTER_MODEL |
OpenRouter model name | openai/gpt-oss-120b:free |
Run all core tests:
make testRun integration smoke test against running stack:
make integration-testCurrent coverage focus:
- Backend unit tests: handlers, preprocessing, validation, analyzer timeout behavior
- ML unit tests: NDVI and inference behavior
- Integration test: full request-to-report pipeline smoke validation
Ensure .env exists:
cp .env.local .envCheck logs:
make logsReset stack and volumes when required:
make clean && make upIf OPENROUTER_API_KEY is empty/invalid, the backend falls back to deterministic text for citizenSummary.
Use host 127.0.0.1 consistently (the integration script defaults to this).
- Do not commit
.env. - Keep API keys in local environment only.
- Rotate keys immediately if exposed.
- Restrict CORS origin via
FRONTEND_ORIGINfor non-local deployments.
Detailed docs are in docs/README.md.
Quick links:
- docs/evaluation/01-data-pulling-and-preprocessing.md
- docs/evaluation/02-technique-logic-data-handling-response-time.md
- docs/evaluation/03-accuracy-and-result-validation.md
- docs/evaluation/04-report-quality.md
- docs/evaluation/05-frontend-design-and-experience.md
- docs/report/Report.tex
- docs/report/Report.pdf
Project demo recording: