# CLAUDE.md - GeoCrop Engineering Guide

GeoCrop is a production-grade, self-hosted ML platform for crop-type classification in Zimbabwe.

## 🚀 Key Commands

```bash
# Frontend (React 19 + TypeScript)
cd apps/web && npm install && npm run dev

# API (FastAPI)
cd apps/api && uvicorn main:app --reload

# Worker (RQ)
cd apps/worker && python worker.py --worker

# Infrastructure (K8s)
# Manifests are managed via ArgoCD. Pushing to 'main' triggers reconciliation.
# Root manifests in k8s/base/
```

## 🚢 CI/CD & GitOps

- **Source Control**: Gitea (`git.techarvest.co.zw`).
- **CI**: Gitea Actions (`.gitea/workflows/build-push.yaml`) builds and pushes images to Docker Hub.
- **CD**: ArgoCD (`cd.techarvest.co.zw`) tracks `k8s/base/` and auto-syncs to the `geocrop` namespace.
- **Git Repo**: `http://gitea.geocrop.svc.cluster.local:3000/fchinembiri/geocrop-platform..git`

## 🌐 Endpoints

- **Portfolio**: `portfolio.techarvest.co.zw`
- **API**: `api.portfolio.techarvest.co.zw`
- **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`
- **MinIO**: `minio.portfolio.techarvest.co.zw`

## 📐 Architecture & Patterns

### Components
- **Web**: React 19 + OpenLayers. UI for portfolio and interactive crop mapping.
- **API**: FastAPI. Handles auth (JWT), job validation, and queueing.
- **Worker**: RQ-based Python worker. Orchestrates STAC fetch → Feature extraction → Inference → smoothing → COG export.
- **Tiler**: TiTiler. Serves tiles directly from MinIO COGs via S3 protocol.

### Storage (MinIO)
- `geocrop-models`: ML models and MLflow artifacts.
- `geocrop-baselines`: Dynamic World COGs.
- `geocrop-results`: Inference outputs (COGs).

### Non-Obvious Constraints
- **Kubernetes Only**: Only modify resources managed by K8s. **Avoid** host-level configs (Nginx/CloudPanel).
- **AOI Format**: `(lon, lat, radius_m)` — Longitude first.
- **Season Window**: Sept 1st to May 31st (Zimbabwe Summer).
- **Feature Order**: `FEATURE_ORDER_V1` (51 features) is immutable.

## 📂 Repository Structure

- `apps/`: Source code for web, api, and worker.
- `k8s/base/`: Kubernetes manifests (ArgoCD target).
- `training/`: Model training scripts and research.
- `plan/`: Architectural blueprints and restructuring reports.
- `ops/`: Infrastructure scripts and data migration tools.