From 577e385764d2a7b8fda5732a97251d0b6d174391 Mon Sep 17 00:00:00 2001 From: debesocial Date: Thu, 21 May 2026 17:01:08 +0700 Subject: [PATCH] docs: fully translate and align v1 README.md structure with v2, implementing premium layout and corporate English style --- README.md | 316 +++++++++++++++++++++++------------------------------- 1 file changed, 132 insertions(+), 184 deletions(-) diff --git a/README.md b/README.md index 3c53e24..15219e6 100644 --- a/README.md +++ b/README.md @@ -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 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 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 `. +All endpoints are versioned and situated under `/api/v1/*`. Requests requesting authorization require an HTTP header formatted as `Authorization: Bearer `. ### 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.