# ⚡ 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-ready **Laravel + Inertia.js + React** starter kit with a comprehensive built-in Role-Based Access Control (RBAC) matrix, API authentication, activity logging, and real-time custom branding systems. **Version 2** is built to accelerate development and shipping times.

---

## 🛠️ Tech Stack

| Layer | Technology |
|---|---|
| **Backend** | Laravel 11.x (PHP 8.3+) with PostgreSQL |
| **Frontend** | React 18, TypeScript, TailwindCSS v4, Vite 8 |
| **Bridge** | Inertia.js v2 (Sleek Single Page Application feel) |
| **Authentication** | Breeze (Web Session) + Sanctum (API Tokens) + Passport (OAuth2/SSO) |
| **RBAC** | `spatie/laravel-permission` (Granular Role & Permission Matrix UI) |
| **System Audit** | `spatie/laravel-activitylog` |
| **Import & Export** | `maatwebsite/excel` (Asynchronous and memory-safe bulk exports) |
| **Interactive API Docs**| `knuckleswtf/scribe` |

---

## ⚡ Quick Start

This project is fully containerized and features a unified automation startup script.

With **Docker** running on your local machine, 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.
> 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

| Role | Email | Password |
|---|---|---|
| **super-admin** | `superadmin@biiskit.com` | `password` |
| **admin** | `admin@biiskit.com` | `password` |
| **user** | `user@biiskit.com` | `password` |

> [!IMPORTANT]
> The `super-admin` role bypasses all authorization checks globally via `Gate::before`, allowing you full management control.

---

## 🛡️ Roles & Permissions Matrix

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

---

## ✨ Key Features in v2

* 👤 **User Management & Soft Deletes** — CRUD operations, soft-delete with full restoration, bulk exports to Excel/CSV, and dynamic profile photo/avatar uploads.
* 🛡️ **Role & Permission Management UI** — Create and configure roles with a matrix UI that assigns permissions with real-time feedback.
* 🪵 **Integrated Audit/Activity Logs** — Track and view user actions, database events, and API calls. Filterable, paginated, and clearable dashboard.
* 📢 **Centralized Notifications** — Broadcaster notification panel for administration announcements with read/unread indicators.
* 🔑 **Two-Factor Authentication (2FA)** — Time-based One-time Password (TOTP) compatible with Google Authenticator, Authy, or 1Password. Full login challenge flow with secure recovery codes.
* ⚙️ **System & Theme Settings** — Dynamic branding settings (App Name, Logo, Favicon), dynamic Mail/SMTP configurations, OAuth logins (Google/GitHub), and password policy control. Kept in DB with optimized cache.
* 🔌 **Remote Config API** — Seamless Mobile app remote config control (`GET /api/v1/app-config?platform=android`).
* 🎨 **Elegant Custom Branded Error Pages** — Inertia-rendered, customized UI error templates for `403`, `404`, `419`, `500`, and `503` codes.
* 📘 **Internal Documentation Hub** — Integrated documentation accessible directly at `/documentation`.

---

## 🔌 API Endpoints (v1)

| 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 |
| `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 |
| `GET` | `/api/v1/app-config` | — | Retrieve mobile app remote configuration parameters |

---

## 🧪 Running Tests

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