docs: fully translate and align v1 README.md structure with v2, implementing premium layout and corporate English style

This commit is contained in:
2026-05-21 17:01:08 +07:00
parent 03c10f91e2
commit 577e385764
+132 -184
View File
@@ -7,150 +7,159 @@
[![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.
A high-performance, secure, and enterprise-ready **Laravel 13** starter kit featuring a comprehensive real-time admin monitoring dashboard, a granular Spatie permission matrix with Blade templates, custom backup services, and ready-to-use Expo React Native mobile application API integration. **Version 1** is designed to provide a highly optimized and rock-solid foundation for business management and SaaS systems.
---
## 🛠️ Tech Stack
## 🚀 Key Architectural Features in v1
| 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) |
* 📊 **Real-time Admin Monitoring** — Dynamic telemetry panel tracking CPU, RAM, Disk usage, and live active users powered by Laravel Reverb WebSockets. Configurable drag-and-drop widget layout is saved per user.
* 🛡️ **Granular Tab-Level Access** — Highly custom authorization gates mapping 85 permission levels for Global Settings and Mobile Remote variables using Blade directives (`@cantab` and `@managetab`).
* ⚙️ **Integrated Control Console** — Unified administration backend governing application branding details, live SMTP servers, OAuth login triggers, automated backups, and maintenance gates.
* 💾 **Secure Backup Automation** — Integrated scheduling mechanisms routing encrypted backups to Cloud storage (Amazon S3 or Google Drive) with custom integrity verification.
* 🤖 **AI Intelligence Engine** — Direct adapters for OpenAI, Gemini, and Mistral, providing automatic Swagger annotations, system diagnostic logs auditing, and real-time security score assessments.
* 📱 **Expo Mobile Application integration** — Native Sanctum API token exchange, dynamic configuration sync, and device token registration endpoints ready for Push Notifications.
---
## ⚡ Fitur Utama
## 🛠️ Tech Stack & Dependencies
* 📊 **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.
| Layer | Technology | Version | Description |
|---|---|---|---|
| **Core Framework** | Laravel | `13.x` | Modern backend routing, scheduler, and service container |
| **Database Engine** | PostgreSQL | `15.x` | Relational database storage |
| **Caching & Queue** | Redis | `Alpine` | High-speed cache memory and asynchronous queues |
| **Real-time Server**| Laravel Reverb | `1.x` | Native high-performance WebSockets broadcaster |
| **Frontend UI** | Blade + SortableJS | `v1.x` | Server-side templating with interactive drag-drop widgets |
| **Authentication** | Breeze + WebAuthn | `v2.x` | Classic web sessions + FIDO2 Biometric Passkeys |
| **Roles & Privileges** | Spatie Permissions | `v6.x` | Granular permission layers mapped to Blade templates |
| **Audit Trail** | Spatie Activity Logs| `v4.x` | Transparent logging for models and user actions |
| **Docs Generator** | Swagger (L5-Swagger) | `v8.x` | OpenAPI spec files with integrated AI assistant |
---
## 🚀 Mulai Cepat (Development)
## 📂 Directory Structure Overview
### Tanpa Docker
This project follows strict clean code practices and Laravel standard modular architectures:
```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
```text
├── app/
│ ├── Exceptions/ # SystemConfig/Backup/Monitoring exception classes
│ ├── Helpers/ # SettingsHelper, SessionHelper, ImpersonateHelper, PasswordRuleHelper
│ ├── Http/
│ │ ├── Controllers/ # AccessControl, Auth, SystemSettings, WebAuthn, Dashboard modules
│ │ ├── Helpers/ # Standardized JSON API responses formats
│ │ └── Middleware/ # SecurityHeaders, IpAccessControl, CheckActivePermission, Gzip
│ ├── Models/ # Primary Eloquent schemas (User, OtpCode, PasswordHistory, DeviceToken)
│ └── Services/ # AI Service adapters, Backup management, SystemConfig caches
├── config/ # Consolidated application parameters
├── database/
│ ├── migrations/ # Database schemas (40+ migrations)
│ └── seeders/ # Dynamic settings, mobile variables, and primary RBAC matrix
├── docker/ # Standardized Sail multi-service docker compose environments
├── public/ # Standard assets (vendor scripts, custom CSS)
├── resources/
│ └── views/ # Server-side Blade layouts, templates, and view components
├── routes/ # Divided routing protocols (web, api, auth, ai, channels, console)
└── tests/ # 371 feature-rich Pest integration tests
```
### Via Docker (Laravel Sail) — Direkomendasikan
---
```bash
./vendor/bin/sail up -d
./vendor/bin/sail artisan migrate --seed
```
## ⚡ Quick Start & Development
Aplikasi dapat diakses di `http://localhost:8000`.
Get your development environment up and running quickly:
### Manual Setup (Without Docker)
1. **Clone & Install Dependencies:**
```bash
git clone <repo-url> Project && cd Project
composer install
npm install
```
2. **Setup Environment Configuration:**
```bash
cp .env.example .env
# Configure your DB_HOST=127.0.0.1 and REDIS_HOST=127.0.0.1 in .env
php artisan key:generate
```
3. **Run Migrations & Seeds:**
```bash
php artisan migrate --seed
```
4. **Launch Development Servers:**
```bash
composer run dev
```
---
### 🔧 Containerized Setup (Laravel Sail) — Recommended
If you prefer using Docker:
1. **Spin Up Containers:**
```bash
./vendor/bin/sail up -d
```
2. **Initialize Database:**
```bash
./vendor/bin/sail artisan migrate --seed
```
The application will be accessible immediately at `http://localhost:8000`.
> [!TIP]
> Jika seeder dijalankan, selalu hapus cache setelahnya agar perubahan muncul di aplikasi:
> Always clear application cache after seeding is completed to reflect settings instantly:
> ```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)
## 🔐 Default Credentials
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` |
| Role | Email | Password | Role Description |
|---|---|---|---|
| **Super Admin** | `superadmin@biiproject.com` | `password` | Unrestricted access. Bypasses all system gates. |
| **Admin** | `admin@biiproject.com` | `password` | Manager privileges for access control, logs, and settings. |
| **User** | `user@biiproject.com` | `password` | Standard user role with read-only dashboard layout. |
> [!IMPORTANT]
> Ganti password segera setelah deploy. Bcrypt 12 rounds + history block aktif by default.
> Please change default passwords immediately after deployment. Bcrypt 12 rounds + history blockers are active by default.
---
## 🛡️ Keamanan Bawaan
## 🛡️ Built-in Security Policies
* **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.
* **Security Headers** — Automatically injected custom headers (`X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy`, `Permissions-Policy`, `X-XSS-Protection`, `Strict-Transport-Security`) protecting all routing responses.
* **Smart Rate Limiting** — Intelligent throttle thresholds applied on `/login`, `/2fa`, `/forgot-password`, `/api/v1/otp/*`, and Expo client login gates.
* **Robust Password Policy** — Dynamic complexity regulations (minimum length, mixed-case, numbers, special characters) with Bcrypt 12 rounds encryption and **365-day history reuse blocker**.
* **IP Access Control** — Customizable administrator Whitelists, global blacklists, and automated burst-block (24 hours) trigger alerting via Telegram.
* **Auto Data Retention** — Dynamic automated pruning pipelines running daily via `model:prune` (expired OTPs/trusted devices, 90-day AI history logs, 48-hour Telescope database entries).
---
## ⚡ Quality Gate
## ⚡ Quality Gate Standards
| Check | Status | Tool |
All components are rigorously audited under continuous quality benchmarks:
| Benchmark | Standard | Auditing 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
```
| **Unit & Feature Tests** | `371 / 371 Passed` | Pest 4 / PHPUnit |
| **Static Code Analysis** | `Clean` | Larastan (Level 5 Baseline) |
| **Code Style Conformity**| `Clean` | Laravel Pint (PSR-12 ruleset) |
| **Dependency Security** | `0 Vulnerabilities` | `composer audit` |
| **Query Performance** | `0 N+1 Regressions` | Pest + Custom Query Logger |
---
## 🔌 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>`.
All endpoints are versioned and situated under `/api/v1/*`. Requests requesting authorization require an HTTP header formatted as `Authorization: Bearer <your_token>`.
### Authentication & Config
| Method | Endpoint | Auth | Description |
@@ -187,99 +196,38 @@ All endpoints listed below are versioned and located under `/api/v1/*`. Requests
---
## 🛠️ Perintah Artisan Khusus
## 🛠️ Specialized Artisan Commands
Sistem ini dilengkapi dengan perintah CLI tambahan untuk memudahkan administrasi:
The administration console provides customized CLI commands for operational workflows:
| Perintah | Deskripsi |
| Command | Description |
|---|---|
| `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. |
| `php artisan system:check` | Audit core infrastructure health (Database, Redis, Cloud Storage, AI engines). |
| `php artisan system:optimize` | Consolidate caches and wipe out production application logs. |
| `php artisan ai:swagger {path}` | Generate automated Swagger controller annotations utilizing OpenAI. |
| `php artisan system:send-digest` | Dispatch weekly operational system health digest to Administrators. |
| `php artisan backups:verify` | Audit and verify the integrity of local/cloud backup files. |
| `php artisan l5-swagger:generate` | Compile and regenerate OpenAPI/Swagger specifications. |
| `php artisan model:prune` | Safely clear out expired OTP keys, passwords histories, and expired device records. |
| `php artisan telescope:prune --hours=48`| Clear out Telescope registry entries older than 48 hours. |
| `php artisan dashboard:broadcast-stats`| Broadcast updated CPU/RAM/Disk stats to the admin monitoring channel. Scheduled minutely. |
---
## 📖 Dokumentasi
## 📖 Related Manuals
| Dokumen | Untuk Siapa | Isi |
| Document | Target Audience | Content |
|---|---|---|
| [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 |
| [README.md](README.md) | All Users | Quick Start & Architectural Overview (This file) |
| [USER_GUIDE.md](USER_GUIDE.md) | Administrators | Operational guidelines for the administrative panel |
| [TECH_STACK.md](TECH_STACK.md) | Developers | Architectural dependencies, CI pipelines, and plugins details |
| [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) | DevOps Engineers | Outlines production environment server deployments |
| [SECURITY.md](SECURITY.md) | All Users | Security policies and reporting protocols |
| [CHANGELOG.md](CHANGELOG.md) | All Users | Versioned repository changes log |
| [mobile/README.md](mobile/README.md) | Mobile Engineers | Outline and instructions for React Native/Expo builds |
---
## 📂 Struktur Direktori
## 📄 License & Terms
```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**.
Proprietary © 2026 Andika Debi Putra (Debesocial). Designed and packaged to expedite development while aligning with modern security and architectural guidelines (Compliant with **UU PDP No. 27/2022**). All rights reserved.