211 lines
9.9 KiB
Markdown
211 lines
9.9 KiB
Markdown
# ⚡ biiproject-kit v2
|
|
|
|
[](https://laravel.com)
|
|
[](https://react.dev)
|
|
[](https://www.typescriptlang.org)
|
|
[](https://tailwindcss.com)
|
|
[](https://www.docker.com)
|
|
|
|
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/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.
|
|
|
|
---
|
|
|
|
## 🛠️ 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
|
|
```
|
|
|
|
> [!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)
|
|
|
|
If you prefer to perform the setup step-by-step:
|
|
|
|
1. **Spin up database & cache services:**
|
|
```bash
|
|
docker compose up -d
|
|
```
|
|
2. **Install backend dependencies:**
|
|
```bash
|
|
composer install
|
|
```
|
|
3. **Setup environment configuration:**
|
|
```bash
|
|
cp .env.example .env
|
|
php artisan key:generate
|
|
```
|
|
4. **Run migrations and seed default users:**
|
|
```bash
|
|
php artisan migrate --seed
|
|
```
|
|
5. **Install frontend dependencies & build assets:**
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## 🔐 Default Credentials
|
|
|
|
Use the default credentials below to test the RBAC capabilities of the starter kit:
|
|
|
|
| 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` | ✓ | — | — |
|
|
|
|
---
|
|
|
|
## 🌎 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:
|
|
|
|
```bash
|
|
php artisan test
|
|
```
|
|
|
|
Or evaluate coverage scores:
|
|
```bash
|
|
php artisan test --coverage
|
|
```
|