biiproject-kit-v2/README.md

biiproject kit

A production-ready Laravel + Inertia.js starter kit with full RBAC, API auth, activity logging, and system settings — built to ship fast.

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

Quick Start

This project is fully containerized and features an automated startup script.

With Docker running on your machine, simply execute the following command at the root of the project:

./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.

---

Manual Setup (Without Automation Script)

If you prefer to perform the setup manually:

1. Spin up database & cache services:

   docker compose up -d
   

2. Install backend dependencies:

   composer install
   

3. Setup environment configuration:

   cp .env.example .env
   php artisan key:generate
   

4. Run migrations and seed default users:

   php artisan migrate --seed
   

5. Install frontend dependencies & start dev server:

   npm install
   composer dev
   

Default Credentials

Role	Email	Password
super-admin	superadmin@biiskit.com	password
admin	admin@biiskit.com	password
user	user@biiskit.com	password

Roles & Permissions

Permission	super-admin	admin	user
user.view	✓	✓	✓
user.create	✓	✓	—
user.edit	✓	✓	—
user.delete	✓	✓	—
role.view	✓	✓	—
role.manage	✓	✓	—
settings.manage	✓	—	—

super-admin bypasses all checks via Gate::before.

Features

• 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)

Environment Variables

Key variables beyond the Laravel defaults:

# 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)

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

Full interactive docs: GET /documentation

Running Tests

php artisan test
# or with coverage:
php artisan test --coverage