78 lines
3.1 KiB
Markdown
78 lines
3.1 KiB
Markdown
# 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`
|