🏛️ DesaAI: AI-Powered Operating System for Smart Villages

Karya Inovasi Teknologi Desa untuk APTIKOM Hackathon 2026
Kategori: Smart Village Technology

---

📌 Tentang DesaAI

Transformasi digital desa di Indonesia selama ini kerap hanya berfokus pada keberadaan situs web profil desa statis yang pasif. Ketika warga memerlukan informasi surat atau ingin mengadukan kerusakan fasilitas umum, prosesnya masih terfragmentasi melalui antrean fisik atau grup pesan singkat tanpa kepastian tindak lanjut.

DesaAI hadir sebagai AI-Powered Operating System terpadu yang menjembatani masyarakat desa (Citizen) dengan pemerintah desa (Government) melalui siklus pelayanan tertutup (closed-loop workflow):

1. Bukan Sekadar Chatbot: AI dihubungkan langsung ke pipeline pelayanan administrasi dan pelaporan keluhan nyata.
2. Knowledge Base Terverifikasi (RAG): Seluruh jawaban panduan birokrasi mengacu pada dokumen resmi desa (Perdes, SOP layanan, dan profil desa) guna mengeliminasi halusinasi model.
3. AI Complaint Intelligence: Laporan keluhan warga secara otomatis dianalisis, dikelompokkan kategorinya (Infrastruktur, Kebersihan, Keamanan, dll.), dan ditentukan tingkat urgensinya (Emergency, High, Medium, Low) untuk mempermudah triage staf desa.
4. Digital Service Request: Pengajuan surat administrasi mandiri secara digital dengan nomor tiket pelacakan transparan.
5. Government Dashboard & Village Analytics: Dashboard kerja perangkat desa untuk verifikasi berkas, disposisi laporan, serta visualisasi data tren masalah desa berbasis bukti (evidence-based policy).

---

🚀 Fitur Utama

                      ┌────────────────────────────────────────┐
                      │        DesaAI Ecosystem (Web/PWA)      │
                      └───────────────────┬────────────────────┘
                                          │
                  ┌───────────────────────┴───────────────────────┐
                  ▼                                               ▼
     ┌────────────────────────┐                      ┌────────────────────────┐
     │  Citizen Platform      │                      │  Government Dashboard  │
     │  (Warga Desa)          │                      │  (Perangkat Desa)      │
     ├────────────────────────┤                      ├────────────────────────┤
     │ • AI Village Assistant │                      │ • Triage & Disposisi   │
     │   (RAG Grounded SOP)   │                      │ • Verifikasi Surat     │
     │ • Pengajuan Surat      │                      │ • Update Progres Tiket │
     │ • Tracking No. Tiket   │                      │ • Analitik Tren Desa   │
     │ • Lapor Pengaduan      │                      │ • Knowledge Base Admin │
     └────────────┬───────────┘                      └────────────▲───────────┘
                  │                                               │
                  └─────────────► [AI Core Engine] ───────────────┘
                                  - RAG Retrieval
                                  - Intent Classification
                                  - Severity Triage

1. 🤖 AI Village Assistant (RAG Grounded)

Warga dapat berkonsultasi menggunakan bahasa sehari-hari mengenai syarat pengurusan berkas, jam buka kantor desa, dan prosedur administrasi. Jawaban divalidasi langsung dari basis data dokumen resmi desa.

2. 📝 Digital Service Request (Pengajuan Surat Mandiri)

Permohonan surat (Surat Keterangan Domisili, SKU, Pengantar SKCK, SKTM) dapat diajukan secara online dengan upload berkas pendukung dan menerima nomor pelacakan unik (REQ-xxx).

3. 🚨 AI Complaint Intelligence (Pengaduan Cerdas)

Warga melaporkan keluhan fasilitas (contoh: "Lampu jalan di Banjar X mati sejak 3 hari"). Sistem mengekstrak lokasi, mendeteksi kategori masalah, menghitung skor urgensi, dan membuat ringkasan eksekutif secara instan untuk perangkat desa.

4. 📊 Government Dashboard & Village Analytics

Perangkat desa memiliki pusat kendali terintegrasi untuk menyetujui permohonan surat, memperbarui status pengaduan warga, serta melihat analitik sebaran masalah per Banjar/Dusun.

---

🛠️ Tech Stack Modern

• Frontend & Fullstack Framework: TanStack Start (React 19 + TypeScript + Vite)
• Styling & UI: Tailwind CSS v4 + Lucide Icons
• Database & ORM: PostgreSQL 16 + Prisma ORM 7
• AI & RAG Engine: @tanstack/ai + Google Gemini API / LLM Embeddings
• Containerization: Docker & Docker Compose (Multi-platform: Windows & macOS ARM/x86)
• CI/CD & QA: GitHub Actions, ESLint, Commitlint, Husky Git Hooks

---

💻 Panduan Menjalankan Proyek (Quickstart)

Proyek ini telah dikonfigurasi agar berjalan mulus di sistem operasi Windows maupun macOS (termasuk Apple Silicon M1/M2/M3/M4).

Opsi 1: Menggunakan Docker Compose (Direkomendasikan)

Menjalankan seluruh ekosistem (Aplikasi Web + Basis Data PostgreSQL) dalam kontainer:

# 1. Clone repositori
git clone https://github.com/wsantika/desa-ai.git
cd desa-ai

# 2. Siapkan file konfigurasi environment
cp .env.example .env.local

# 3. Jalankan Docker Compose
docker compose up -d --build

# 4. Buka aplikasi di browser
# Web: http://localhost:3000

