# ⚡ biiproject-kit v1

[![Laravel](https://img.shields.io/badge/Laravel-13.x-FF2D20?style=for-the-badge&logo=laravel)](https://laravel.com)
[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-15-4169E1?style=for-the-badge&logo=postgresql)](https://www.postgresql.org)
[![Redis](https://img.shields.io/badge/Redis-Alpine-DC382D?style=for-the-badge&logo=redis)](https://redis.io)
[![Tests](https://img.shields.io/badge/Tests-371%20Passed-31C653?style=for-the-badge)]()
[![Pint](https://img.shields.io/badge/Pint-Clean-007ACC?style=for-the-badge)]()
[![Larastan](https://img.shields.io/badge/Larastan-Level%205-blue?style=for-the-badge)]()

Aplikasi web manajemen bisnis berbasis **Laravel 13** dengan PostgreSQL, Redis, dan WebSocket real-time. Didesain secara tangguh, kaya fitur keamanan bawaan, dan diintegrasikan dengan AI Intelligence Engine.

---

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| **Backend** | Laravel 13.x (PHP 8.3+) with PostgreSQL & Redis |
| **Real-time Engine** | Laravel Reverb (WebSockets for real-time monitoring and widgets) |
| **Frontend** | Vanilla CSS, Blade Templates, SortableJS (Drag-and-drop dashboard) |
| **Authentication** | Breeze (Session) + Sanctum (API) + Passkeys (WebAuthn FIDO2) + OAuth |
| **RBAC** | `spatie/laravel-permission` (Granular 85 tab levels matrix) |
| **System Audit** | `spatie/laravel-activitylog` + Custom Action Logs |
| **Interactive API Docs**| `l5-swagger` (OpenAPI Swagger with AI Assistant) |

---

## ⚡ Fitur Utama

* 📊 **Dashboard Admin Real-time** — ringkasan CPU/RAM/Disk/Live Users/Queue dengan update via WebSocket (Reverb). Widget bisa disembunyikan, diurutkan ulang (drag), dan disimpan per-user. Fallback ke polling 30 detik jika Reverb tidak terhubung.
* 🧩 **Custom Dashboard Widgets** — 7 widget bawaan (cpu, ram, disk, live users, queues, activity feed, AI insight). Per-user layout tersimpan di `dashboard_widget_preferences`. Toggle show/hide + drag-to-reorder via SortableJS.
* 👤 **Manajemen Pengguna** — role & permission granular (Spatie), soft delete + restore + force delete, bulk action.
* ⚙️ **Global Settings** — branding, keamanan, email, AI, SAP, backup, dan lainnya dalam satu panel.
* 📱 **Mobile Settings** — kontrol remote konfigurasi aplikasi Android/iOS.
* 🚧 **Maintenance Mode** — offline page dengan countdown, bypass key, dan IP whitelist.
* 💾 **Backup & Restore** — Local, Amazon S3, atau Google Drive dengan enkripsi opsional.
* 🩺 **System Monitoring** — log Laravel, log SAP, log mobile, background job, AI usage, health check.
* 📢 **Notifikasi Real-time** — WebSocket via Laravel Reverb + Notification Center. Dashboard stats di-push tiap menit via `dashboard:broadcast-stats`.
* 🛡️ **Granular Tab Permissions** — 85 permission level tab untuk Global/Mobile Settings. `CheckTabPermission` middleware + `@cantab`/`@managetab` Blade directives. Picker role dengan UI two-panel drag-drop dan category headers.
* 🔌 **Session Manager** — lihat & paksa logout sesi aktif, single-session enforcement opsional.
* ⚖️ **Legal & Content** — Privacy Policy, ToS, About (WYSIWYG), kepatuhan UU PDP No. 27/2022.
* 📱 **Mobile App** — React Native + Expo dengan API Sanctum, OTP, device token (push notification).
* 🪵 **Audit Trail** — semua perubahan tercatat via Spatie ActivityLog + Action Log.
* 🚨 **Error Monitoring** — Sentry integration untuk production error tracking.
* 🔑 **Passkeys (WebAuthn)** — login biometrik/FIDO2.
* 🤝 **Social OAuth** — Google, Facebook, GitHub (callback aman terhadap identity-overwrite).
* 🤖 **AI Intelligence Engine** — Integrasi OpenAI, Gemini, Claude, DeepSeek, Mistral, dll.
* 🔍 **Smart Search (CMD+K)** — Navigasi cerdas & AI Assistant terintegrasi.
* 🛡️ **AI Security Audit** — Skor keamanan otomatis & rekomendasi perkuatan (hardening).
* 🩺 **AI Error Diagnostics** — Analisis otomatis & saran perbaikan saat terjadi error sistem.
* 📘 **API Documentation** — Swagger/OpenAPI otomatis (l5-swagger) dengan bantuan AI.

---

## 🚀 Mulai Cepat (Development)

### Tanpa Docker

```bash
# 1. Clone & install
git clone <repo-url> Project && cd Project
composer install
npm install

# 2. Environment
cp .env.example .env
# Edit .env: DB_HOST=127.0.0.1, REDIS_HOST=127.0.0.1
php artisan key:generate

# 3. Database & seed
php artisan migrate --seed

# 4. Jalankan (server + vite + reverb + queue + scheduler)
composer run dev
```

### Via Docker (Laravel Sail) — Direkomendasikan

```bash
./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate --seed
```

Aplikasi dapat diakses di `http://localhost:8000`.

> [!TIP]
> Jika seeder dijalankan, selalu hapus cache setelahnya agar perubahan muncul di aplikasi:
> ```bash
> ./vendor/bin/sail artisan cache:clear
> ```

### Menjalankan Test Suite

```bash
./vendor/bin/sail artisan test                 # 371 tests (full)
./vendor/bin/sail artisan test --filter Auth   # filter
./vendor/bin/sail bin phpstan analyse          # static analysis
./vendor/bin/sail bin pint --test              # code style check
./vendor/bin/sail bin pint                     # code style auto-fix
```

---

## 🔐 Akun Default (Setelah Seed)

Use the default credentials below to test the RBAC capabilities of the starter kit:

| Role | Email | Password |
|---|---|---|
| **Super Admin** | `superadmin@biiproject.com` | `password` |
| **Admin** | `admin@biiproject.com` | `password` |
| **User** | `user@biiproject.com` | `password` |

> [!IMPORTANT]
> Ganti password segera setelah deploy. Bcrypt 12 rounds + history block aktif by default.

---

## 🛡️ Keamanan Bawaan

* **Security Headers**: `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`, `X-XSS-Protection`, dan `Strict-Transport-Security` (HTTPS) di-set otomatis oleh middleware global.
* **Rate Limiting**: throttle pada `/login`, `/2fa`, `/forgot-password`, `/api/v1/otp/*`, dan endpoint mobile lain. Per-IP bucket terisolasi.
* **Password Policy**: panjang min/max, charset wajib, expiry, dan **history reuse blocker** (Bcrypt 12 rounds).
* **IP Access Control**: whitelist admin, blacklist global, auto-block on burst (24 jam) dengan alert Telegram.
* **Data Integrity**: FK constraint penuh di semua tabel audit; soft-delete cascade tested.
* **Data Retention Otomatis**: 10 tabel/model memiliki kebijakan retensi — OTP & trusted device dipangkas saat expired, log AI & healing 90 hari, password history 365 hari, Telescope 48 jam. Dijalankan via `model:prune` + `telescope:prune` setiap dini hari.

---

## ⚡ Quality Gate

| Check | Status | Tool |
|---|---|---|
| Unit & feature tests | **371 / 371 ✓** | Pest 4 |
| Static analysis | **clean** | Larastan level 5 (baseline) |
| Code style | **clean** | Laravel Pint (PSR-12) |
| Dependency audit | **0 vulns** | `composer audit` |
| N+1 regression locks | **3 datatables** | Pest + Query Log |

CI menjalankan keempatnya di setiap push/PR — lihat [`.github/workflows/ci.yml`](.github/workflows/ci.yml).

```bash
./vendor/bin/sail artisan test
./vendor/bin/sail bin phpstan analyse
./vendor/bin/sail bin pint --test
./vendor/bin/sail composer audit
```

---

## 🔌 API Endpoints Reference (v1)

All endpoints listed below are versioned and located under `/api/v1/*`. Requests requesting authorization require a header formatted as `Authorization: Bearer <your_token>`.

### Authentication & Config
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/api/v1/login` | — | Exchange credentials for Bearer Token (Rate limited) |
| `POST` | `/api/v1/register` | — | Register a new user account (Rate limited) |
| `POST` | `/api/v1/forgot-password`| — | Request reset password link |
| `GET` | `/api/v1/app-config` | — | Retrieve mobile app remote configuration parameters |
| `GET` | `/api/v1/mobile/sync` | — | Sync latest configurations and updates |
| `POST` | `/api/v1/mobile/log` | — | Send mobile application logs to server (Rate limited) |

### OTP Gateway
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/api/v1/otp/send` | — | Request verification OTP code via Email/WhatsApp (Rate limited) |
| `POST` | `/api/v1/otp/verify` | — | Validate the OTP code |

### Profile & Dashboard (Authenticated)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/api/v1/user` | Bearer | Fetch authenticated user data, roles, and permissions |
| `POST` | `/api/v1/logout` | Bearer | Revoke current authenticated session token |
| `POST` | `/api/v1/profile/update` | Bearer | Update user profile personal details |
| `POST` | `/api/v1/profile/avatar` | Bearer | Upload and update profile photo |
| `POST` | `/api/v1/profile/password` | Bearer | Change account login password |
| `DELETE` | `/api/v1/profile/delete` | Bearer | Self account termination/deletion |
| `GET` | `/api/v1/dashboard` | Bearer | Retrieve secure mobile dashboard analytics |

### Push Notification Registry
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/api/v1/devices/register` | Bearer | Register target FCM device token |
| `DELETE`| `/api/v1/devices/unregister`| Bearer | Revoke and unregister FCM device token |

---

## 🛠️ Perintah Artisan Khusus

Sistem ini dilengkapi dengan perintah CLI tambahan untuk memudahkan administrasi:

| Perintah | Deskripsi |
|---|---|
| `php artisan system:check` | Audit kesehatan infrastruktur (DB, Redis, Storage, AI). |
| `php artisan system:optimize` | Optimasi cache & pembersihan log produksi. |
| `php artisan ai:swagger {path}` | Menghasilkan anotasi Swagger otomatis menggunakan AI. |
| `php artisan system:send-digest` | Mengirim ringkasan kesehatan sistem mingguan ke Admin. |
| `php artisan backups:verify` | Verifikasi integritas file cadangan di cloud/lokal. |
| `php artisan l5-swagger:generate` | Regenerasi dokumentasi API OpenAPI. |
| `php artisan model:prune` | Pangkas data kedaluwarsa (OTP, trusted device, AI log, password history, dll). |
| `php artisan telescope:prune --hours=48` | Hapus Telescope entries lebih dari 48 jam. |
| `php artisan dashboard:broadcast-stats` | Broadcast statistik sistem terbaru ke channel WebSocket `admin.monitoring`. Dijadwalkan tiap menit. |

---

## 📖 Dokumentasi

| Dokumen | Untuk Siapa | Isi |
|---|---|---|
| [README.md](README.md) | Semua | Ringkasan & quick start (file ini) |
| [USER_GUIDE.md](USER_GUIDE.md) | Admin / Operator | Cara pakai panel admin |
| [TECH_STACK.md](TECH_STACK.md) | Developer | Framework, library, plugin, tooling, CI |
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | DevOps | Instalasi server produksi |
| [SECURITY.md](SECURITY.md) | Semua | Reporting & supply-chain advisory |
| [CHANGELOG.md](CHANGELOG.md) | Semua | Log perubahan |
| [mobile/README.md](mobile/README.md) | Mobile Dev | Build & pengembangan aplikasi Android/iOS |

---

## 📂 Struktur Direktori

```text
Project/
├── app/
│   ├── Exceptions/                 # SystemConfig/Backup/Monitoring exception classes
│   ├── Helpers/                    # SettingsHelper, SessionHelper, ImpersonateHelper, PasswordRuleHelper
│   ├── Http/
│   │   ├── Controllers/
│   │   │   ├── AccessControl/      # User, Role, Permission, ActionLog management
│   │   │   ├── Admin/              # Mobile settings
│   │   │   ├── Api/                # Sanctum-protected mobile API (v1) + Health
│   │   │   ├── Auth/               # Login, 2FA, Passkey (WebAuthn), Social OAuth
│   │   │   ├── SystemSettings/     # Global settings, monitoring, backup, maintenance
│   │   │   ├── WebAuthn/           # Laragear WebAuthn login/register controllers
│   │   │   ├── DashboardController.php
│   │   │   ├── ImpersonateController.php
│   │   │   ├── LegalController.php
│   │   │   └── ProfileController.php
│   │   ├── Helpers/                # ApiResponse
│   │   └── Middleware/             # SecurityHeaders, IpAccessControl, CheckActivePermission,
│   │                               # CheckLegalAgreement, PasswordExpiry, GzipCompression
│   ├── Services/
│   │   ├── Auth/                   # PasswordPolicyService
│   │   ├── AI/                     # Multi-provider AI service abstraction
│   │   ├── MobileConfig/           # MobileConfigService (admin → mobile sync)
│   │   ├── Monitoring/             # SystemMonitoringService + MonitoringFormatter
│   │   ├── Notification/           # FCM, Telegram adapters
│   │   ├── System/                 # BackupManagementService, MaintenanceManagementService,
│   │   │                           # ActivityFormatter, GlobalSearchService
│   │   └── SystemConfig/           # SystemConfigService + SettingDefinitions +
│   │                               # SettingValueCaster + SettingFileUploader
│   └── Models/                     # User, Role, Permission, SystemSetting (+ Revision),
│                                   # MobileSetting, OtpCode, PasswordHistory, DeviceToken,
│                                   # DashboardWidgetPreference, ...
├── config/                         # Konfigurasi Laravel
├── database/
│   ├── migrations/                 # Skema database (40+ tabel)
│   └── seeders/                    # RoleAndPermission, SystemSetting, MobileSetting, AdminUser
├── docker/                         # Konfigurasi Sail (PHP, Postgres, Redis)
├── mobile/                         # Aplikasi React Native (Expo SDK 54+)
├── resources/views/                # Template Blade
├── routes/
│   ├── web.php                     # Rute web (admin panel)
│   ├── api.php                     # Rute API mobile (prefix /api/v1)
│   ├── auth.php                    # Rute autentikasi Breeze + 2FA + WebAuthn
│   ├── ai.php                      # Endpoint AI assistant
│   ├── channels.php                # Broadcast channel auth
│   └── console.php                 # Schedule kernel
├── storage/api-docs/               # Generated OpenAPI/Swagger spec
├── storage/logs/                   # File log aplikasi
├── tests/
│   ├── Feature/                    # HTTP + integration tests
│   └── Unit/                       # Pure logic (Formatter, Caster, Helpers, Exceptions)
├── phpstan.neon                    # Larastan config (level 5)
├── phpstan-baseline.neon           # Pre-existing errors silenced
└── .github/workflows/ci.yml        # Test + Lint + Static Analysis pipeline
```

---

## 📄 Lisensi & Ketentuan

Proprietary © 2026 Andika Debi Putra. Lihat header tiap file. Dirancang dengan kepatuhan terhadap **UU PDP No. 27/2022**.