diff --git a/README.md b/README.md index c8bc42c..d9690d7 100644 --- a/README.md +++ b/README.md @@ -1,44 +1,54 @@ -# 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-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. + +--- + +## ๐Ÿ› ๏ธ Tech Stack | 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 | +| **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` | -## Quick Start +--- -This project is fully containerized and features an automated startup script. +## โšก Quick Start -With **Docker** running on your machine, simply execute the following command at the root of the project: +This project is fully containerized and features a unified automation startup script. + +With **Docker** running on your local machine, simply execute the following command at the root of the project: ```bash ./run.sh ``` -This script will completely automate the setup by: -1. Creating a `.env` file from `.env.example` (if it does not exist yet). -2. Starting the PostgreSQL and Redis containers in the background. -3. Installing Composer dependencies. -4. Generating the application encryption key. -5. Running all database migrations and seeding the default accounts. -6. Installing Node.js (NPM) frontend dependencies. -7. Starting the development server (`php artisan serve` + `Vite` + queue listeners + logs) concurrently. +> [!NOTE] +> **What the `run.sh` script automates for you:** +> 1. Verifies/creates a local `.env` configuration file. +> 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) +### ๐Ÿ”ง 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:** ```bash @@ -57,89 +67,82 @@ If you prefer to perform the setup manually: ```bash php artisan migrate --seed ``` -5. **Install frontend dependencies & start dev server:** +5. **Install frontend dependencies & build assets:** ```bash npm install - composer dev + npm run dev ``` +--- -## Default Credentials +## ๐Ÿ” Default Credentials | Role | Email | Password | |---|---|---| -| super-admin | superadmin@biiskit.com | password | -| admin | admin@biiskit.com | password | -| user | user@biiskit.com | password | +| **super-admin** | `superadmin@biiskit.com` | `password` | +| **admin** | `admin@biiskit.com` | `password` | +| **user** | `user@biiskit.com` | `password` | -## Roles & Permissions +> [!IMPORTANT] +> The `super-admin` role bypasses all authorization checks globally via `Gate::before`, allowing you full management control. + +--- + +## ๐Ÿ›ก๏ธ Roles & Permissions Matrix | Permission | super-admin | admin | user | |---|:---:|:---:|:---:| -| user.view | โœ“ | โœ“ | โœ“ | -| user.create | โœ“ | โœ“ | โ€” | -| user.edit | โœ“ | โœ“ | โ€” | -| user.delete | โœ“ | โœ“ | โ€” | -| role.view | โœ“ | โœ“ | โ€” | -| role.manage | โœ“ | โœ“ | โ€” | -| settings.manage | โœ“ | โ€” | โ€” | +| `user.view` | โœ“ | โœ“ | โœ“ | +| `user.create` | โœ“ | โœ“ | โ€” | +| `user.edit` | โœ“ | โœ“ | โ€” | +| `user.delete` | โœ“ | โœ“ | โ€” | +| `role.view` | โœ“ | โœ“ | โ€” | +| `role.manage` | โœ“ | โœ“ | โ€” | +| `settings.manage` | โœ“ | โ€” | โ€” | -`super-admin` bypasses all checks via `Gate::before`. +--- -## Features +## โœจ Key Features in v2 -- **User Management** โ€” CRUD, soft delete, restore, bulk export/import (Excel/CSV), avatar upload -- **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) +* ๐Ÿ‘ค **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`. -## Environment Variables +--- -Key variables beyond the Laravel defaults: - -```env -# Mail (overridable via System Settings UI) -MAIL_MAILER=smtp -MAIL_HOST= -MAIL_PORT=587 -MAIL_USERNAME= -MAIL_PASSWORD= - -# OAuth (Passport) -PASSPORT_PERSONAL_ACCESS_CLIENT_ID= -PASSPORT_PERSONAL_ACCESS_CLIENT_SECRET= -``` - -## API Endpoints (v1) +## ๐Ÿ”Œ API Endpoints (v1) | Method | Endpoint | Auth | Description | |---|---|---|---| -| POST | `/api/v1/login` | โ€” | Get Bearer token (rate-limited: 10/min) | -| POST | `/api/v1/logout` | Bearer | Revoke token | -| GET | `/api/v1/me` | Bearer | Authenticated user with roles & 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 | +| `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 | +| `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 | +| `GET` | `/api/v1/app-config` | โ€” | Retrieve mobile app remote configuration parameters | -Full interactive docs: `GET /documentation` +--- -## Running Tests +## ๐Ÿงช Running Tests + +Ensure all features remain perfectly healthy by running the comprehensive Pest / PHPUnit suite: ```bash php artisan test -# or with coverage: +``` + +Or evaluate coverage scores: +```bash php artisan test --coverage ```