# ⚡ 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)]()

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:

```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
```

---

## ⚡ Quick Start & Development

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]
> Always clear application cache after seeding is completed to reflect settings instantly:
> ```bash
> ./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](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 |

---

## 📄 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.