🧠 Custora

• Deskripsi Singkat Proyek
• Fitur Utama
• Tautan Model dan Sumber Daya
• Petunjuk Setup Environment
• Cara Menjalankan Aplikasi
• Petunjuk Penggunaan
• Struktur Proyek
• Tech Stack
• Pemecahan Masalah (Troubleshooting)
• Informasi Penting Lainnya
• Penutup

Custora adalah platform analitik retensi pelanggan yang ditenagai oleh kecerdasan buatan (AI). Platform ini dirancang untuk membantu bisnis dalam:

• Mengidentifikasi pelanggan yang berisiko tinggi melakukan churn (berhenti berlangganan).
• Memahami sentimen pelanggan berdasarkan ulasan dan umpan balik yang diberikan.
• Mendapatkan rekomendasi aksi retensi yang konkret dan dapat ditindaklanjuti, yang dihasilkan secara otomatis oleh AI.

Dengan Custora, tim bisnis dapat mengambil keputusan berbasis data untuk meningkatkan loyalitas pelanggan dan mengurangi tingkat churn secara efektif.

Custora menggunakan dua jenis model AI:

1. Model LLM (Qwen oleh Alibaba Cloud) — Digunakan untuk fitur rekomendasi retensi AI. Model ini diakses melalui Alibaba Cloud DashScope API, sehingga tidak perlu diunduh atau dijalankan secara lokal. Cukup buat API key di DashScope, lalu masukkan ke dalam berkas .env.local.

2. Model Churn Prediction (Machine Learning) — Proses scoring churn dijalankan melalui ML API yang sudah di-deploy di Azure Container Apps. Dokumentasi endpoint API tersedia pada tautan di bawah.

• Model LLM (Qwen): Tidak perlu mengunduh model secara manual. Cukup atur variabel ALIBABA_CLOUD_API_KEY di berkas .env.local, dan aplikasi akan otomatis terhubung ke API DashScope.
• Model Churn Prediction: Model dijalankan melalui ML API yang sudah di-deploy. Atur variabel ML_API_URL di berkas .env.local agar mengarah ke endpoint API yang aktif.
• Notebook Pelatihan: Jika ingin melatih ulang model, buka tautan Google Colab di atas dan ikuti instruksi di dalam notebook.

Pastikan perangkat lunak berikut sudah terpasang di komputer Anda:

• Node.js versi 18 atau lebih baru — Unduh di sini
• npm versi 9 atau lebih baru (sudah termasuk saat memasang Node.js)
• Git — Unduh di sini

Selain itu, Anda juga memerlukan akun pada layanan berikut:

• Supabase — Untuk basis data dan autentikasi (tersedia paket gratis).
• Alibaba Cloud DashScope — Untuk mengakses model AI Qwen (diperlukan untuk fitur rekomendasi retensi).

git clone https://github.com/zickrian/Custora.git
cd Custora

npm install

Perintah ini akan memasang seluruh paket yang dibutuhkan sesuai dengan berkas package.json.

Salin berkas template environment:

cp .env.example .env.local

Kemudian buka berkas .env.local menggunakan editor teks pilihan Anda, lalu isi variabel yang dibutuhkan:

# -----------------------------------------------
# Supabase (Wajib)
# Dapatkan dari: https://supabase.com/dashboard → Project Settings → API
# -----------------------------------------------
NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_ANON_KEY=<anon-key>
SUPABASE_SERVICE_ROLE_KEY=<service-role-key>

# -----------------------------------------------
# Alibaba Cloud DashScope (Wajib untuk fitur AI)
# Dapatkan dari: https://dashscope.aliyun.com
# -----------------------------------------------
ALIBABA_CLOUD_API_KEY=<api-key>
ALIBABA_CLOUD_MODEL_FALLBACKS=qwen3.5-122b-a10b,qwen3-max,qwen-plus

# -----------------------------------------------
# ML API (Opsional — untuk fitur churn prediction)
# Jika tidak diisi, scoring akan menggunakan heuristik lokal.
# -----------------------------------------------
ML_API_URL=https://custora-ml-api.redpebble-35acc587.southeastasia.azurecontainerapps.io

💡 Catatan: Lihat berkas .env.example untuk daftar lengkap variabel beserta penjelasan masing-masing. Jangan pernah meng-commit berkas .env.local ke version control.

Jalankan migrasi basis data menggunakan Supabase CLI:

npx supabase db push

Alternatif: Jika tidak menggunakan Supabase CLI, Anda juga dapat menjalankan berkas SQL yang terdapat di folder supabase/migrations/ secara berurutan melalui Supabase Dashboard → SQL Editor.

Jalankan perintah berikut untuk memulai server pengembangan:

npm run dev

Setelah server berhasil berjalan, buka alamat berikut di peramban (browser) Anda:

http://localhost:3000

Aplikasi akan dimuat ulang secara otomatis setiap kali Anda menyimpan perubahan pada kode sumber.

Untuk membangun dan menjalankan versi produksi:

# Membangun (build) aplikasi
npm run build

# Menjalankan server produksi
npm run start

Untuk menjalankan pemeriksaan linting pada kode sumber:

npm run lint

