Files

T

debesocial e024777a72 docs: update and complete README with advanced features, tree structure, and orchestration details

2026-05-21 16:53:46 +07:00

13 KiB

Raw Blame History

⚡ 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/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:

├── 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.sh script automates for you:

Verifies/creates a local .env configuration 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	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:

php artisan test

Or evaluate coverage scores:

php artisan test --coverage

📂 Project Directory Structure

.
├── 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:

Port & Instance Conflict Protection: Scans and gracefully stops local/containerized processes conflicting on ports 8000 (Web), 5432 (Postgres), and 6379 (Redis).
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.
Database Health Synchronization: Implements asynchronous health loops checking container states. Database migrations and seeder processes wait precisely until services report a healthy state.
Automatic Workspace Permissions: Secures and corrects directory owner attributes (chown / chmod) across compiled Vite bundles and Laravel cache paths.

13 KiB Raw Blame History