fchinembiri
/
geocrop-platform.
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
geocrop-platform./CLAUDE.md

2.4 KiB
Raw Blame History

CLAUDE.md - GeoCrop Engineering Guide

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

🚀 Key Commands

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