README Project

KopiBot - AI Chatbot Order System

## AI Agent Coffee Shop Commerce Platform Platform AI untuk otomatisasi order, customer service, loyalty customer, Customer CRM, Customer Portal, dan manajemen multi cabang coffee shop. ### Features - AI Chatbot Order Menu - WhatsApp / Telegram / Discord Integration - Multi Branch Management - AI Upselling & Promo Recommendation - Order via Website & Chat Apps - Variant Product & Topping Support - Loyalty Point, Redeem Point, and Customer CRM - Customer Self-Service Dashboard - Multi Currency, Tax, and Timezone ### Tech Stack PHP Native - MySQL - OpenAI - Anthropic WhatsApp Gateway - REST API - LLM AI ### Suitable For Coffee Shop - Cafe - Restaurant - Bakery - Beverage Store Dibuat dan dikembangkan oleh: Kukuh TW Email : kukuhtw@gmail.com WhatsApp : https://wa.me/628129893706 Instagram : @kukuhtw X/Twitter : @kukuhtw GitHub : https://github.com/kukuhtw/toko_kopi Facebook : https://www.facebook.com/kukuhtw LinkedIn : https://linkedin.com/in/kukuhtw Demo: https://botlelang.com/toko_kopi Copyright 2026 Kukuh TW. All rights reserved.

Sistem chatbot pemesanan kopi berbasis PHP 8 native, tanpa framework besar, dengan satu codebase untuk multi-cabang, multi-channel, multi-bahasa, promo engine, loyalty point, Customer CRM, Customer Portal, dan plugin system.

Fitur

Kategori	Detail
Chatbot AI	Intent detection berbasis rule dan LLM untuk order, promo, dan customer interaction
Multi Cabang	Satu brand, banyak cabang dengan menu, promo, pengaturan, mata uang, dan timezone terpisah
Multi Channel	Website, WhatsApp, Telegram, dan Discord dengan logika chatbot yang sama
Plugin System	Tambah fitur tanpa ubah kode inti melalui action/filter hooks
Shopping Cart	Tambah, edit, hapus, clear, promo, dan checkout berbasis session
Checkout Flow	Chatbot meminta data customer langkah demi langkah sampai order siap dibuat
Loyalty Point	Earn point otomatis, cek saldo, redeem point via chatbot dan halaman order web
Promo Engine	Diskon persen, nominal, promo code, jadwal promo, min order, dan rekomendasi promo
Payment Gateway	Midtrans dan Xendit via plugin
Menu Management	Upload CSV, variant size/price, topping, dan override per cabang
Dashboard	Super admin lintas cabang, branch admin per cabang, Customer CRM, histori loyalty customer, dan Customer Portal self-service
Customer CRM	Normalisasi identitas customer berbasis email/WhatsApp, notifikasi loyalty, dan log CRM per cabang
Customer Portal	Login customer ringan via kontak + nomor order untuk cek order history, loyalty, profile, dan repeat order
Dokumentasi HTML	README dan docs Markdown tersedia juga sebagai halaman HTML
Export CSV	Export order, menu, promo, dan data dashboard terkait

Persyaratan

PHP 8.0+ dengan ekstensi: pdo_mysql, mbstring, json, fileinfo
MySQL 5.7+ atau MariaDB 10.3+
Apache dengan mod_rewrite aktif
XAMPP sudah cukup untuk development lokal

Instalasi

Panduan lengkap ada di __DOC_CODE_0__.

Cara 1 - Web Installer

Salin folder proyek ke C:\xampp\htdocs\toko_kopi\
Buka:

http://localhost/toko_kopi/public/install.php

Ikuti wizard sampai database, .env, dan akun admin selesai dibuat.
Hapus public/install.php setelah instalasi selesai.

Cara 2 - Instalasi Manual

Buat database toko_kopi
Import:

database/schema.sql
database/seed.sql

Salin .env.example menjadi .env
Isi konfigurasi database dan BASE_URL
Pastikan folder berikut bisa ditulis:

