biiproject-kit-v1/README.md

⚡ biiproject-kit v1

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.

---

🚀 Key Architectural Features in v1

• 📊 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.

---

🛠️ Tech Stack & Dependencies

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

---

📂 Directory Structure Overview

This project follows strict clean code practices and Laravel standard modular architectures:

├── 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

---

⚡ Quick Start & Development

Get your development environment up and running quickly:

Manual Setup (Without Docker)

1. Clone & Install Dependencies:

   git clone <repo-url> Project && cd Project
   composer install
   npm install
   

2. Setup Environment Configuration:

   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:

   php artisan migrate --seed
   

4. Launch Development Servers:

   composer run dev
   

---

🔧 Containerized Setup (Laravel Sail) — Recommended

If you prefer using Docker:

1. Spin Up Containers:

   ./vendor/bin/sail up -d
   

2. Initialize Database:

   ./vendor/bin/sail artisan migrate --seed
   

The application will be accessible immediately at http://localhost:8000.

Tip

Always clear application cache after seeding is completed to reflect settings instantly:

./vendor/bin/sail artisan cache:clear

---

🔐 Default Credentials

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

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

Please change default passwords immediately after deployment. Bcrypt 12 rounds + history blockers are active by default.

---

🛡️ Built-in Security Policies

• 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 Standards

All components are rigorously audited under continuous quality benchmarks:

Benchmark	Standard	Auditing Tool
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 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
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

---

🛠️ Specialized Artisan Commands

The administration console provides customized CLI commands for operational workflows:

Command	Description
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.

---

📖 Related Manuals

Document	Target Audience	Content
README.md	All Users	Quick Start & Architectural Overview (This file)
USER_GUIDE.md	Administrators	Operational guidelines for the administrative panel
TECH_STACK.md	Developers	Architectural dependencies, CI pipelines, and plugins details
DEPLOYMENT_GUIDE.md	DevOps Engineers	Outlines production environment server deployments
SECURITY.md	All Users	Security policies and reporting protocols
CHANGELOG.md	All Users	Versioned repository changes log
mobile/README.md	Mobile Engineers	Outline and instructions for React Native/Expo builds

---

📄 License & Terms

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.