Compare commits
3 Commits
d4fd478e1f
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 debesocial
|
e024777a72 | ||
|
debesocial
|
96d5d8717f | ||
|
debesocial
|
7be12c03aa |
@@ -1,44 +1,106 @@
|
||||
# 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.
|
||||
[](https://laravel.com)
|
||||
[](https://react.dev)
|
||||
[](https://www.typescriptlang.org)
|
||||
[](https://tailwindcss.com)
|
||||
[](https://www.docker.com)
|
||||
|
||||
## Stack
|
||||
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.
|
||||
|
||||
| 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 |
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
## 🚀 Key Architectural Improvements in v2
|
||||
|
||||
This project is fully containerized and features an automated startup script.
|
||||
* 🔒 **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/excel` under 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.
|
||||
|
||||
With **Docker** running on your machine, simply execute the following command at the root of the project:
|
||||
---
|
||||
|
||||
## 🛠️ 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:
|
||||
|
||||
```text
|
||||
├── 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:
|
||||
|
||||
```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 from `.env.example`.
|
||||
> 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 +119,144 @@ 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 |
|
||||
Use the default credentials below to test the RBAC capabilities of the starter kit:
|
||||
|
||||
## Roles & Permissions
|
||||
| Role | Email | 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 | ✓ | — | — |
|
||||
| `user.view` | ✓ | ✓ | ✓ |
|
||||
| `user.create` | ✓ | ✓ | — |
|
||||
| `user.edit` | ✓ | ✓ | — |
|
||||
| `user.delete` | ✓ | ✓ | — |
|
||||
| `role.view` | ✓ | ✓ | — |
|
||||
| `role.manage` | ✓ | ✓ | — |
|
||||
| `settings.manage` | ✓ | — | — |
|
||||
|
||||
`super-admin` bypasses all checks via `Gate::before`.
|
||||
---
|
||||
|
||||
## Features
|
||||
## 🌎 Dynamic System Settings (Super-Admin Console)
|
||||
|
||||
- **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)
|
||||
Accessible at `/system-settings` for users holding the `super-admin` role, this panel allows you to customize the core parameters in real-time:
|
||||
|
||||
## Environment Variables
|
||||
* **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.
|
||||
|
||||
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=
|
||||
## 🔌 API Endpoints Reference (v1)
|
||||
|
||||
# OAuth (Passport)
|
||||
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=
|
||||
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=
|
||||
```
|
||||
|
||||
## API Endpoints (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` | — | 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 |
|
||||
|
||||
Full interactive docs: `GET /documentation`
|
||||
### 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 |
|
||||
|
||||
## Running Tests
|
||||
### 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:
|
||||
|
||||
```bash
|
||||
php artisan test
|
||||
# or with coverage:
|
||||
```
|
||||
|
||||
Or evaluate coverage scores:
|
||||
```bash
|
||||
php artisan test --coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 Project Directory Structure
|
||||
|
||||
```text
|
||||
.
|
||||
├── app/
|
||||
│ ├── Http/
|
||||
│ │ ├── Controllers/
|
||||
│ │ │ ├── Api/V1/ # Sanctum-protected REST API endpoints
|
||||
│ │ │ ├── Auth/ # Full Breeze web and 2FA authentication flow
|
||||
│ │ │ ├── Settings/ # Dynamic system configurations and branding controllers
|
||||
│ │ │ ├── Dashboard/ # Dynamic home widgets layout engine
|
||||
│ │ │ └── Profile/ # Account preferences and session settings
|
||||
│ │ └── Middleware/ # Custom CORS, IP blockers, 2FA enforcement
|
||||
│ ├── Models/ # User, Role, Permission, SystemSetting, ActivityLog, DashboardWidget
|
||||
│ └── Services/ # Dynamic configuration caches, Excel batching, and remote sync services
|
||||
├── bootstrap/ # Compiled route/config caches
|
||||
├── config/ # Core configs (Spatie matrix, Breeze auth, Inertia, Mail)
|
||||
├── database/
|
||||
│ ├── migrations/ # Standardized DB schemas (users, roles, permissions, settings, logs)
|
||||
│ └── seeders/ # Initial dynamic settings & full RBAC Matrix seeds
|
||||
├── docker/ # Optimized Alpine + PHP-FPM / pgsql / Redis service images
|
||||
├── public/ # Compiled browser-ready front-end assets
|
||||
├── resources/
|
||||
│ ├── js/
|
||||
│ │ ├── Components/ # Reusable dynamic components (Command Palette, Modals, Forms)
|
||||
│ │ ├── Layouts/ # Premium dashboard frames, notification panel, global search
|
||||
│ │ └── Pages/ # Sleek React + TailwindCSS views (RBAC, Audit Logs, Settings)
|
||||
│ └── views/ # Primary Inertia wrapper template
|
||||
├── routes/ # Structured API, Web, Auth, and System configuration endpoints
|
||||
├── storage/ # Dynamic file assets, private exports, and system logs
|
||||
└── tests/ # Full-featured integration and regression test coverage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🐳 Architecture & Self-Healing Orchestration (`run.sh`)
|
||||
|
||||
The starter kit features an advanced orchestration script (`run.sh`) that automates container configuration and implements robust **Self-Healing Mechanics**:
|
||||
|
||||
1. **Port & Instance Conflict Protection**: Scans and gracefully stops local/containerized processes conflicting on ports `8000` (Web), `5432` (Postgres), and `6379` (Redis).
|
||||
2. **Zero-Dependency Host Bootstrapping**: Automatically spins up temporary PHP containers to run `composer install` if dependencies are absent, ensuring you can initialize the stack on a completely clean host.
|
||||
3. **Database Health Synchronization**: Implements asynchronous health loops checking container states. Database migrations and seeder processes wait precisely until services report a `healthy` state.
|
||||
4. **Automatic Workspace Permissions**: Secures and corrects directory owner attributes (`chown` / `chmod`) across compiled Vite bundles and Laravel cache paths.
|
||||
|
||||
---
|
||||
|
||||
## 📄 License & Terms
|
||||
|
||||
Proprietary © 2026 Andika Debi Putra (Debesocial). Designed and packaged to expedite development while aligning with modern security and architectural guidelines. All rights reserved.
|
||||
|
||||
Reference in New Issue
Block a user