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

Compare commits

base: debesocial/biiproject-kit-v2:d4fd478e1ff2d98884066105adcbd9ae94caef15
Branches Tags
debesocial/biiproject-kit-v2:main
..
compare: debesocial/biiproject-kit-v2:e024777a721b6f3d67a215021003cc8631aa6440
Branches Tags
debesocial/biiproject-kit-v2:main

3 Commits
d4fd478e1f .. e024777a72

Author SHA1 Message Date
debesocial e024777a72 docs: update and complete README with advanced features, tree structure, and orchestration details 2026-05-21 16:53:46 +07:00
debesocial 96d5d8717f docs: expand README with directory structures, tech stack specs and detailed developer guides 2026-05-21 16:53:16 +07:00
debesocial 7be12c03aa docs: update README for biiproject-kit v2 2026-05-21 16:52:47 +07:00
1 changed files with 202 additions and 85 deletions
Expand all files Collapse all files
README.md
+202 -85
View File
@@ -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. [![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-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 ```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 from `.env.example`.
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 +119,144 @@ 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 | Use the default credentials below to test the RBAC capabilities of the starter kit:
|---|---|---|
| super-admin | superadmin@biiskit.com | password |
| admin | admin@biiskit.com | password |
| user | user@biiskit.com | password |
## 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 | | 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 ## 🌎 Dynamic System Settings (Super-Admin Console)
- **User Management** — CRUD, soft delete, restore, bulk export/import (Excel/CSV), avatar upload Accessible at `/system-settings` for users holding the `super-admin` role, this panel allows you to customize the core parameters in real-time:
- **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)
## 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 ## 🔌 API Endpoints Reference (v1)
# Mail (overridable via System Settings UI)
MAIL_MAILER=smtp
MAIL_HOST=
MAIL_PORT=587
MAIL_USERNAME=
MAIL_PASSWORD=
# OAuth (Passport) All endpoints listed below are versioned and located under `/api/v1/*`. Requests requesting authorization require a header formatted as `Authorization: Bearer <your_token>`.
PASSPORT_PERSONAL_ACCESS_CLIENT_ID=
PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET=
```
## API Endpoints (v1)
### Authentication Gateways
| 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) |
| 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 |
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 ```bash
php artisan test php artisan test
# or with coverage: ```
Or evaluate coverage scores:
```bash
php artisan test --coverage 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.