# 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 the `geocrop-platform` application.
- **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`