uploads/
storage/logs/

LLM API key tidak diisi di .env, tetapi dikelola lewat dashboard Super Admin.

URL Penting

URL	Keterangan
`http://localhost/toko_kopi/public/`	Landing page
`http://localhost/toko_kopi/public/readme.php`	README versi HTML
`http://localhost/toko_kopi/public/docs/index.php`	Pusat dokumentasi HTML
`http://localhost/toko_kopi/public/docs/sirclo-full-connector.php`	Tutorial integrasi SIRCLO
`http://localhost/toko_kopi/public/login.php`	Login admin
`http://localhost/toko_kopi/public/chat.php`	Chat demo
`http://localhost/toko_kopi/public/order.php?branch={slug}`	Halaman order per cabang
`http://localhost/toko_kopi/public/customer/login.php`	Login Customer Portal
`http://localhost/toko_kopi/public/customer/`	Overview Customer Portal
`http://localhost/toko_kopi/public/customer/orders.php`	Riwayat order customer
`http://localhost/toko_kopi/public/customer/loyalty.php`	Dashboard loyalty customer
`http://localhost/toko_kopi/public/customer/profile.php`	Profil dan preferensi customer

Akun Default

Role	Email	Password
Super Admin	admin@tokokopi.com	password
Admin Jakarta Selatan	admin.jaksel@tokokopi.com	password
Admin Bandung	admin.bandung@tokokopi.com	password
Admin Surabaya	admin.surabaya@tokokopi.com	password

Ganti password setelah login pertama.

Struktur Direktori

toko_kopi/
|-- app/
|   |-- Config/
|   |-- Helpers/
|   |-- Models/
|   |-- Plugin/
|   `-- Services/
|-- database/
|   |-- schema.sql
|   |-- seed.sql
|   `-- add_loyalty_point_plugin.sql
|-- plugins/
|   |-- customer-crm/
|   |-- loyalty-point/
|   |-- midtrans-payment/
|   |-- xendit-payment/
|   |-- telegram-channel/
|   |-- discord-channel/
|   |-- fonnte-whatsapp/
|   |-- twilio-whatsapp/
|   |-- vonage-whatsapp/
|   |-- baileys-whatsapp/
|   |-- messagebird-whatsapp/
|   |-- upselling/
|   |-- rekomendasi-promo/
|   |-- cms-berita/
|   |-- sirclo-full-connector/
|   `-- plugins.json
|-- public/
|   |-- index.php
|   |-- readme.php
|   |-- chat.php
|   |-- order.php
|   |-- docs/
|   |-- api/
|   |-- customer/
|   `-- dashboard/
|-- docs/
|   |-- instalasi.md
|   |-- lisensi.md
|   |-- plugin-system.md
|   |-- sirclo-full-connector.md
|   |-- tutorial-membuat-plugin.md
|   `-- customer-agent-architecture.md
|-- uploads/
`-- storage/logs/

Channel Configuration

Didukung beberapa provider:

Fonnte
Wablas
Meta Cloud API
Twilio
Baileys Bridge
MessageBird
Vonage

Webhook:

POST /api/whatsapp/webhook.php?branch={id}

Aktifkan plugin telegram-channel
Gunakan webhook:

POST /api/channel/webhook.php?channel=telegram

Discord

Aktifkan plugin discord-channel
Gunakan webhook:

POST /api/channel/webhook.php?channel=discord

Channel Custom

Tambahkan lewat implementasi ChannelInterface dan filter channel.registered.

Plugin System

Plugin memungkinkan developer menambah fitur tanpa mengubah kode inti.

Struktur Plugin Minimal

