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 | | Layer | Technology |
|---|---| |---|---|
| Backend | Laravel 13, PHP 8.3, PostgreSQL | | **Backend** | Laravel 11.x (PHP 8.3+) with PostgreSQL |
| Frontend | React 18, TypeScript, TailwindCSS v4, Vite 8 | | **Frontend** | React 18, TypeScript, TailwindCSS v4, Vite 8 |
| Bridge | Inertia.js v2 | | **Bridge** | Inertia.js v2 (Sleek Single Page Application feel) |
| Auth | Breeze (web session) + Sanctum (API token) + Passport (OAuth2/SSO) | | **Authentication** | Breeze (Web Session) + Sanctum (API Tokens) + Passport (OAuth2/SSO) |
| RBAC | spatie/laravel-permission | | **RBAC** | `spatie/laravel-permission` (Granular Role & Permission Matrix UI) |
| Logging | spatie/laravel-activitylog | | **System Audit** | `spatie/laravel-activitylog` |
| Export/Import | maatwebsite/excel | | **Import & Export** | `maatwebsite/excel` (Asynchronous and memory-safe bulk exports) |
| API Docs | knuckleswtf/scribe | | **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 ```bash
./run.sh ./run.sh
``` ```
This script will completely automate the setup by: > [!NOTE]
1. Creating a `.env` file from `.env.example` (if it does not exist yet). > **What the `run.sh` script automates for you:**
2. Starting the PostgreSQL and Redis containers in the background. > 1. Verifies/creates a local `.env` configuration file.
3. Installing Composer dependencies. > 2. Starts PostgreSQL and Redis containers in the background.
4. Generating the application encryption key. > 3. Installs Composer packages and frontend Node modules (`npm install`).
5. Running all database migrations and seeding the default accounts. > 4. Generates the application key and builds the Passport OAuth client keys.
6. Installing Node.js (NPM) frontend dependencies. > 5. Runs database migrations and seeds the database with roles and default users.
7. Starting the development server (`php artisan serve` + `Vite` + queue listeners + logs) concurrently. > 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:** 1. **Spin up database & cache services:**
```bash ```bash
@@ -57,89 +67,82 @@ If you prefer to perform the setup manually:
```bash ```bash
php artisan migrate --seed php artisan migrate --seed
``` ```
5. **Install frontend dependencies & start dev server:** 5. **Install frontend dependencies & build assets:**
```bash ```bash
npm install npm install
composer dev npm run dev
``` ```
---
## Default Credentials ## 🔐 Default Credentials
| Role | Email | Password | | Role | Email | Password |
|---|---|---| |---|---|---|
| super-admin | superadmin@biiskit.com | password | | **super-admin** | `superadmin@biiskit.com` | `password` |
| admin | admin@biiskit.com | password | | **admin** | `admin@biiskit.com` | `password` |
| user | user@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 | | Permission | super-admin | admin | user |
|---|:---:|:---:|:---:| |---|:---:|:---:|:---:|
| user.view | ✓ | ✓ | ✓ | | `user.view` | ✓ | ✓ | ✓ |
| user.create | ✓ | ✓ | — | | `user.create` | ✓ | ✓ | — |
| user.edit | ✓ | ✓ | — | | `user.edit` | ✓ | ✓ | — |
| user.delete | ✓ | ✓ | — | | `user.delete` | ✓ | ✓ | — |
| role.view | ✓ | ✓ | — | | `role.view` | ✓ | ✓ | — |
| role.manage | ✓ | ✓ | — | | `role.manage` | ✓ | ✓ | — |
| settings.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 * 👤 **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** — Assign roles, fine-grained permission matrix UI * 🛡️ **Role & Permission Management UI** — Create and configure roles with a matrix UI that assigns permissions with real-time feedback.
- **Activity Logs** — Auto-logged actions via spatie/activitylog, filterable, clearable * 🪵 **Integrated Audit/Activity Logs** — Track and view user actions, database events, and API calls. Filterable, paginated, and clearable dashboard.
- **Notifications** — Admin broadcast notifications with read/unread tracking * 📢 **Centralized Notifications** — Broadcaster notification panel for administration announcements with read/unread indicators.
- **Two-Factor Auth** — TOTP 2FA (Google Authenticator compatible), enable/disable per user via Account Settings, recovery codes, full login challenge flow * 🔑 **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.
- **Account Settings** — Profile, avatar, phone, bio, password change, 2FA management, account deletion — with tab state persisted in URL hash * ⚙️ **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.
- **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 API** — Seamless Mobile app remote config control (`GET /api/v1/app-config?platform=android`).
- **Remote Config** — Mobile app version gate (`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.
- **Branded Error Pages** — Inertia-rendered 403, 404, 419, 500, 503 * 📘 **Internal Documentation Hub** — Integrated documentation accessible directly at `/documentation`.
- **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)
## Environment Variables ---
Key variables beyond the Laravel defaults: ## 🔌 API Endpoints (v1)
```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)
| Method | Endpoint | Auth | Description | | Method | Endpoint | Auth | Description |
|---|---|---|---| |---|---|---|---|
| POST | `/api/v1/login` | — | Get Bearer token (rate-limited: 10/min) | | `POST` | `/api/v1/login` | — | Exchange credentials for Bearer Token (Rate limited) |
| POST | `/api/v1/logout` | Bearer | Revoke token | | `POST` | `/api/v1/logout` | Bearer | Revoke current authenticated session token |
| GET | `/api/v1/me` | Bearer | Authenticated user with roles & permissions | | `GET` | `/api/v1/me` | Bearer | Fetch authenticated user data, roles, and permissions |
| GET | `/api/v1/users` | Bearer | List users (paginated, sortable, filterable) | | `GET` | `/api/v1/users` | Bearer | Retrieve paginated users (sortable & filterable) |
| POST | `/api/v1/users` | Bearer | Create user | | `POST` | `/api/v1/users` | Bearer | Create a new user record |
| GET | `/api/v1/users/{id}` | Bearer | Get user | | `GET` | `/api/v1/users/{id}` | Bearer | Get details of a specific user |
| PATCH | `/api/v1/users/{id}` | Bearer | Update user | | `PATCH` | `/api/v1/users/{id}` | Bearer | Update user profile details |
| DELETE | `/api/v1/users/{id}` | Bearer | Soft-delete user | | `DELETE` | `/api/v1/users/{id}` | Bearer | Soft-delete a user record |
| POST | `/api/v1/users/{id}/restore` | Bearer | Restore user | | `POST` | `/api/v1/users/{id}/restore` | Bearer | Restore a soft-deleted user |
| DELETE | `/api/v1/users/{id}/force` | Bearer | Permanent delete | | `DELETE` | `/api/v1/users/{id}/force` | Bearer | Permanently delete a user record |
| GET | `/api/v1/app-config` | — | Mobile remote config | | `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 ```bash
php artisan test php artisan test
# or with coverage: ```
Or evaluate coverage scores:
```bash
php artisan test --coverage php artisan test --coverage
``` ```