3.1 KiB
3.1 KiB
AGENTS.md - GeoCrop Intelligence & Patterns
This file provides foundational guidance for AI agents working within this repository. Adhere to these patterns to maintain system integrity.
🛠️ Project Stack
- Frontend: React 19 + TypeScript + Vite + OpenLayers (Leaflet fallback).
- API: FastAPI + Redis + RQ Job Queue.
- Worker: Python 3.11, rasterio, scikit-learn, XGBoost, LightGBM, CatBoost.
- GitOps: Gitea (Source) + Gitea Actions (CI) + ArgoCD (CD).
- Storage: MinIO (S3-compatible) + PostGIS (Metadata).
- Observability: MLflow (Experiments) + JupyterLab (Research).
🚀 Build & Dev Commands
Frontend
cd apps/web && npm install && npm run dev
API
cd apps/api && uvicorn main:app --host 0.0.0.0 --port 8000 --reload
Worker
cd apps/worker && python worker.py --worker
Docker (Local Build)
docker build -t frankchine/geocrop-web:latest apps/web/
🧠 Critical Patterns (Non-Obvious)
🚫 Scoping Mandate
- Kubernetes Only: Focus exclusively on resources managed by Kubernetes. NEVER modify host-level Nginx, CloudPanel, or system services outside the cluster.
🗺️ Geospatial Conventions
- AOI Format: Always
(lon, lat, radius_m). (Longitude first!). - Season Window: "Summer" = Sept 1st to May 31st of following year.
- Zimbabwe Bounds: Lon 25.2–33.1, Lat -22.5 to -15.6.
- Feature Order:
FEATURE_ORDER_V1(51 features) is strictly immutable.
🔌 Connectivity
- Redis Host:
redis.geocrop.svc.cluster.local(Port 6379). - MinIO Host:
minio.geocrop.svc.cluster.local(Port 9000). - Queue Name:
geocrop_tasks.
📦 Storage Layout (MinIO)
geocrop-models/: Serialized ML models (.pkl) and MLflow artifacts.geocrop-baselines/: Dynamic World COGs (dw/zim/summer/...).geocrop-results/: Output COGs (results/<job_id>/...).geocrop-datasets/: Training CSVs.
🚢 GitOps Workflow
- CI: Build and Push via
.gitea/workflows/build-push.yaml. - CD: ArgoCD tracks
k8s/base/in thegeocrop-platformapplication. - Secrets: Managed via Kubernetes Secrets (e.g.,
geocrop-secrets,geocrop-db-secret).
📊 Current Kubernetes State (geocrop namespace)
| Deployment | Role | Status |
|---|---|---|
geocrop-web |
React Frontend | Running (1/1) |
geocrop-api |
FastAPI Backend | Running (1/1) |
geocrop-worker |
Inference Engine | Running (1/1) |
gitea |
Source Control | Running (1/1) |
gitea-runner |
CI Runner (Actions) | Running (1/1) |
mlflow |
Experiment Tracking | Running (1/1) |
jupyter-lab |
Data Science IDE | Running (1/1) |
geocrop-db |
PostGIS Database | Running (1/1) |
redis |
Job Broker | Running (1/1) |
minio |
S3 Storage | Running (1/1) |
geocrop-tiler |
Dynamic Tile Server | Running (2/2) |
🌐 Endpoints
- Portfolio:
portfolio.techarvest.co.zw - API Docs:
api.portfolio.techarvest.co.zw/docs - Gitea:
git.techarvest.co.zw - ArgoCD:
cd.techarvest.co.zw - MLflow:
ml.techarvest.co.zw - Jupyter:
lab.techarvest.co.zw - Tiler:
tiles.portfolio.techarvest.co.zw