⚡ biiproject-kit v2
A high-performance, enterprise-grade Laravel 11 + Inertia.js v2 + React 18 starter kit designed to accelerate the shipping times of SaaS and corporate applications. Version 2 introduces advanced features such as robust multi-factor authentication (2FA), customized application branding, full system auditing, and ready-to-use OAuth2 integration.
🚀 Key Architectural Improvements in v2
- 🔒 Granular Security Gateways — Integrated Time-based One-time Password (TOTP) compatible with Google Authenticator, Authy, or 1Password. Full dynamic login challenge flow with fallback recovery codes.
- 🛡️ Advanced Spatie RBAC Matrix — Sleek dashboard (
/roles) allowing real-time permission modifications per role without code adjustments. - ⚙️ Dynamic Brand & Settings Console — Modify application details (App Name, Logo, Favicon), live mail servers (SMTP settings with built-in Test Email utility), and authentication methods in the browser. Kept inside database configurations with memory caching for fast processing.
- 📁 Asynchronous Bulk Actions — Integrated memory-friendly bulk export and import using
maatwebsite/excelunder queuing, along with bulk archiving, restoration, and permanent removal. - 🌐 Global App Search Engine — An intelligent keyboard-navigable global search system (
/api/search) indexing users, roles, system settings, and notifications instantly. - 🔌 Enterprise OAuth2 & SSO Server — Built-in Laravel Passport endpoints to integrate secure Single Sign-On (SSO) tokens with secondary platforms or mobile applications.
🛠️ Tech Stack & Dependencies
| Layer | Technology | Version | Description |
|---|---|---|---|
| Core Framework | Laravel | 11.x |
Modern backend routing, queues, and container |
| Frontend Runtime | React | 18.x |
Declarative UI layer written in TypeScript |
| Design Engine | TailwindCSS | v4.x |
Ultra-fast utility CSS engine |
| Bridge Engine | Inertia.js | v2.x |
Classic routing mechanics with dynamic SPA feel |
| API Authentication | Laravel Sanctum | v4.x |
Fast SPA and mobile API session token auth |
| OAuth2 / SSO | Laravel Passport | v12.x |
Heavy-duty OAuth client authorization servers |
| Roles & Privileges | Spatie Permissions | v6.x |
Granular permission layers using Laravel Gates |
| Audit Logs | Spatie Activity Logs | v4.x |
Detailed logging for DB models and user actions |
| Docs Generator | Scribe | v4.x |
Dynamic API markdown/HTML documentation builder |
📂 Directory Structure Overview
This project follows clean code conventions and modular MVC architectures:
├── app/
│ ├── Http/
│ │ ├── Controllers/ # Versioned REST Controllers & SPA Action Handlers
│ │ ├── Middleware/ # 2FA checks, CORS, rate limits, and custom gates
│ │ └── Requests/ # Fully-validated Form requests
│ └── Models/ # Database models (User, Setting, RemoteConfig, NotificationLog)
├── bootstrap/
│ └── cache/ # Optimized system boot caching configurations
├── config/ # Consolidated application parameters
├── database/
│ ├── migrations/ # Versioned SQL migrations schema
│ └── seeders/ # Auto-populating test profiles & RBAC setups
├── docker/ # Custom multi-arch Dockerfiles (PHP 8.3 configurations)
├── public/ # Compiled Vite assets, logos, and entry points
├── resources/
│ ├── css/ # Global style variables and animations
│ ├── js/
│ │ ├── Components/ # Reusable UI building blocks (DataTable, Modal, Checkbox)
│ │ ├── Contexts/ # State hooks (ToastContext)
│ │ ├── Layouts/ # Sidebars, Navbars, dynamic layout bindings
│ │ └── Pages/ # Individual React single-page routes
│ └── views/ # Blade server-side templates and layout gates
├── routes/
│ ├── api.php # Token-protected versioned endpoint routing
│ ├── auth.php # Login/registration workflows and security challenges
│ └── web.php # Application administration routes
└── run.sh # Automated unified terminal start dashboard
⚡ Quick Start & Automation
This project is fully containerized and features a unified shell script that automates compilation, migration, containerization, and initialization.
Prerequisites
Make sure Docker Desktop is running on your device.
Spin Up
Simply execute the following command at the root of the project:
./run.sh
Note
What the
run.shscript automates for you:
- Verifies/creates a local
.envconfiguration file from.env.example.- Starts PostgreSQL and Redis containers in the background.
- Installs Composer packages and frontend Node modules (
npm install).- Generates the application key and builds the Passport OAuth client keys.
- Runs database migrations and seeds the database with roles and default users.
- 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:
- Spin up database & cache services:
docker compose up -d - Install backend dependencies:
composer install - Setup environment configuration:
cp .env.example .env php artisan key:generate - Run migrations and seed default users:
php artisan migrate --seed - Install frontend dependencies & build assets:
npm install npm run dev
🔐 Default Credentials
Use the default credentials below to test the RBAC capabilities of the starter kit:
| Role | Password | Role Features | |
|---|---|---|---|
| super-admin | superadmin@biiskit.com |
password |
Complete access. Bypasses all authority gates globally. |
| admin | admin@biiskit.com |
password |
Management privileges for users, roles, and logs. |
| user | user@biiskit.com |
password |
Standard user dashboard with read-only dashboard widgets. |
🛡️ Roles & Permissions Matrix
The default permission matrix seeded during setup is as follows:
| Permission | super-admin | admin | user |
|---|---|---|---|
user.view |
✓ | ✓ | ✓ |
user.create |
✓ | ✓ | — |
user.edit |
✓ | ✓ | — |
user.delete |
✓ | ✓ | — |
role.view |
✓ | ✓ | — |
role.manage |
✓ | ✓ | — |
settings.manage |
✓ | — | — |
🌎 Dynamic System Settings (Super-Admin Console)
Accessible at /system-settings for users holding the super-admin role, this panel allows you to customize the core parameters in real-time:
- Custom App Branding — Change app title, header logos, and tab favicon. The UI adapts dynamically.
- Live Mail Configuration — Manage SMTP host, port, username, password, and sender credentials. Features a Test SMTP Email utility to immediately verify outbound mailing settings.
- OAuth Login Toggles — Instantly enable or disable Google/GitHub Single Sign-On (SSO) gateways.
- Password Policy Enforcer — Dynamically adjust password complexity requirements (minimum length, mixed-case, numbers, special characters).
- Mobile Gatekeeper — Configure API version parameters and remote variables for client mobile apps.
🔌 API Endpoints Reference (v1)
All endpoints listed below are versioned and located under /api/v1/*. Requests requesting authorization require a header formatted as Authorization: Bearer <your_token>.
Authentication Gateways
| 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 |
User Management
| Method | Endpoint | Auth | Description |
|---|---|---|---|
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 |
Remote Mobile App Configurations
| Method | Endpoint | Auth | Description |
|---|---|---|---|
GET |
/api/v1/app-config |
— | Retrieve mobile app remote configuration parameters |
🧪 Comprehensive Automated Testing
Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite:
php artisan test
Or evaluate coverage scores:
php artisan test --coverage