149 lines
6.2 KiB
Markdown
149 lines
6.2 KiB
Markdown
# ⚡ biiproject-kit v2
|
|
|
|
[](https://laravel.com)
|
|
[](https://react.dev)
|
|
[](https://www.typescriptlang.org)
|
|
[](https://tailwindcss.com)
|
|
[](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
|
|
```
|