plugins/nama-plugin/
|-- plugin.php
`-- NamaPlugin.php

Hook Penting

Hook	Type	Keterangan
`order.created`	action	Order baru berhasil dibuat
`order.status_changed`	action	Status order berubah
`order.completed`	action	Order selesai
`order.payment_updated`	action	Status bayar berubah
`cart.total`	filter	Modifikasi total harga
`cart.before_checkout`	filter	Validasi sebelum checkout
`chat.message_received`	action	Pesan masuk dari channel manapun
`chat.before_ai`	filter	Sebelum dikirim ke LLM
`chat.after_ai`	filter	Setelah LLM merespons
`llm.providers`	filter	Tambah AI provider custom
`channel.registered`	filter	Tambah channel baru
`dashboard.nav_items`	filter	Tambah menu sidebar

Referensi:

Plugin yang Sudah Tersedia

loyalty-point - loyalty earn/redeem dan dashboard loyalty
customer-crm - normalisasi identitas customer, log CRM, dan notifikasi loyalty ke customer
midtrans-payment - payment gateway Midtrans
xendit-payment - payment gateway Xendit
telegram-channel - channel Telegram
discord-channel - channel Discord
fonnte-whatsapp, twilio-whatsapp, vonage-whatsapp, baileys-whatsapp, messagebird-whatsapp - adapter WhatsApp berbasis plugin
upselling - upsell recommendation
rekomendasi-promo - promo recommendation
cms-berita - branch news/content
notifikasi-admin - helper notifikasi/admin mailer support
themes - pengelolaan tema/tampilan
instagram-dm - integrasi DM Instagram
sirclo-full-connector - fondasi integrasi SIRCLO untuk order, produk, dan customer
anthropic-llm, gemini-llm, openrouter-llm - provider AI tambahan

Plugin diaktifkan lewat __DOC_CODE_0__. Pada state proyek saat ini, loyalty-point dan customer-crm aktif dan saling terhubung.

Integrasi SIRCLO

Proyek ini sekarang memiliki plugin sirclo-full-connector sebagai fondasi integrasi ke SIRCLO.

Cakupan yang sudah tersedia:

pengaturan koneksi per cabang dan global
menu dashboard branch dan super admin untuk monitoring
log sinkronisasi ke tabel sirclo_sync_logs
queue event order untuk created, status_changed, dan payment_updated
snapshot manual untuk sinkronisasi order, produk, dan customer

Penting:

versi saat ini masih scaffold integrasi
request HTTP real ke API SIRCLO belum diimplementasikan
webhook inbound SIRCLO juga belum dibuat

Dokumentasi lengkap:

File utama plugin:

Loyalty Point

Fitur loyalty saat ini mendukung:

earn point otomatis saat order completed
opsi branch untuk hanya memberi poin jika payment paid
cek saldo lewat chatbot: poin saya, cek poin, my points
redeem point lewat chatbot: pakai poin 10, pakai semua poin, hapus poin
redeem point lewat halaman order web
sinkronisasi diskon promo dan loyalty di cart
refund point otomatis saat order dibatalkan
dashboard branch untuk histori member loyalty dan mutasi poin per customer
operasi earn/redeem/refund dibungkus transaksi database agar saldo akun dan ledger tetap konsisten
mutasi loyalty memicu event loyalty.points_changed untuk plugin lain seperti customer-crm

File utama:

Customer CRM

Plugin customer-crm menambahkan lapisan Customer CRM yang fokus pada identitas dan komunikasi loyalty.

Fitur utamanya:

normalisasi customer berbasis email dan WhatsApp
log notifikasi loyalty ke tabel plugin crm_notification_logs
dashboard branch CRM untuk melihat customer, loyalty, order terakhir, dan histori notifikasi
backfill satu kali dari histori loyalty_point_transactions agar CRM tetap punya jejak event lama
schema plugin terpisah di __DOC_CODE_0__

File utama:

Customer Portal

Selain dashboard admin, proyek ini sekarang memiliki Customer Portal self-service.

Alur login:

customer masuk lewat email atau WhatsApp
verifikasi ringan memakai nomor order
session customer dipisah dari session admin

Halaman utama:

Yang bisa dilakukan customer:

cek ringkasan order dan total belanja
cek saldo poin dan histori loyalty
lihat detail order lengkap
ulang order ke cabang asal dari halaman detail
akses dashboard customer langsung dari landing page, halaman chat, dan halaman order

LLM Integration

Konfigurasi lewat dashboard Super Admin.

Provider	Contoh Model
OpenAI	`gpt-4o`, `gpt-4o-mini`
Anthropic	`claude-3-5-haiku`, `claude-3-5-sonnet`
Rule-based	tanpa API key

Provider custom bisa ditambahkan lewat plugin.

API Endpoints

Endpoint	Method	Keterangan
`/api/chat/send.php`	POST	Kirim pesan ke chatbot web
`/api/whatsapp/webhook.php`	POST	Webhook WhatsApp
`/api/channel/webhook.php?channel={name}&branch={id}`	POST	Webhook channel plugin
`/api/cart/add.php`	POST	Tambah item ke cart
`/api/cart/update.php`	POST	Update quantity item
`/api/cart/clear.php`	POST	Kosongkan cart
`/api/loyalty/status.php`	POST	Cek saldo loyalty customer dan status redeem di cart
`/api/loyalty/redeem.php`	POST	Pakai atau batalkan redeem point
`/api/order/checkout.php`	POST	Buat order dari cart
`/api/order/status.php`	GET	Cek status order
`/api/upload/menu.php`	POST	Upload CSV menu
`/api/upload/promo.php`	POST	Upload CSV promo
`/api/export/orders-branch.php`	GET	Export order branch
`/api/export/orders-super.php`	GET	Export order semua cabang

Simulasi Chat

Coba percakapan berikut di /chat.php:

menu
harga latte
promo
pesan 2 latte
cart
ubah latte jadi 1
poin saya
pakai poin 10
hapus poin
checkout

Di halaman order web, redeem point juga bisa dipakai langsung dari panel loyalty saat checkout.

Portal customer juga dapat diakses langsung setelah checkout lewat tombol Dashboard Customer, dengan prefill kontak dan nomor order terakhir.

Regression Check

Untuk cek cepat flow entity extraction dan chatbot tanpa browser, jalankan:

php scripts/chat-regression.php
php scripts/chat-regression.php --verbose
php scripts/chat-regression.php --branch=1

Script ini menguji skenario umum seperti deskripsi menu, query budget, order dengan varian, order dengan hint harga, dan lookup promo.

Dokumentasi

Versi HTML yang bisa dibuka langsung di browser:

Dokumen Markdown sumber:

Keamanan

Password memakai password_hash / password_verify
Query memakai PDO prepared statements
Form dashboard memakai CSRF token
RBAC untuk super_admin dan branch_admin
Branch admin hanya bisa akses data cabangnya
Customer portal hanya bisa membuka data yang cocok dengan sesi customer yang sudah diverifikasi
Credentials disimpan di .env

Kontribusi

Fork repo ini
Buat branch fitur
Commit dengan pesan jelas
Buka Pull Request

Untuk fitur besar, pertimbangkan bentuk plugin agar core tetap bersih.

Lisensi

GNU Affero General Public License v3.0 (AGPL-3.0)

Proyek ini menggunakan model dual license:

AGPL-3.0 untuk penggunaan open source
Commercial License untuk penggunaan proprietary / tertutup yang tidak ingin tunduk pada kewajiban AGPL

Kapan AGPL cocok

kamu membuat fork open source
kamu nyaman membuka source code turunan
kamu menjalankan deployment yang siap memenuhi kewajiban copyleft

Kapan commercial license dibutuhkan

kamu ingin white-label
kamu ingin SaaS proprietary
kamu ingin modifikasi core tetap tertutup
kamu menjual solusi ke klien tanpa membuka source code turunan

Detail lebih lengkap ada di __DOC_CODE_0__.

Untuk commercial inquiry:

Email: kukuhtw@gmail.com
WhatsApp: https://wa.me/628129893706

Catatan: penjelasan ini bersifat praktis untuk proyek dan bukan nasihat hukum formal.

🚀 Features

💻 Tech Stack

☕ Suitable For

Dibuat & Dikembangkan oleh