146 lines
4.8 KiB
Markdown
146 lines
4.8 KiB
Markdown
# 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:
|
|
|
|
```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.
|
|
|
|
---
|
|
|
|
### Manual Setup (Without Automation Script)
|
|
|
|
If you prefer to perform the setup manually:
|
|
|
|
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 & start dev server:**
|
|
```bash
|
|
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:
|
|
|
|
```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)
|
|
|
|
| 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
|
|
|
|
```bash
|
|
php artisan test
|
|
# or with coverage:
|
|
php artisan test --coverage
|
|
```
|