# ⚡ biiproject-kit v2

[![Laravel](https://img.shields.io/badge/Laravel-11.x-FF2D20?style=for-the-badge&logo=laravel)](https://laravel.com)
[![React](https://img.shields.io/badge/React-18.x-61DAFB?style=for-the-badge&logo=react)](https://react.dev)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?style=for-the-badge&logo=typescript)](https://www.typescriptlang.org)
[![TailwindCSS](https://img.shields.io/badge/TailwindCSS-v4.x-06B6D4?style=for-the-badge&logo=tailwindcss)](https://tailwindcss.com)
[![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker)](https://www.docker.com)

A high-performance, enterprise-grade **Laravel 11 + Inertia.js v2 + React 18** starter kit designed to accelerate the shipping times of SaaS and corporate applications. **Version 2** introduces advanced features such as robust multi-factor authentication (2FA), customized application branding, full system auditing, and ready-to-use OAuth2 integration.

---

## 🚀 Key Architectural Improvements in v2

* 🔒 **Granular Security Gateways** — Integrated Time-based One-time Password (TOTP) compatible with Google Authenticator, Authy, or 1Password. Full dynamic login challenge flow with fallback recovery codes.
* 🛡️ **Advanced Spatie RBAC Matrix** — Sleek dashboard (`/roles`) allowing real-time permission modifications per role without code adjustments.
* ⚙️ **Dynamic Brand & Settings Console** — Modify application details (App Name, Logo, Favicon), live mail servers (SMTP settings with built-in Test Email utility), and authentication methods in the browser. Kept inside database configurations with memory caching for fast processing.
* 📁 **Asynchronous Bulk Actions** — Integrated memory-friendly bulk export and import using `maatwebsite/excel` under queuing, along with bulk archiving, restoration, and permanent removal.
* 🌐 **Global App Search Engine** — An intelligent keyboard-navigable global search system (`/api/search`) indexing users, roles, system settings, and notifications instantly.
* 🔌 **Enterprise OAuth2 & SSO Server** — Built-in Laravel Passport endpoints to integrate secure Single Sign-On (SSO) tokens with secondary platforms or mobile applications.

---

## 🛠️ Tech Stack & Dependencies

| Layer | Technology | Version | Description |
|---|---|---|---|
| **Core Framework** | Laravel | `11.x` | Modern backend routing, queues, and container |
| **Frontend Runtime** | React | `18.x` | Declarative UI layer written in TypeScript |
| **Design Engine** | TailwindCSS | `v4.x` | Ultra-fast utility CSS engine |
| **Bridge Engine** | Inertia.js | `v2.x` | Classic routing mechanics with dynamic SPA feel |
| **API Authentication** | Laravel Sanctum | `v4.x` | Fast SPA and mobile API session token auth |
| **OAuth2 / SSO** | Laravel Passport | `v12.x` | Heavy-duty OAuth client authorization servers |
| **Roles & Privileges** | Spatie Permissions | `v6.x` | Granular permission layers using Laravel Gates |
| **Audit Logs** | Spatie Activity Logs | `v4.x` | Detailed logging for DB models and user actions |
| **Docs Generator** | Scribe | `v4.x` | Dynamic API markdown/HTML documentation builder |

---

## 📂 Directory Structure Overview

This project follows clean code conventions and modular MVC architectures:

```text
├── app/
│   ├── Http/
│   │   ├── Controllers/       # Versioned REST Controllers & SPA Action Handlers
│   │   ├── Middleware/        # 2FA checks, CORS, rate limits, and custom gates
│   │   └── Requests/          # Fully-validated Form requests
│   └── Models/                # Database models (User, Setting, RemoteConfig, NotificationLog)
├── bootstrap/
│   └── cache/                 # Optimized system boot caching configurations
├── config/                    # Consolidated application parameters
├── database/
│   ├── migrations/            # Versioned SQL migrations schema
│   └── seeders/               # Auto-populating test profiles & RBAC setups
├── docker/                    # Custom multi-arch Dockerfiles (PHP 8.3 configurations)
├── public/                    # Compiled Vite assets, logos, and entry points
├── resources/
│   ├── css/                   # Global style variables and animations
│   ├── js/
│   │   ├── Components/        # Reusable UI building blocks (DataTable, Modal, Checkbox)
│   │   ├── Contexts/          # State hooks (ToastContext)
│   │   ├── Layouts/           # Sidebars, Navbars, dynamic layout bindings
│   │   └── Pages/             # Individual React single-page routes
│   └── views/                 # Blade server-side templates and layout gates
├── routes/
│   ├── api.php                # Token-protected versioned endpoint routing
│   ├── auth.php               # Login/registration workflows and security challenges
│   └── web.php                # Application administration routes
└── run.sh                     # Automated unified terminal start dashboard
```

---

## ⚡ Quick Start & Automation

This project is fully containerized and features a unified shell script that automates compilation, migration, containerization, and initialization.

### Prerequisites
Make sure **Docker Desktop** is running on your device.

### Spin Up
Simply execute the following command at the root of the project:

```bash
./run.sh
```

> [!NOTE]
> **What the `run.sh` script automates for you:**
> 1. Verifies/creates a local `.env` configuration file from `.env.example`.
> 2. Starts PostgreSQL and Redis containers in the background.
> 3. Installs Composer packages and frontend Node modules (`npm install`).
> 4. Generates the application key and builds the Passport OAuth client keys.
> 5. Runs database migrations and seeds the database with roles and default users.
> 6. Launches the development servers (`Artisan serve` + `Vite` + queue listeners + logs) concurrently in a single dashboard!

---

### 🔧 Manual Setup (Without Automation Script)

If you prefer to perform the setup step-by-step:

1. **Spin up database & cache services:**
   ```bash
   docker compose up -d
   ```
2. **Install backend dependencies:**
   ```bash
   composer install
   ```
3. **Setup environment configuration:**
   ```bash
   cp .env.example .env
   php artisan key:generate
   ```
4. **Run migrations and seed default users:**
   ```bash
   php artisan migrate --seed
   ```
5. **Install frontend dependencies & build assets:**
   ```bash
   npm install
   npm run dev
   ```

---

## 🔐 Default Credentials

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

| Role | Email | Password | Role Features |
|---|---|---|---|
| **super-admin** | `superadmin@biiskit.com` | `password` | Complete access. Bypasses all authority gates globally. |
| **admin** | `admin@biiskit.com` | `password` | Management privileges for users, roles, and logs. |
| **user** | `user@biiskit.com` | `password` | Standard user dashboard with read-only dashboard widgets. |

---

## 🛡️ Roles & Permissions Matrix

The default permission matrix seeded during setup is as follows:

| Permission | super-admin | admin | user |
|---|:---:|:---:|:---:|
| `user.view` | ✓ | ✓ | ✓ |
| `user.create` | ✓ | ✓ | — |
| `user.edit` | ✓ | ✓ | — |
| `user.delete` | ✓ | ✓ | — |
| `role.view` | ✓ | ✓ | — |
| `role.manage` | ✓ | ✓ | — |
| `settings.manage` | ✓ | — | — |

---

## 🌎 Dynamic System Settings (Super-Admin Console)

Accessible at `/system-settings` for users holding the `super-admin` role, this panel allows you to customize the core parameters in real-time:

* **Custom App Branding** — Change app title, header logos, and tab favicon. The UI adapts dynamically.
* **Live Mail Configuration** — Manage SMTP host, port, username, password, and sender credentials. Features a **Test SMTP Email** utility to immediately verify outbound mailing settings.
* **OAuth Login Toggles** — Instantly enable or disable Google/GitHub Single Sign-On (SSO) gateways.
* **Password Policy Enforcer** — Dynamically adjust password complexity requirements (minimum length, mixed-case, numbers, special characters).
* **Mobile Gatekeeper** — Configure API version parameters and remote variables for client mobile apps.

---

## 🔌 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 Gateways
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `POST` | `/api/v1/login` | — | Exchange credentials for Bearer Token (Rate limited) |
| `POST` | `/api/v1/logout` | Bearer | Revoke current authenticated session token |
| `GET` | `/api/v1/me` | Bearer | Fetch authenticated user data, roles, and permissions |

### User Management
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/api/v1/users` | Bearer | Retrieve paginated users (sortable & filterable) |
| `POST` | `/api/v1/users` | Bearer | Create a new user record |
| `GET` | `/api/v1/users/{id}` | Bearer | Get details of a specific user |
| `PATCH` | `/api/v1/users/{id}` | Bearer | Update user profile details |
| `DELETE` | `/api/v1/users/{id}` | Bearer | Soft-delete a user record |
| `POST` | `/api/v1/users/{id}/restore` | Bearer | Restore a soft-deleted user |
| `DELETE` | `/api/v1/users/{id}/force` | Bearer | Permanently delete a user record |

### Remote Mobile App Configurations
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| `GET` | `/api/v1/app-config` | — | Retrieve mobile app remote configuration parameters |

---

## 🧪 Comprehensive Automated Testing

Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite:

```bash
php artisan test
```

Or evaluate coverage scores:
```bash
php artisan test --coverage
```