Berikut adalah panduan singkat cara menggunakan fitur-fitur utama Custora:

• Buka aplikasi di peramban (http://localhost:3000).
• Anda akan diarahkan ke halaman Login.
• Masuk menggunakan akun yang telah terdaftar melalui Supabase Auth.

• Navigasikan ke menu Pusat Data (Data Hub) pada sidebar.
• Klik tombol unggah dan pilih berkas CSV yang berisi data pelanggan Anda.
• Sistem akan memproses dan menyimpan data ke dalam basis data.

• Halaman utama (Dashboard) menampilkan ringkasan metrik retensi pelanggan.
• Grafik dan statistik akan diperbarui secara otomatis berdasarkan data yang telah diunggah.

• Buka menu Skor Risiko Churn pada sidebar.
• Sistem akan menampilkan daftar pelanggan beserta skor risiko churn masing-masing.
• Pelanggan dengan skor risiko tinggi ditandai secara visual agar mudah diidentifikasi.

• Buka menu Analisis Sentimen pada sidebar.
• Sistem akan menampilkan hasil analisis sentimen dari ulasan atau umpan balik pelanggan.

• Buka menu Rekomendasi Retensi AI pada sidebar.
• AI (Qwen) akan menghasilkan rekomendasi aksi retensi yang dapat ditindaklanjuti berdasarkan data pelanggan Anda.

• Buka menu Laporan pada sidebar.
• Pilih format ekspor yang diinginkan (PDF atau CSV).
• Berkas laporan akan diunduh secara otomatis ke komputer Anda.

custora/
├── src/
│   ├── app/                         # Next.js App Router
│   │   ├── (dashboard)/             # Halaman utama (dilindungi autentikasi)
│   │   ├── ai-recommendations/      # Halaman rekomendasi retensi AI
│   │   ├── churn-risk/              # Halaman skor risiko churn
│   │   ├── sentiment-analysis/      # Halaman analisis sentimen
│   │   ├── data-hub/                # Halaman unggah & manajemen dataset
│   │   ├── reports/                 # Halaman laporan & ekspor
│   │   ├── segments/                # Halaman segmentasi pelanggan
│   │   ├── settings/                # Halaman pengaturan
│   │   ├── api/                     # API Routes (sisi server)
│   │   │   ├── ai-retention-analysis/  # Endpoint analisis retensi AI
│   │   │   ├── analytics/              # Endpoint analitik
│   │   │   ├── datasets/               # Endpoint dataset
│   │   │   ├── notifications/          # Endpoint notifikasi
│   │   │   └── reports/                # Endpoint laporan
│   │   ├── login/                   # Halaman login
│   │   └── auth/                    # Callback autentikasi (Supabase)
│   ├── components/                  # Komponen React yang dapat digunakan ulang
│   │   ├── auth/                    # Komponen terkait autentikasi
│   │   ├── core/                    # Komponen inti (layout, sidebar, dll.)
│   │   └── dashboard/               # Komponen khusus dashboard
│   ├── lib/                         # Utilitas dan konfigurasi
│   │   ├── supabase/                # Konfigurasi klien Supabase
│   │   └── custora/                 # Logika bisnis Custora
│   └── assets/                      # Aset statis (ikon, gambar, dll.)
├── supabase/
│   └── migrations/                  # Berkas migrasi SQL basis data
├── machine learning/
│   └── datasets/                    # Dataset sampel untuk pelatihan model
├── public/                          # Berkas publik (favicon, gambar statis)
├── .env.example                     # Template variabel lingkungan
├── next.config.ts                   # Konfigurasi Next.js
├── tsconfig.json                    # Konfigurasi TypeScript
├── package.json                     # Daftar dependensi dan skrip proyek
└── eslint.config.mjs                # Konfigurasi linting ESLint

• Jangan pernah meng-commit berkas .env.local ke repository. Berkas ini sudah tercantum di .gitignore.
• Variabel dengan awalan NEXT_PUBLIC_ akan terekspos ke sisi klien (browser). Pastikan hanya memasukkan nilai yang memang boleh diakses publik.
• SUPABASE_SERVICE_ROLE_KEY memiliki akses penuh ke basis data. Jangan gunakan awalan NEXT_PUBLIC_ untuk variabel ini.

Model AI yang digunakan dalam aplikasi ini diperoleh dari Alibaba Cloud melalui layanan DashScope API dengan model Qwen. API key dapat diperoleh secara langsung di dashboard DashScope.

Di dalam folder machine learning/datasets/, tersedia beberapa dataset sampel yang dapat digunakan untuk pengujian:

Custora dikembangkan sebagai proyek Capstone dengan tujuan memberikan solusi nyata bagi pelaku bisnis dalam mengelola retensi pelanggan secara efektif. Dengan menggabungkan teknologi web modern dan kecerdasan buatan, platform ini diharapkan dapat menjadi alat bantu yang bermanfaat untuk memahami perilaku pelanggan, memprediksi risiko churn, dan mengambil langkah retensi yang tepat sasaran.

Dokumentasi ini disusun agar siapa pun dapat memasang, menjalankan, dan memahami keseluruhan sistem Custora dengan mudah.