# 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 (STRICT)

- **Source Control**: Gitea (`git.techarvest.co.zw`).
- **CI**: Gitea Actions builds images using **Kaniko** (DIND is deprecated).
- **Tagging**: Deterministic SHA-based tagging (managed by CI).
- **CD**: ArgoCD (`cd.techarvest.co.zw`) tracks `k8s/base/`.
- **Policy**:
    - All changes MUST be pushed to Gitea.
    - Deployments occur ONLY via CI/CD + ArgoCD.
    - Manual server/container modifications are forbidden.
    - No bypassing GitOps for production state.

## 🌐 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.

### 🛑 STRICT ENGINEERING POLICY
* All approved changes MUST be committed and pushed to Gitea.
* All deployments MUST occur ONLY through the CI/CD pipeline via ArgoCD.
* Direct manual server modifications are forbidden.
* No bypassing ArgoCD.
* No hotfixes directly on running containers.
* Infrastructure state must remain GitOps-managed.
