ZeaVis Edu

Klasifikasi penyakit daun jagung berbasis machine learning — dari dataset hingga aplikasi web.

ZeaVis Edu adalah aplikasi edukasi pengenalan penyakit daun jagung melalui klasifikasi gambar. Repositori ini mencakup pipeline machine learning lengkap (EfficientNetV2B0), layanan inferensi Rust/ONNX Runtime, aplikasi web React, API backend Elysia, serta infrastruktur multi-VPS dengan observabilitas penuh.

---

Daftar Isi

1. Tentang ZeaVis Edu
2. Kelas Penyakit
3. Arsitektur Proyek
4. Tech Stack
5. Panduan Memulai
   • 5.1 Instalasi Root Workspace
   • 5.2 Menjalankan Aplikasi Web & API
   • 5.3 Pipeline Machine Learning
   • 5.4 ML Inference Service
   • 5.5 Infrastruktur & Deployment
   • 5.6 Telemetry & Observabilitas
6. Dokumentasi Lengkap
7. Troubleshooting Umum

---

1. Tentang ZeaVis Edu

ZeaVis Edu membantu petani, peneliti, dan pelajar mengidentifikasi penyakit daun jagung secara cepat menggunakan kamera. Pengguna cukup mengunggah foto daun jagung dan sistem akan mengklasifikasikannya ke dalam salah satu dari empat kategori kondisi daun.

Fitur Utama

• Aplikasi Web — Antarmuka pengguna interaktif berbasis React + Vite
• API Backend — Layanan data dan autentikasi berbasis Elysia + PostgreSQL
• ML Inference Service — Inferensi real-time via Rust/Axum + ONNX Runtime
• Pipeline ML — Preprocessing dataset, pelatihan di Google Colab, ekspor model ke TFLite, TFJS, dan ONNX
• Infrastruktur Multi-VPS — Deployment produksi dengan Tailscale mesh VPN
• Observabilitas — Prometheus → ClickHouse pipeline dengan dashboard metrik

---

2. Kelas Penyakit

Model mengklasifikasikan gambar ke dalam 4 kelas berbahasa Indonesia:

Label	Deskripsi
Bercak Daun	Gray Leaf Spot — bercak abu-abu memanjang
Hawar Daun	Northern/Southern Leaf Blight — hawar coklat berbentuk panjang
Karat Daun	Common Rust — bintik coklat kemerahan berbentuk pustula
Daun Sehat	Daun jagung tanpa gejala penyakit

---

3. Arsitektur Proyek

.
├── apps/
│   ├── api/                # Backend Elysia/Bun + Drizzle ORM + PostgreSQL
│   ├── ml-service/         # Layanan inferensi Rust/Axum + ONNX Runtime
│   └── web/                # Frontend React + Vite + Tailwind
├── Machine_Learning/       # Pipeline dataset, training, dan ekspor model
│   └── README.md           # ⤷ Panduan lengkap pipeline ML
├── infra/
│   └── README.md           # ⤷ Panduan deployment multi-VPS
├── packages/
│   └── shared/             # Tipe dan utilitas bersama TypeScript
├── telemetry/              # Submodule — Prometheus → ClickHouse pipeline
├── docker-compose.yml      # Konfigurasi deployment container
├── package.json            # Root workspace Bun + Moon
└── README.md               # ⤷ Anda di sini

Komponen	Teknologi	Dokumentasi
Web Frontend	React, Vite, Tailwind, Zustand	apps/web/
API Backend	Bun, Elysia, Drizzle ORM, PostgreSQL	apps/api/
ML Inference	Rust, Axum, ONNX Runtime	apps/ml-service/README.md
ML Pipeline	Python, TensorFlow/Keras, EfficientNetV2B0	Machine_Learning/README.md
Infrastruktur	Docker, Coolify, Traefik, Tailscale	infra/README.md
Telemetry	Prometheus, ClickHouse, Vector, Vue 3	telemetry/

---

4. Tech Stack

Frontend

React • Vite • TypeScript • React Router • TanStack Query • Zustand • Tailwind CSS

Backend API

Bun • Elysia • Drizzle ORM • PostgreSQL

Machine Learning

Python • TensorFlow/Keras • EfficientNetV2B0 • Rust • Axum • ONNX Runtime • TFLite • TensorFlow.js

Tooling & Deployment

Bun workspaces • Moon task runner • Docker • Docker Compose • Coolify • Traefik

Telemetry & Observabilitas

Prometheus • Metric Ingester (Go) • Vector • ClickHouse • Query Proxy (Go) • Telemetry UI (Vue 3)

---

5. Panduan Memulai

Prasyarat

• Bun — untuk workspace TypeScript
• Python 3.9–3.11 — untuk pipeline ML
• Rust & Cargo — untuk apps/ml-service
• Docker & Docker Compose — untuk deployment dan telemetry
• PostgreSQL — untuk backend API

5.1 Instalasi Root Workspace

# Clone repositori
git clone https://github.com/mytheclipse/zeavis-edu.git
cd zeavis-edu

# Instal dependensi TypeScript workspace
bun install

5.2 Menjalankan Aplikasi Web & API

