debesocial/biiproject-kit-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: update README for biiproject-kit v2

Browse Source
This commit is contained in:
debesocial
2026-05-21 16:52:47 +07:00
parent d4fd478e1f
commit 7be12c03aa
1 changed files with 86 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+86 -83
View File
@@ -1,44 +1,54 @@
# biiproject kit
# ⚡ biiproject-kit v2
A production-ready Laravel + Inertia.js starter kit with full RBAC, API auth, activity logging, and system settings — built to ship fast.
[![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)
## Stack
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 13, PHP 8.3, PostgreSQL |
| Frontend | React 18, TypeScript, TailwindCSS v4, Vite 8 |
| Bridge | Inertia.js v2 |
| Auth | Breeze (web session) + Sanctum (API token) + Passport (OAuth2/SSO) |
| RBAC | spatie/laravel-permission |
| Logging | spatie/laravel-activitylog |
| Export/Import | maatwebsite/excel |
| API Docs | knuckleswtf/scribe |
| **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 an automated startup script.
## ⚡ Quick Start
With **Docker** running on your machine, simply execute the following command at the root of the project:
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
```
This script will completely automate the setup by:
1. Creating a `.env` file from `.env.example` (if it does not exist yet).
2. Starting the PostgreSQL and Redis containers in the background.
3. Installing Composer dependencies.
4. Generating the application encryption key.
5. Running all database migrations and seeding the default accounts.
6. Installing Node.js (NPM) frontend dependencies.
7. Starting the development server (`php artisan serve` + `Vite` + queue listeners + logs) concurrently.
> [!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)
### 🔧 Manual Setup (Without Automation Script)
If you prefer to perform the setup manually:
If you prefer to perform the setup step-by-step:
1. **Spin up database & cache services:**
```bash
@@ -57,89 +67,82 @@ If you prefer to perform the setup manually:
```bash
php artisan migrate --seed
```
5. **Install frontend dependencies & start dev server:**
5. **Install frontend dependencies & build assets:**
```bash
npm install
composer dev
npm run dev
```
---
## Default Credentials
## 🔐 Default Credentials
| Role | Email | Password |
|---|---|---|
| super-admin | superadmin@biiskit.com | password |
| admin | admin@biiskit.com | password |
| user | user@biiskit.com | password |
| **super-admin** | `superadmin@biiskit.com` | `password` |
| **admin** | `admin@biiskit.com` | `password` |
| **user** | `user@biiskit.com` | `password` |
## Roles & Permissions
> [!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 | ✓ | — | — |
| `user.view` | ✓ | ✓ | ✓ |
| `user.create` | ✓ | ✓ | — |
| `user.edit` | ✓ | ✓ | — |
| `user.delete` | ✓ | ✓ | — |
| `role.view` | ✓ | ✓ | — |
| `role.manage` | ✓ | ✓ | — |
| `settings.manage` | ✓ | — | — |
`super-admin` bypasses all checks via `Gate::before`.
---
## Features
## ✨ Key Features in v2
- **User Management** — CRUD, soft delete, restore, bulk export/import (Excel/CSV), avatar upload
- **Role & Permission Management** — Assign roles, fine-grained permission matrix UI
- **Activity Logs** — Auto-logged actions via spatie/activitylog, filterable, clearable
- **Notifications** — Admin broadcast notifications with read/unread tracking
- **Two-Factor Auth** — TOTP 2FA (Google Authenticator compatible), enable/disable per user via Account Settings, recovery codes, full login challenge flow
- **Account Settings** — Profile, avatar, phone, bio, password change, 2FA management, account deletion — with tab state persisted in URL hash
- **System Settings** — App name, branding, mail/SMTP, OAuth (Google/GitHub), password rules, mobile app version gate — stored in DB, cached; super-admin only
- **Remote Config** — Mobile app version gate (`GET /api/v1/app/config?platform=android`)
- **Branded Error Pages** — Inertia-rendered 403, 404, 419, 500, 503
- **API** — Versioned REST API (`/api/v1/*`) with Sanctum token auth + rate limiting
- **OAuth2/SSO** — Laravel Passport endpoints for third-party app integration
- **In-app Documentation** — Full feature docs at `/documentation` (accessible via sidebar)
* 👤 **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`.
## Environment Variables
---
Key variables beyond the Laravel defaults:
```env
# Mail (overridable via System Settings UI)
MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
# OAuth (Passport)
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=
```
## API Endpoints (v1)
## 🔌 API Endpoints (v1)
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | `/api/v1/login` | — | Get Bearer token (rate-limited: 10/min) |
| POST | `/api/v1/logout` | Bearer | Revoke token |
| GET | `/api/v1/me` | Bearer | Authenticated user with roles & permissions |
| GET | `/api/v1/users` | Bearer | List users (paginated, sortable, filterable) |
| POST | `/api/v1/users` | Bearer | Create user |
| GET | `/api/v1/users/{id}` | Bearer | Get user |
| PATCH | `/api/v1/users/{id}` | Bearer | Update user |
| DELETE | `/api/v1/users/{id}` | Bearer | Soft-delete user |
| POST | `/api/v1/users/{id}/restore` | Bearer | Restore user |
| DELETE | `/api/v1/users/{id}/force` | Bearer | Permanent delete |
| GET | `/api/v1/app-config` | — | Mobile remote config |
| `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 |
Full interactive docs: `GET /documentation`
---
## Running Tests
## 🧪 Running Tests
Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite:
```bash
php artisan test
# or with coverage:
```
Or evaluate coverage scores:
```bash
php artisan test --coverage
```