# GEMINI.md — gsbhub Project Brain

## 1. Identitas Proyek
- **Nama Aplikasi:** `gsbhub` (Sistem Informasi Keuangan & Kegiatan Rukun Tetangga)
- **Domain Live:** `https://gsb.celconindonesia.com`
- **Lokasi Workspace:** `\\192.168.1.99\htdocs\gsb` (`Z:\gsb` di PC Rumah / `C:\xampp\htdocs\gsb` di Server Kantor)
- **Stack Server Terverifikasi:** XAMPP Windows — **PHP Native `8.2.12`** (tanpa framework berat/Laravel/Composer bloat), MariaDB `10.4.32` (database baru **`gsbhub_db`** dibangun dari nol), Apache vhost port `8080` (`AllowOverride All`, `DocumentRoot "C:/xampp/htdocs/gsb"`).

## 2. Aturan Anti-Halusinasi & Cara Kerja AI
1. **Straight to the Point:** Jawab ringkas, teknis, jelas, tanpa basa-basi berlebih.
2. **Verifikasi Wajib (No Guessing):** Dilarang menyebut nama file, fungsi, tabel, kolom DB, atau status berhasil tanpa benar-benar membaca file / menjalankan perintah verifikasi di sesi aktif.
3. **Eksekusi Server via SSH:** Semua perintah PHP CLI (`C:\xampp\php\php.exe`) dan MariaDB CLI (`C:\xampp\mysql\bin\mysql.exe`) WAJIB dijalankan via `ssh server-kantor "..."`, bukan di PC lokal.
4. **Proaktif & Adaptif:** Berikan rekomendasi arsitektur/UX terbaik secara singkat bila ada opsi, jelaskan alasannya, dan siap merevisi cepat sesuai arahan user.
5. **Sinkronisasi Dokumen Wajib:**
   - Di awal sesi/tugas: baca `PROGRESS.md` (dan `docs/RECOMMENDATIONS.md` bila relevan).
   - Di akhir setiap perubahan fitur/perbaikan: update `PROGRESS.md` dan `CHANGELOG.md`.

## 3. Arsitektur Modular (`module/`) & God-Level Security
- **Isolasi Modul:** Setiap fitur bisnis wajib diinkubasi di dalam foldernya sendiri di `module/<nama_modul>/` (contoh: `module/auth/`, `module/dashboard/`, `module/warga/`, `module/iuran/`, `module/kas/`, `module/superadmin/`).
- **Zero Direct Web Access:**
  - Root `.htaccess` dan `module/.htaccess` WAJIB memblokir akses HTTP langsung (`403 Forbidden`) ke `module/`, `app/`, `config/`, `database/`, `docs/`, `storage/`, `tools/`, `.agents/`, `.git/`, `.env`, `*.md`, `*.sql`, `*.log`.
  - Satu-satunya entry point publik adalah `public/index.php` (mendefinisikan konstanta `GSBHUB_APP`).
  - Setiap file `.php` di dalam `app/`, `module/`, dan `config/` WAJIB diawali guard:
    `defined('GSBHUB_APP') or (http_response_code(403) && exit('Forbidden'));`
- **Anti-LFI / Strict Route Registry:** Dilarang melakukan `include`/`require` dinamis dari parameter user (`$_GET`/`$_POST`). Semua route modul didaftarkan eksplisit lewat `module/<nama>/routes.php` dan whitelist modul aktif.
- **Database & Auth Hardening:**
  - PDO (`utf8mb4`, `ATTR_ERRMODE => ERRMODE_EXCEPTION`, `ATTR_EMULATE_PREPARES => false`), 100% prepared statements.
  - Operasi multi-tabel (pembayaran iuran, pemasukan lain, pengeluaran) wajib dibungkus `beginTransaction()` / `commit()` / `rollBack()`.
  - `password_hash()` / `password_verify()`, brute-force rate limiter pada `module/auth`, CSRF token (`hash_equals`) pada semua `POST`/`PUT`/`DELETE`, `session_regenerate_id(true)` saat login/ubah privilege, cookie `httponly` + `samesite=Lax` + `use_strict_mode=1`, Security Headers (`CSP`, `X-Frame-Options: DENY`, `X-Content-Type-Options: nosniff`), serta `htmlspecialchars(..., ENT_QUOTES, 'UTF-8')`.
  - File upload (jika ada) wajib validasi magic bytes (`finfo`), rename acak, simpan di `storage/uploads/` (eksekusi PHP dimatikan via `.htaccess`), dan disajikan lewat controller terotorisasi.

## 4. Matriks Role & Alur Bisnis Inti
Aplikasi memiliki 3 role dengan otorisasi ketat di level server (middleware + controller):
- **`superadmin`**:
  - Akses penuh ke seluruh fitur sistem, pengaturan RT, dan audit log.
  - Dapat melakukan seluruh tugas `admin`.
  - **Eksklusif:** Mengubah status/role akun (`user` <-> `admin`, aktif/nonaktif), mengelola akun admin.
- **`admin`**:
  - Mengelola data warga & jenis iuran.
  - Menginput pembayaran iuran warga, pemasukan lain-lain, dan pengeluaran kas RT.
  - Memantau seluruh laporan kas, tunggakan, dan rekap iuran.
  - Dilarang mengubah role/status `admin` lain atau `superadmin`.
- **`user` (Warga)**:
  - Memantau laporan keuangan RT secara transparan: pemasukan iuran, pemasukan lain, pengeluaran, dan saldo kas real-time.
  - Melihat **laporan iuran pribadi** yang otomatis terintegrasi dari input admin (status lunas/belum bayar per periode, riwayat transaksi, rincian bayar).
  - Read-only pada data keuangan (tidak bisa edit/hapus transaksi).

## 5. Prinsip UI/UX (Enterprise Mobile-First + Desktop-Ready)
- **Mobile-First Primary (`360px–430px`):** Desain ala modern fintech/enterprise SaaS yang nyaman satu tangan: sticky compact header, bottom navigation bar dengan icon outline/filled, bottom-sheet modal untuk aksi cepat admin, card-list responsif tanpa scroll horizontal, dan PWA-ready (`manifest.webmanifest`).
- **Desktop-Ready (`>= 1024px`):** Beradaptasi rapi menjadi sidebar navigasi kiri + grid dashboard lega dengan `max-width` terkontrol.
- **Self-Hosted Premium Assets:** Prioritaskan aset lokal di `public/assets/` (Tailwind CSS compiled, Alpine.js, Phosphor/Lucide SVG sprite, Plus Jakarta Sans + Inter, ApexCharts/Chart.js) agar cepat, tahan offline/CDN lag, dan kompatibel dengan CSP ketat.

## 6. Project Skills (`.agents/skills/`)
Aktifkan skill sesuai konteks pekerjaan:
- `gsbhub-php-security`: Arsitektur modular `module/`, proteksi `.htaccess`, runtime guard, CSRF, rate limit, CSP, RBAC.
- `gsbhub-ui-mobile-first`: Standar UI/UX enterprise mobile-first, aset frontend lokal, bottom-nav/bottom-sheet, format angka.
- `gsbhub-db-workflow`: Desain skema MariaDB 10.4, transaksi atomic kas/iuran, perintah DB via `ssh server-kantor`.
- `gsbhub-session-sync`: Verifikasi akhir (`php -l`, cek DB, cek HTTP/browser) & update `PROGRESS.md` + `CHANGELOG.md`.