# Semua task development (web + api)
bun run dev

# Atau jalankan terpisah:
cd apps/web && bun run dev     # Frontend — Vite dev server
cd apps/api && bun run start   # API backend

Environment variables yang perlu disiapkan di root .env:

Variable	Keterangan
DATABASE_URL	URL koneksi PostgreSQL
SESSION_SECRET	Secret untuk session auth
WEB_APP_URL	URL frontend (untuk CORS)
ML_SERVICE_URL	URL layanan inferensi ML

5.3 Pipeline Machine Learning

Pipeline lengkap preprocessing dataset, pelatihan model di Google Colab, dan ekspor ke berbagai format produksi.

📖 Panduan lengkap: Machine_Learning/README.md

Ringkasan alur:

1. Unduh 3 file ZIP dataset ke Machine_Learning/
2. Jalankan python preprocessing.py untuk menggabungkan dataset
3. Upload dataset.zip ke Google Drive
4. Jalankan notebook.ipynb di Google Colab (GPU T4)
5. Download best_model.keras hasil training
6. Ekspor model: python save_model.py → TFLite + SavedModel
7. Konversi ke TFJS dan ONNX

Output pipeline:

Path	Format	Kegunaan
Machine_Learning/model/saved_model/	TensorFlow SavedModel	Jembatan konversi
Machine_Learning/model/model.tflite	TFLite	Mobile (Android/iOS)
Machine_Learning/model/model.onnx	ONNX	Rust inference service
Machine_Learning/model/tfjs_model/	TensorFlow.js	Web browser

5.4 ML Inference Service

Layanan inferensi berbasis Rust/Axum dengan ONNX Runtime untuk prediksi real-time.

📖 Panduan lengkap: apps/ml-service/README.md

cd apps/ml-service
cargo run                           # Default port 8000

# Atau dengan konfigurasi custom:
MODEL_PATH=/path/to/model.onnx ML_SERVICE_PORT=9000 cargo run

Endpoint utama:

Method	Path	Deskripsi
GET	/health	Health check + status model
GET	/metadata	Info model, label, versi
POST	/predict	Klasifikasi gambar (multipart upload)

5.5 Infrastruktur & Deployment

📖 Panduan lengkap: infra/README.md

Arsitektur produksi berjalan di dua VPS terpisah yang terhubung via Tailscale mesh VPN:

VPS	Hostname	Peran
App VPS	imrnes (Arch Linux)	Web, API, ML Service
Telemetry VPS	orange (Ubuntu)	Prometheus, ClickHouse, Telemetry UI

# Deploy app services via Docker Compose
docker compose up -d

# Deploy telemetry stack
make telemetry-up

5.6 Telemetry & Observabilitas

Pipeline metrik lengkap: Prometheus → Metric Ingester → Vector → ClickHouse → Telemetry UI.

Setiap service ZeaVis Edu mengekspos endpoint GET /metrics dalam format Prometheus. Prometheus di Telemetry VPS melakukan scrape melalui IP Tailscale.

make telemetry-up          # Mode produksi
make telemetry-up-local    # Mode development lokal
make telemetry-status      # Cek kesehatan
make telemetry-logs        # Lihat log

Service	Port	Peran
Prometheus	9090	Scraping & remote_write
Metric Ingester	9091	Enrichment & filtering
Vector	9001	Buffering
ClickHouse	8123	Penyimpanan analitik
Query Proxy	9092	Read-only SQL proxy
Telemetry UI	8181	Dashboard metrik

---

6. Dokumentasi Lengkap

Dokumen	Isi
Machine_Learning/README.md	Panduan lengkap pipeline ML — preprocessing, training Colab, ekspor model TFLite/TFJS/ONNX
apps/ml-service/README.md	ML inference service — setup, endpoint API, konfigurasi, troubleshooting
infra/README.md	Arsitektur multi-VPS — diagram, GitHub Secrets, port, metrics flow
METRICS.md	Daftar lengkap metrik Prometheus yang diekspos
telemetry/ (submodule)	Source code telemetry stack

---

7. Troubleshooting Umum

bun install gagal

Pastikan Bun versi terbaru terinstal:

bun --version   # minimal 1.x

API membutuhkan database

Pastikan DATABASE_URL tersedia di root .env dan PostgreSQL dapat diakses.

ML service gagal memuat model

Pastikan Machine_Learning/model/model.onnx sudah dibuat:

ls -la Machine_Learning/model/model.onnx

Jika belum, jalankan pipeline ML terlebih dahulu — lihat Machine_Learning/README.md.

Docker Compose gagal — network tidak ditemukan

docker network create app-shared-net

Konversi TensorFlow.js gagal (konflik protobuf)

export PROTOCOL_BUFFERS_PYTHON_IMPLEMENTATION=python

---

Pengembangan

1. bun install
2. Jalankan service yang dibutuhkan secara lokal
3. bun run typecheck sebelum commit
4. bun run build untuk verifikasi build produksi
5. Ikuti dokumentasi detail di masing-masing README untuk perubahan spesifik

---

🧬 ZeaVis Edu — Memberdayakan pertanian presisi melalui machine learning