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

2.8 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 (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.