Opsi 2: Pengembangan Lokal (Hybrid Mode)

Menjalankan database di Docker dan frontend/backend di host laptop untuk kecepatan Vite HMR maksimal:

# 1. Jalankan container database saja
docker compose up -d db

# 2. Salin environment dan generate Prisma client
cp .env.example .env.local
npm run db:generate

# 3. Sinkronisasikan skema database
npm run db:push

# 4. Isi data awal (seed master banjar, layanan, dan RAG embeddings)
npm run db:seed

# 5. Jalankan server pengembangan
npm run dev

---

🤖 Checklist Setup untuk Rekan Tim & AI Agent (Setelah git pull)

Ketika rekan tim atau AI Coding Agent menarik (pull) branch pengembangan terbaru (dev atau feat/*), lakukan langkah-langkah wajib berikut secara berurutan:

# 1. Pastikan Docker / Container Database PostgreSQL Aktif
# PERINGATAN: Jika container mati, aplikasi akan melempar error ECONNREFUSED saat query database!
docker compose up -d db

# 2. Pasang dependensi jika ada penambahan package
npm install

# 3. Pastikan konfigurasi .env.local terisi
# Salin dari .env.example jika belum ada, dan isi GEMINI_API_KEY
cp .env.example .env.local

# 4. GENERATE PRISMA CLIENT (SANGAT PENTING!)
# Folder src/generated/prisma/ ada di .gitignore.
# Setiap developer / AI Agent WAJIB menjalankan ini agar TypeScript dan runtime sinkron.
npm run db:generate

# 5. Sinkronisasi Skema ke Basis Data Lokal
npm run db:push

# 6. Jalankan Database Seed (Wajib untuk Data Awal & RAG Embedding)
# Mengisi master banjar, katalog permohonan surat, user demo, dan vektor embedding dokumen regulasi desa.
npm run db:seed

# 7. Jalankan Automated Test Suite & Linter
npm run test
npm run lint

# 8. Jalankan Server Pengembangan
npm run dev

🌐 Navigasi Halaman Utama

• Portal Pelayanan Warga: http://localhost:3000/
  • Pengaduan Keluhan Fasilitas: http://localhost:3000/pengaduan
  • Permohonan Surat Administrasi: http://localhost:3000/layanan
  • Asisten Cerdas Desa (RAG Chat): http://localhost:3000/asisten
• Meja Kerja Perangkat Desa (Government Dashboard): http://localhost:3000/admin
  • Meja Triage Pengaduan Cepat: http://localhost:3000/admin/pengaduan
  • Verifikasi Berkas Layanan: http://localhost:3000/admin/layanan
  • Analitik Masalah & Sebaran Banjar: http://localhost:3000/admin/analitik
  • Manajemen Regulasi Desa (Knowledge Base): http://localhost:3000/admin/knowledge

📋 Aturan Kerja Kolaborasi AI Agent

1. Target Branch: Selalu buat branch dari dev dan buka Pull Request ke dev. Jangan pernah menargetkan branch master langsung.
2. Atomic Commits: Lakukan commit secara atomik per file (git add <file> && git commit -m "..."). Jangan menggabungkan banyak perubahan file dalam satu commit.
3. Format Pesan Commit: Wajib menggunakan format Conventional Commits (feat: ..., fix: ..., docs: ..., test: ..., refactor: ...).
4. Validasi Kualitas: Wajib memastikan npm run test, npm run lint, dan npm run build berhasil sebelum mem-push kode ke repositori.
5. Standar Antislop: Dilarang menggunakan karakter em dash (ganti dengan titik dua, koma, titik, atau kurung), dan pastikan semua komponen visual memiliki state empty, loading, dan error.

---

🌿 Standar GitFlow & Kolaborasi Tim

Untuk menjaga stabilitas kode menjelang kompetisi hackathon, repositori ini menerapkan aturan percabangan ketat yang divalidasi otomatis oleh GitHub Actions CI:

Struktur Branch

• master : Cabang produksi stabil. Dilarang push langsung. Hanya menerima PR dari branch dev.
• dev : Cabang integrasi utama pengembangan.
• feat/*, fix/*, chore/* : Dibuat dari dev dan WAJIB membuka PR ke target branch dev.

Caution

GitHub Actions CI akan otomatis membatalkan (FAIL) Pull Request yang mencoba menggabungkan branch feat/* langsung ke master.

Format Conventional Commits

Setiap pesan commit dan judul Pull Request wajib mengikuti konvensi:

<type>(<scope>): <pesan dalam huruf kecil>

Contoh yang benar:

• feat(complaint): implement ai classification prompt
• fix(rag): handle empty query response gracefully
• docs(prd): update kpi evaluation criteria

---

📚 Indeks Dokumentasi Lengkap

Dokumentasi arsitektur dan teknis mendalam tersedia di direktori docs/:

• 📄 Product Requirements Document (PRD)
• 🧅 Clean Architecture & Design Principles
• 📐 Arsitektur Sistem, Use Case & Activity Diagram
• 🗄️ Database Schema & ERD
• 🔀 GitFlow, Branching Rules & Conventional Commits
• 🐳 Infrastruktur Docker & Setup Windows/macOS

---

👨‍💻 Tim Pengembang (Undiknas Denpasar)

Karya ini dikembangkan oleh Tim Desa AI dari Universitas Pendidikan Nasional (Undiknas) Denpasar:

1. Benedito Nidio Da Rosa Maia Tilman
2. Kadek Wahyu Santika Putra
3. Renald Kevin Azzaky

APTIKOM Hackathon 2026: Smart Village Technology