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

docs: expand README with directory structures, tech stack specs and detailed developer guides

Browse Source
This commit is contained in:
debesocial
2026-05-21 16:53:16 +07:00
parent 7be12c03aa
commit 96d5d8717f
1 changed files with 97 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+97 -35
View File
@@ -6,30 +6,82 @@
[![TailwindCSS](https://img.shields.io/badge/TailwindCSS-v4.x-06B6D4?style=for-the-badge&logo=tailwindcss)](https://tailwindcss.com) [![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) [![Docker](https://img.shields.io/badge/Docker-Ready-2496ED?style=for-the-badge&logo=docker)](https://www.docker.com)
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. 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.
--- ---
## 🛠️ Tech Stack ## 🚀 Key Architectural Improvements in v2
| Layer | Technology | * 🔒 **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.
| **Backend** | Laravel 11.x (PHP 8.3+) with PostgreSQL | * ⚙️ **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.
| **Frontend** | React 18, TypeScript, TailwindCSS v4, Vite 8 | * 📁 **Asynchronous Bulk Actions** — Integrated memory-friendly bulk export and import using `maatwebsite/excel` under queuing, along with bulk archiving, restoration, and permanent removal.
| **Bridge** | Inertia.js v2 (Sleek Single Page Application feel) | * 🌐 **Global App Search Engine** — An intelligent keyboard-navigable global search system (`/api/search`) indexing users, roles, system settings, and notifications instantly.
| **Authentication** | Breeze (Web Session) + Sanctum (API Tokens) + Passport (OAuth2/SSO) | * 🔌 **Enterprise OAuth2 & SSO Server** — Built-in Laravel Passport endpoints to integrate secure Single Sign-On (SSO) tokens with secondary platforms or mobile applications.
| **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 ## 🛠️ Tech Stack & Dependencies
This project is fully containerized and features a unified automation startup script. | 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 |
With **Docker** running on your local machine, simply execute the following command at the root of the project: ---
## 📂 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
@@ -37,7 +89,7 @@ With **Docker** running on your local machine, simply execute the following comm
> [!NOTE] > [!NOTE]
> **What the `run.sh` script automates for you:** > **What the `run.sh` script automates for you:**
> 1. Verifies/creates a local `.env` configuration file. > 1. Verifies/creates a local `.env` configuration file from `.env.example`.
> 2. Starts PostgreSQL and Redis containers in the background. > 2. Starts PostgreSQL and Redis containers in the background.
> 3. Installs Composer packages and frontend Node modules (`npm install`). > 3. Installs Composer packages and frontend Node modules (`npm install`).
> 4. Generates the application key and builds the Passport OAuth client keys. > 4. Generates the application key and builds the Passport OAuth client keys.
@@ -77,19 +129,20 @@ If you prefer to perform the setup step-by-step:
## 🔐 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` |
> [!IMPORTANT] | Role | Email | Password | Role Features |
> The `super-admin` role bypasses all authorization checks globally via `Gate::before`, allowing you full management control. |---|---|---|---|
| **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 ## 🛡️ 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` | ✓ | ✓ | ✓ |
@@ -102,27 +155,32 @@ If you prefer to perform the setup step-by-step:
--- ---
## ✨ Key Features in v2 ## 🌎 Dynamic System Settings (Super-Admin Console)
* 👤 **User Management & Soft Deletes** — CRUD operations, soft-delete with full restoration, bulk exports to Excel/CSV, and dynamic profile photo/avatar uploads. 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 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. * **Custom App Branding** — Change app title, header logos, and tab favicon. The UI adapts dynamically.
* 📢 **Centralized Notifications** — Broadcaster notification panel for administration announcements with read/unread indicators. * **Live Mail Configuration** — Manage SMTP host, port, username, password, and sender credentials. Features a **Test SMTP Email** utility to immediately verify outbound mailing settings.
* 🔑 **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. * **OAuth Login Toggles** — Instantly enable or disable Google/GitHub Single Sign-On (SSO) gateways.
* ⚙️ **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. * **Password Policy Enforcer** — Dynamically adjust password complexity requirements (minimum length, mixed-case, numbers, special characters).
* 🔌 **Remote Config API** — Seamless Mobile app remote config control (`GET /api/v1/app-config?platform=android`). * **Mobile Gatekeeper** — Configure API version parameters and remote variables for client mobile apps.
* 🎨 **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) ## 🔌 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 | | Method | Endpoint | Auth | Description |
|---|---|---|---| |---|---|---|---|
| `POST` | `/api/v1/login` | — | Exchange credentials for Bearer Token (Rate limited) | | `POST` | `/api/v1/login` | — | Exchange credentials for Bearer Token (Rate limited) |
| `POST` | `/api/v1/logout` | Bearer | Revoke current authenticated session token | | `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/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) | | `GET` | `/api/v1/users` | Bearer | Retrieve paginated users (sortable & filterable) |
| `POST` | `/api/v1/users` | Bearer | Create a new user record | | `POST` | `/api/v1/users` | Bearer | Create a new user record |
| `GET` | `/api/v1/users/{id}` | Bearer | Get details of a specific user | | `GET` | `/api/v1/users/{id}` | Bearer | Get details of a specific user |
@@ -130,11 +188,15 @@ If you prefer to perform the setup step-by-step:
| `DELETE` | `/api/v1/users/{id}` | Bearer | Soft-delete a user record | | `DELETE` | `/api/v1/users/{id}` | Bearer | Soft-delete a user record |
| `POST` | `/api/v1/users/{id}/restore` | Bearer | Restore a soft-deleted user | | `POST` | `/api/v1/users/{id}/restore` | Bearer | Restore a soft-deleted user |
| `DELETE` | `/api/v1/users/{id}/force` | Bearer | Permanently delete a user record | | `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 | | `GET` | `/api/v1/app-config` | — | Retrieve mobile app remote configuration parameters |
--- ---
## 🧪 Running Tests ## 🧪 Comprehensive Automated Testing
Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite: Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite: