EcoBot

Introduction

Pendahuluan

EcoBot is a Python/Flask backend for WhatsApp-based waste management. It integrates AI text and vision, a SQLite database, and role-based workflows to deliver education, schedules, collection locations, and administrative operations.

EcoBot adalah backend Python/Flask untuk pengelolaan sampah berbasis WhatsApp. Sistem ini mengintegrasikan AI teks dan gambar, database SQLite, serta alur kerja berbasis peran untuk edukasi, jadwal, lokasi pengumpulan, dan operasi administratif.

Version 1.5.0 introduces hybrid AI mode, database-backed long‑term memory, resilient API calls, and a toggleable registration flow.

Versi 1.5.0 menghadirkan mode AI hybrid, memori percakapan berbasis database, pemanggilan API yang lebih tangguh, serta alur registrasi yang dapat diatur.

Use Cases / Functions

Kasus Penggunaan / Fungsi

Features

Fitur

• AI Modes - EcoBot (database-only), General, and Hybrid modes selectable via WhatsApp commands.
• Mode AI - EcoBot (khusus database), General, dan Hybrid dapat dipilih melalui perintah WhatsApp.
• Conversation Memory - Long‑term memory stored in SQLite (user facts and conversation history).
• Memori Percakapan - Memori jangka panjang tersimpan di SQLite (fakta pengguna dan riwayat percakapan).
• Registration Modes - Auto or manual, controlled by REGISTRATION_MODE.
• Mode Registrasi - Otomatis atau manual, dikontrol oleh REGISTRATION_MODE.
• WhatsApp Integration - Uses WAHA.
• Integrasi WhatsApp - Menggunakan WAHA.
• AI Providers - Lunos.tech (text) and Unli.dev (vision).
• Penyedia AI - Lunos.tech (teks) dan Unli.dev (visi).
• Admin Commands - /admin help, user/point management, stats, logs, backup, broadcast, report, memory_stats.
• Perintah Admin - /admin help, manajemen user/point, statistik, log, backup, broadcast, report, memory_stats.

Arsitektur Sistem

System Overview

EcoBot menggunakan pola arsitektur microservice yang dibangun di atas kerangka kerja Flask. Sistem ini terdiri dari beberapa komponen kunci yang saling berinteraksi:

EcoBot follows a microservice architecture pattern built on the Flask framework. The system consists of several key components that interact with each other:

Komponen Arsitektur

Architecture Components

Alur Data

Data Flow

Memulai

Getting Started

Quickstart

Quickstart

1. Clone and install

   Klon dan instal

   git clone https://github.com/mycoderisyad/raflangt-ecobot.git
   cd raflangt-ecobot
   python3 -m venv venv && source venv/bin/activate
   pip install -r requirements.txt

2. Configure environment

   Konfigurasi lingkungan

   cp .env.example .env
   # edit .env and set at minimum:
   WAHA_BASE_URL=...
   WAHA_API_KEY=...
   LUNOS_API_KEY=...
   LUNOS_BASE_URL=...
   REGISTRATION_MODE=auto

3. Run the server

   Jalankan server

   python3 main.py

4. Point WAHA webhook to EcoBot

   Arahkan webhook WAHA ke EcoBot

   Set WAHA instance webhook URL to http://<your-server>:5000/webhook (or your public URL). Ensure the instance is connected.

   Setel URL webhook instance WAHA ke http://<server-anda>:5000/webhook (atau URL publik Anda). Pastikan instance tersambung.

5. Test via WhatsApp

   Uji melalui WhatsApp

   • Send help to see features by role
   • Kirim help untuk melihat fitur sesuai peran
   • Try AI modes: /hybrid-ecobot, /layanan-ecobot, /general-ecobot
   • Coba mode AI: /hybrid-ecobot, /layanan-ecobot, /general-ecobot
   • Send an image to receive waste classification
   • Kirim gambar untuk klasifikasi sampah

Persyaratan

Requirements

• Python 3.10 atau lebih tinggi
• pip (manajer paket Python)
• Virtual environment (direkomendasikan)
• Git untuk kontrol versi

Instalasi

Installation

# Clone the repository
git clone https://github.com/raflangt/ecobot.git
cd ecobot

# Buat virtual environment
python3 -m venv venv
source venv/bin/activate  # Di Windows: venv\Scripts\activate

