From 96d5d8717f86ae502ba78c5fe562d8a8c57467f4 Mon Sep 17 00:00:00 2001 From: debesocial Date: Thu, 21 May 2026 16:53:16 +0700 Subject: [PATCH] docs: expand README with directory structures, tech stack specs and detailed developer guides --- README.md | 132 +++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 97 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index d9690d7..4b4c944 100644 --- a/README.md +++ b/README.md @@ -6,30 +6,82 @@ [![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) -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 | -|---|---| -| **Backend** | Laravel 11.x (PHP 8.3+) with PostgreSQL | -| **Frontend** | React 18, TypeScript, TailwindCSS v4, Vite 8 | -| **Bridge** | Inertia.js v2 (Sleek Single Page Application feel) | -| **Authentication** | Breeze (Web Session) + Sanctum (API Tokens) + Passport (OAuth2/SSO) | -| **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` | +* ๐Ÿ”’ **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. --- -## โšก 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 ./run.sh @@ -37,7 +89,7 @@ With **Docker** running on your local machine, simply execute the following comm > [!NOTE] > **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. > 3. Installs Composer packages and frontend Node modules (`npm install`). > 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 -| 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: -> [!IMPORTANT] -> The `super-admin` role bypasses all authorization checks globally via `Gate::before`, allowing you full management control. +| 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` | โœ“ | โœ“ | โœ“ | @@ -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. -* ๐Ÿ›ก๏ธ **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. -* ๐Ÿ“ข **Centralized Notifications** โ€” Broadcaster notification panel for administration announcements with read/unread indicators. -* ๐Ÿ”‘ **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. -* โš™๏ธ **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. -* ๐Ÿ”Œ **Remote Config API** โ€” Seamless Mobile app remote config control (`GET /api/v1/app-config?platform=android`). -* ๐ŸŽจ **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`. +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 (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 `. + +### 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 | @@ -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 | | `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 | --- -## ๐Ÿงช Running Tests +## ๐Ÿงช Comprehensive Automated Testing Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite: