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