71 lines
2.5 KiB
Markdown
71 lines
2.5 KiB
Markdown
# 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.
|