337 lines
7.0 KiB
Markdown
337 lines
7.0 KiB
Markdown
# Software Requirements Specification (SRS) & Development Context
|
||
|
||
Project: **GeoCrop Platform**
|
||
Format: Modified IEEE Std 830-1998 (Optimized for AI Agent / Roo Code Initialization)
|
||
Date: February 2026
|
||
|
||
---
|
||
|
||
# 1. Introduction
|
||
|
||
## 1.1 Purpose
|
||
|
||
This document defines the Software Requirements Specification (SRS) for the GeoCrop Platform.
|
||
|
||
⚠️ This document also serves as the **master initialization and execution context for Roo Code (AI agent)**.
|
||
It explicitly states:
|
||
|
||
* What infrastructure already exists and must NOT be rebuilt
|
||
* What services are live and working
|
||
* What remains to be implemented
|
||
* Architectural constraints that must be respected
|
||
|
||
Roo must treat the infrastructure layer as stable and focus on application-layer implementation.
|
||
|
||
---
|
||
|
||
## 1.2 Scope
|
||
|
||
GeoCrop is a cloud-native web application designed to generate refined **Land Use and Land Cover (LULC)** maps for regions in Zimbabwe.
|
||
|
||
The system:
|
||
|
||
* Uses satellite imagery from the **Digital Earth Africa (DEA) STAC API**
|
||
* Uses **Dynamic World (DW) seasonal baselines**
|
||
* Applies custom ML models for crop refinement
|
||
* Is geographically restricted to **Zimbabwe only**
|
||
* Is spatially restricted to **maximum 5km AOI radius**
|
||
* Is deployed on a **self-managed K3s Kubernetes cluster**
|
||
|
||
Outputs are delivered as:
|
||
|
||
* Refined LULC GeoTIFF (10m resolution)
|
||
* Optional supporting rasters (DW baseline, indices, true color)
|
||
|
||
---
|
||
|
||
# 2. Current System State (Already Built — Do Not Rebuild)
|
||
|
||
⚠️ ATTN ROO CODE: Infrastructure is complete and running. Do NOT recreate cluster, ingress, TLS, or storage.
|
||
|
||
---
|
||
|
||
## 2.1 Infrastructure & Networking
|
||
|
||
* K3s cluster (1 control plane, 2 workers)
|
||
* NGINX Ingress Controller active
|
||
* cert-manager with Let’s Encrypt Production ClusterIssuer
|
||
* All domains operational over HTTPS:
|
||
|
||
* portfolio.techarvest.co.zw
|
||
* api.portfolio.techarvest.co.zw
|
||
* minio.portfolio.techarvest.co.zw
|
||
* console.minio.portfolio.techarvest.co.zw
|
||
|
||
---
|
||
|
||
## 2.2 Live Services (Namespace: geocrop)
|
||
|
||
### MinIO (minio)
|
||
|
||
* S3-compatible object storage
|
||
* Buckets (planned/partially used):
|
||
|
||
* geocrop-baselines
|
||
* geocrop-models
|
||
* geocrop-results
|
||
* geocrop-datasets
|
||
|
||
### Redis (redis)
|
||
|
||
* Used as message broker for asynchronous ML tasks
|
||
* Queue name: geocrop_tasks
|
||
|
||
### FastAPI Backend (geocrop-api)
|
||
|
||
* Live and publicly accessible
|
||
* JWT authentication functional
|
||
* Accepts AOI payload (Lat, Lon, Radius)
|
||
* Pushes async tasks to Redis
|
||
* Returns job_id
|
||
|
||
### Python RQ Worker (geocrop-worker)
|
||
|
||
* Live and listening to Redis queue
|
||
* Currently runs mock inference using time.sleep()
|
||
* Returns hardcoded JSON result
|
||
|
||
### Dynamic World Baselines
|
||
|
||
* DW seasonal GeoTIFFs successfully migrated from Google Drive
|
||
* Converted to Cloud Optimized GeoTIFFs (COGs)
|
||
* Stored locally and ready for MinIO upload
|
||
|
||
---
|
||
|
||
# 3. Development Objectives for Roo Code
|
||
|
||
Primary Objective: Replace mock pipeline with real geospatial + ML processing.
|
||
|
||
---
|
||
|
||
# Phase 1 — Real Worker Pipeline
|
||
|
||
## 3.1 STAC Integration
|
||
|
||
Worker must:
|
||
|
||
* Query DEA STAC endpoint:
|
||
[https://explorer.digitalearth.africa/stac/search](https://explorer.digitalearth.africa/stac/search)
|
||
* Filter by:
|
||
|
||
* AOI geometry (circle polygon)
|
||
* Date range: **Summer Cropping Season = Sept 1 – May 30 (must match model training window exactly)**
|
||
* Year range: 2015 – Present
|
||
* Use Sentinel-2 L2A collection (initial version)
|
||
|
||
⚠️ Correct seasonal window: Sept 1 – May 30 (not Sept–May)
|
||
|
||
---
|
||
|
||
## 3.2 Feature Engineering
|
||
|
||
Worker must compute:
|
||
|
||
* True Color composite
|
||
* NDVI
|
||
* EVI
|
||
* SAVI
|
||
* Peak NDVI/EVI/SAVI (seasonal max)
|
||
|
||
Feature consistency must match training feature_list.json.
|
||
|
||
---
|
||
|
||
## 3.3 ML Inference
|
||
|
||
Worker must:
|
||
|
||
* Load selected model from MinIO (geocrop-models bucket)
|
||
* Load:
|
||
|
||
* model.pkl
|
||
* feature_list.json
|
||
* scaler.pkl (if used)
|
||
* label_encoder.json
|
||
* Validate feature alignment
|
||
* Run inference
|
||
|
||
---
|
||
|
||
## 3.4 Neighborhood Smoothing
|
||
|
||
Implement configurable majority filter:
|
||
|
||
* Default: 3x3 kernel
|
||
* Optional: 5x5
|
||
|
||
Rule:
|
||
If pixel class confidence is low AND surrounded by strong majority → flip to majority.
|
||
|
||
---
|
||
|
||
## 3.5 Output Generation
|
||
|
||
Worker must:
|
||
|
||
* Export refined output as **Cloud Optimized GeoTIFF (COG)**
|
||
* Save to MinIO under:
|
||
geocrop-results/jobs/{job_id}/refined.tif
|
||
|
||
Optional outputs:
|
||
|
||
* truecolor.tif
|
||
* ndvi_peak.tif
|
||
* dw_clipped.tif
|
||
|
||
---
|
||
|
||
# Phase 2 — Tile Service (TiTiler)
|
||
|
||
Deploy geocrop-tiler service:
|
||
|
||
* Reads COGs from MinIO
|
||
* Serves XYZ tiles
|
||
* Exposed via tiles.portfolio.techarvest.co.zw
|
||
|
||
Requirement:
|
||
|
||
* Sub-second tile latency
|
||
|
||
---
|
||
|
||
# Phase 3 — React Frontend
|
||
|
||
Frontend must:
|
||
|
||
* Implement JWT login
|
||
* AOI selection via Leaflet
|
||
* Radius limit 5km
|
||
* Zimbabwe boundary validation
|
||
* Year dropdown (2015–present)
|
||
* Model dropdown
|
||
* Submit job to API
|
||
* Poll status endpoint
|
||
* Render layers via tile server
|
||
* Download GeoTIFF via signed URL
|
||
|
||
Map Layers:
|
||
|
||
* Refined ML LULC
|
||
* Dynamic World baseline
|
||
* True Color
|
||
* Peak NDVI/EVI/SAVI
|
||
|
||
Legend required.
|
||
|
||
---
|
||
|
||
# 4. Functional Requirements
|
||
|
||
## 4.1 Authentication & Quotas
|
||
|
||
REQ-1.1: JWT authentication required.
|
||
REQ-1.2: Standard users limited to 5 jobs per 24 hours.
|
||
REQ-1.3: Global concurrency cap = 2 running jobs cluster-wide.
|
||
REQ-1.4: Admin users bypass quotas.
|
||
|
||
---
|
||
|
||
## 4.2 AOI Validation
|
||
|
||
REQ-2.1: AOI must fall strictly within Zimbabwe boundary (GeoJSON boundary file required).
|
||
REQ-2.2: Radius must be ≤ 5km.
|
||
REQ-2.3: Reject complex polygons exceeding vertex threshold.
|
||
|
||
---
|
||
|
||
## 4.3 Job Pipeline
|
||
|
||
REQ-3.1: API queues job in Redis.
|
||
REQ-3.2: Worker processes job asynchronously.
|
||
REQ-3.3: Worker saves COG outputs to MinIO.
|
||
REQ-3.4: API generates signed URL for download.
|
||
REQ-3.5: Deterministic cache key must be implemented:
|
||
|
||
Hash(year + season + model_version + lat + lon + radius)
|
||
|
||
If identical request exists → return cached result.
|
||
|
||
---
|
||
|
||
## 4.4 Admin Operations
|
||
|
||
REQ-4.1: Admin upload dataset to geocrop-datasets bucket.
|
||
REQ-4.2: Admin trigger retraining via Kubernetes Job.
|
||
REQ-4.3: Model registry must store:
|
||
|
||
* model_name
|
||
* version
|
||
* training_date
|
||
* features_used
|
||
* class_mapping
|
||
|
||
---
|
||
|
||
# 5. External Interfaces
|
||
|
||
## 5.1 DEA STAC API
|
||
|
||
HTTPS-based STAC search queries.
|
||
|
||
## 5.2 MinIO S3 API
|
||
|
||
All object storage via signed S3 URLs.
|
||
|
||
## 5.3 Optional Historical Weather API
|
||
|
||
Used to enrich metadata (not required for MVP).
|
||
|
||
---
|
||
|
||
# 6. Performance & Security Attributes
|
||
|
||
* GET /jobs/{id} response < 500ms
|
||
* ML job timeout = 25 minutes
|
||
* Tile latency < 1 second
|
||
* All traffic via HTTPS
|
||
* MinIO private
|
||
* Signed URLs only
|
||
* Secrets stored as Kubernetes Secrets
|
||
|
||
---
|
||
|
||
# 7. Architectural Clarifications for Roo
|
||
|
||
* Namespace: geocrop
|
||
* Ingress class: nginx
|
||
* ClusterIssuer: letsencrypt-prod
|
||
* Do NOT rebuild cluster
|
||
* Do NOT expose MinIO publicly
|
||
* Do NOT bypass quota logic
|
||
|
||
---
|
||
|
||
# 8. Future Enhancements (Post-MVP)
|
||
|
||
* Postgres for persistent user/job storage
|
||
* Confidence raster layer
|
||
* Area statistics panel
|
||
* Model comparison mode
|
||
* Side-by-side DW vs Refined slider
|
||
|
||
---
|
||
|
||
# Summary
|
||
|
||
Infrastructure is complete.
|
||
|
||
Next focus:
|
||
|
||
1. Replace mock worker with real STAC + ML pipeline
|
||
2. Deploy tiler
|
||
3. Build frontend
|
||
4. Add quotas + caching
|
||
|
||
This SRS defines execution boundaries for Roo Code.
|