biiproject-kit-v2/README.md

⚡ biiproject-kit v2

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:

./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:

   docker compose up -d
   

2. Install backend dependencies:

   composer install
   

3. Setup environment configuration:

   cp .env.example .env
   php artisan key:generate
   

4. Run migrations and seed default users:

   php artisan migrate --seed
   

5. Install frontend dependencies & build assets:

   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:

php artisan test

Or evaluate coverage scores:

php artisan test --coverage