# Install dependensi
pip install -r requirements.txt

# Siapkan konfigurasi lingkungan
cp .env.example .env
# Edit file .env dengan kunci API dan konfigurasi Anda

Menjalankan Aplikasi

Running the Application

# Mode pengembangan (default)
python3 main.py

# Mode produksi
python3 main.py --production

# Produksi dengan Gunicorn
gunicorn -w 4 -b 0.0.0.0:8000 'main:create_app("production")'

Konfigurasi

Configuration

Variabel Lingkungan

Environment Variables

Dokumentasi API

API Documentation

Base URLs

Base URLs

Endpoint sensitif atau administratif tidak dipublikasikan di dokumentasi publik. Untuk akses programatik, hubungi pengelola proyek.

Sensitive or administrative API endpoints are not published in the public documentation for security reasons. For programmatic access, contact the project maintainer.

Minta Akses API melalui WhatsApp Request API Access via WhatsApp

Contoh Respons

Response Examples

Health Check Response

Health Check Response

GET /health

{
    "status": "healthy",
    "service": "EcoBot",
    "version": "1.5.0",
    "environment": "production"
}

Format Respons Error

Error Response Format

{
    "error": {
        "code": 400,
        "message": "Format permintaan tidak valid",
        "details": "Kolom yang dibutuhkan hilang: phone_number"
    }
}

Contoh Penggunaan

Usage Examples

WhatsApp Webhook Integration

WhatsApp Webhook Integration

# Contoh pemrosesan payload webhook dari WAHA
# Pastikan Anda telah mengonfigurasi endpoint webhook di dasbor WAHA
{
    "messages": [{
        "from": "whatsapp:+6281234567890",
        "body": "Jadwal sampah",
        "type": "text"
    }]
}

Alur Integrasi

Workflow Integration

Panduan Deployment

Deployment Guide

Deployment Produksi dengan Heroku/Gunicorn

Production Deployment with Heroku/Gunicorn

# Pastikan file Procfile dan requirements.txt sudah ada di root proyek
# Procfile: web: gunicorn -w 4 -b 0.0.0.0:$PORT main:create_app()
# requirements.txt: flask, gunicorn, requests, dll.

# Login ke Heroku CLI
heroku login

# Buat aplikasi baru di Heroku
heroku create nama-app-unik-ecobot

# Hubungkan repositori Git Anda
git push heroku master

# Setel variabel lingkungan
heroku config:set WAHA_BASE_URL=...
heroku config:set WAHA_API_KEY=...
...

Praktik Terbaik Keamanan

Security Best Practices

Keamanan API

API Security

• Proteksi Kunci API: Simpan kunci di variabel lingkungan, jangan pernah di kode.
• API Key Protection: Store keys in environment variables, never in code.
• Hanya HTTPS: Selalu gunakan enkripsi SSL/TLS di lingkungan produksi.
• HTTPS Only: Always use SSL/TLS encryption in production.
• Validasi Input: Validasi semua data yang masuk dan bersihkan input untuk mencegah serangan.
• Input Validation: Validate all incoming data and sanitize inputs.

Keamanan Infrastruktur

Infrastructure Security

• Reverse Proxy: Gunakan Nginx atau Caddy sebagai reverse proxy dengan header keamanan.
• Reverse Proxy: Use Nginx or Caddy as a reverse proxy with security headers.
• Firewall: Batasi akses ke port yang diperlukan saja.
• Firewall Rules: Restrict access to necessary ports only.
• Pembaruan Reguler: Jaga sistem dan dependensi selalu terbarui.
• Regular Updates: Keep system and dependencies updated.

Changelog / Rencana Masa Depan

Changelog / Future Work

Riwayat Versi

Version History

Rencana Perbaikan

Planned Improvements

• Pelatihan model AI yang disesuaikan untuk akurasi klasifikasi sampah yang lebih baik.
• Enhanced AI model training for better waste classification accuracy.
• Dashboard analitik real-time untuk koordinator.
• Real-time dashboard for coordinator analytics.
• Sistem Poin dan Redeem untuk insentif warga.
• Point and Redeem System for citizen incentives.
• Dukungan multi-bahasa untuk komunitas yang beragam.
• Multi-language support for diverse communities.