# DMS Core: install notes

Targets Laravel 11/12, PHP 8.2+, Tailwind CSS v4 (default in new Laravel 12 apps), MySQL 8 or SQLite.

## 1. Copy files into a fresh Laravel app
Copy `app/`, `config/`, `database/`, `resources/`, `routes/web.php`, `tests/` over the skeleton.
Merge `bootstrap/app.php` (the `withMiddleware` block registers the `role`, `permission`, `active`, `branch` aliases).

## 2. Remove what this replaces
- Delete `database/migrations/0001_01_01_000000_create_users_table.php` (ours creates users, password resets and sessions).
- Keep the default cache and jobs migrations.

## 3. Install, migrate, seed
```bash
composer install
npm install alpinejs && npm install && npm run build
cp .env.example .env && php artisan key:generate
# .env: DB_*, SESSION_DRIVER=database, APP_TIMEZONE=Africa/Nairobi, DMS_ADMIN_EMAIL=you@yourdealership.co.ke
php artisan migrate --seed
php artisan test
```
If you seed without `DMS_ADMIN_PASSWORD`, a random Super Admin password is printed once.

## 4. Using the access control
```php
Route::middleware('role:branch_manager,finance_accountant')->get(...);   // any listed role
Route::middleware('permission:vehicles.change_price')->post(...);        // any listed permission
@can('deals.view_margin') ... @endcan                                    // Blade
```
Branch-owned models (vehicles, leads, deals...) just need a `branch_id` column and `use BelongsToBranch;`.
Add `use Auditable;` to any model that must appear in the audit log.

## Design decisions to review
- Roles are fixed (PRD), permissions are editable per role in the DB. A role-permission admin screen is a later task.
- `users.branch_id` is the home branch; `branch_user` grants extra branches. There is no `branches.manager_id`: the manager is the active `branch_manager` user of that branch (avoids a circular foreign key, which SQLite cannot add after table creation).
- `settings.branch_scope` exists so the unique index works with NULL branch ids.
- Not yet verified on a running Laravel install in this session. Run `php artisan migrate:fresh --seed` and `php artisan test` first.