MythEclipseandClaude
6ba3deb149
- Root README redesigned as landing page with 7 sub-chapters - Each child README gets navigation header + footer linking back to root - Cross-links between Machine_Learning, ml-service, and infra READMEs - Reduced duplication: root summarizes, children provide full detail - Net -207 lines, cleaner structure Co-Authored-By: Claude <noreply@anthropic.com>
289 lines
9.9 KiB
Markdown
289 lines
9.9 KiB
Markdown
# 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](#1-tentang-zeavis-edu)
|
||
2. [Kelas Penyakit](#2-kelas-penyakit)
|
||
3. [Arsitektur Proyek](#3-arsitektur-proyek)
|
||
4. [Tech Stack](#4-tech-stack)
|
||
5. [Panduan Memulai](#5-panduan-memulai)
|
||
- [5.1 Instalasi Root Workspace](#51-instalasi-root-workspace)
|
||
- [5.2 Menjalankan Aplikasi Web & API](#52-menjalankan-aplikasi-web--api)
|
||
- [5.3 Pipeline Machine Learning](#53-pipeline-machine-learning)
|
||
- [5.4 ML Inference Service](#54-ml-inference-service)
|
||
- [5.5 Infrastruktur & Deployment](#55-infrastruktur--deployment)
|
||
- [5.6 Telemetry & Observabilitas](#56-telemetry--observabilitas)
|
||
6. [Dokumentasi Lengkap](#6-dokumentasi-lengkap)
|
||
7. [Troubleshooting Umum](#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`](apps/ml-service/README.md) |
|
||
| ML Pipeline | Python, TensorFlow/Keras, EfficientNetV2B0 | [`Machine_Learning/README.md`](Machine_Learning/README.md) |
|
||
| Infrastruktur | Docker, Coolify, Traefik, Tailscale | [`infra/README.md`](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
|
||
|
||
```bash
|
||
# 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
|
||
|
||
```bash
|
||
# 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`](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`](apps/ml-service/README.md)
|
||
|
||
```bash
|
||
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`](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 |
|
||
|
||
```bash
|
||
# 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.
|
||
|
||
```bash
|
||
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`](Machine_Learning/README.md) | Panduan lengkap pipeline ML — preprocessing, training Colab, ekspor model TFLite/TFJS/ONNX |
|
||
| [`apps/ml-service/README.md`](apps/ml-service/README.md) | ML inference service — setup, endpoint API, konfigurasi, troubleshooting |
|
||
| [`infra/README.md`](infra/README.md) | Arsitektur multi-VPS — diagram, GitHub Secrets, port, metrics flow |
|
||
| [`METRICS.md`](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:
|
||
```bash
|
||
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:
|
||
```bash
|
||
ls -la Machine_Learning/model/model.onnx
|
||
```
|
||
Jika belum, jalankan pipeline ML terlebih dahulu — lihat [`Machine_Learning/README.md`](Machine_Learning/README.md).
|
||
|
||
### Docker Compose gagal — network tidak ditemukan
|
||
```bash
|
||
docker network create app-shared-net
|
||
```
|
||
|
||
### Konversi TensorFlow.js gagal (konflik protobuf)
|
||
```bash
|
||
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
|