# Module 1 Setup Guide — Foundation + User Management

This covers: fresh Laravel project, Breeze auth, Spatie roles, the full database
schema (19 migrations), all 18 models, and an initial admin seeder.

**Where to run this:** on your own machine (or a local/VPS environment with PHP,
Composer, and MySQL) — not directly on Truehost shared hosting. Truehost's shared
plans typically don't give SSH + Composer access. You'll build the app locally,
then upload the finished `vendor/` folder and code via FTP/File Manager. If your
Truehost plan does happen to include SSH, you can run these same commands there
instead — check your hosting dashboard for an SSH/Terminal option first.

---

## 1. Create the project and install dependencies

```bash
composer create-project laravel/laravel patch-ambulance-app
cd patch-ambulance-app

composer require laravel/breeze --dev
php artisan breeze:install blade
npm install && npm run build

composer require spatie/laravel-permission
php artisan vendor:publish --provider="Spatie\Permission\PermissionServiceProvider"
```

## 2. Configure your database

Edit `.env`:

```
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=patch_ambulance
DB_USERNAME=root
DB_PASSWORD=
```

Create the database locally (adjust for your MySQL client):

```bash
mysql -u root -p -e "CREATE DATABASE patch_ambulance CHARACTER SET utf8mb4;"
```

## 3. Drop in the files from this package

Copy the contents of this package into your project, matching the folder structure:

```
database/migrations/*.php   → your project's database/migrations/
app/Models/*.php             → your project's app/Models/ (this REPLACES the default User.php)
database/seeders/*.php       → your project's database/seeders/
```

**Important:** Spatie's `vendor:publish` step above also creates its own
permission-table migration in your migrations folder — that's expected and
should run alongside the 19 migrations included here.

## 4. Register the seeder

Open `database/seeders/DatabaseSeeder.php` and add:

```php
public function run(): void
{
    $this->call([
        RolesAndAdminSeeder::class,
    ]);
}
```

## 5. Run migrations and seed

```bash
php artisan migrate
php artisan db:seed
```

This creates all 20 tables (19 from this package + Spatie's permission tables)
and one admin account:

```
Email:    admin@patchambulance.co.ke
Password: ChangeThisPassword123!
```

**Change this password immediately after your first login** — it's a placeholder,
not meant for production use.

## 6. Verify it worked

```bash
php artisan tinker
```

```php
>>> \App\Models\User::first()->getRoleNames();
=> Illuminate\Support\Collection {#... items: ["admin"]}
```

If that prints `["admin"]`, roles and the seeder are wired correctly.

## 7. Deploying to Truehost (once you're ready)

1. Run `composer install --optimize-autoloader --no-dev` locally to build a
   production-ready `vendor/` folder (no dev dependencies).
2. Run `npm run build` to compile final CSS/JS assets.
3. Upload the entire project via FTP/File Manager. Point Truehost's document
   root at the `public/` folder (cPanel usually has a way to set this, or you
   symlink/redirect — check with Truehost support if this isn't obvious in
   your control panel).
4. Set up your `.env` on the server with live MySQL credentials (Truehost
   gives you these from cPanel → MySQL Databases).
5. Run migrations on the live database — if you don't have SSH, most hosts
   let you run a one-off PHP script or use phpMyAdmin to import a SQL dump
   instead. I can generate a raw SQL export of these migrations if your
   Truehost plan turns out to have no SSH access at all — let me know once
   you've confirmed what your plan supports.

---

## What's in this module

**19 migrations** covering the full schema: users (extended), ambulance_types,
zones, ambulances, ambulance_equipment, customers, drivers, dispatchers,
hospitals, corporate_accounts, bookings, booking_updates, driver_locations,
pricing_rules, payments, app_notifications, trip_feedback, settings, audit_logs.

**18 models**, each matching a table, with relationships wired between them
(e.g. `Booking belongsTo Customer`, `Ambulance hasMany AmbulanceEquipment`).
Two models carry real logic already, not just boilerplate:

- **`Zone`** and **`Ambulance`** both have a `distanceToPoint()` / haversine
  helper — this is what Module 3 (Booking + Fare Engine) will use to figure out
  which pricing zone a pickup falls into, and what Module 4 (Dispatch) will use
  for the nearest-ambulance suggestion.
- **`Booking`** auto-generates its `booking_number` (`AMB-2026000001` style) and
  a `tracking_token` (UUID) on creation — that token is what powers the
  shareable `/track/{uuid}` link we discussed, with no login required.

**1 seeder** creating the four roles (admin, dispatcher, driver, customer) and
one initial admin login so you can access the admin panel from day one.

---

## Next module

**Module 2: Fleet Management** — CRUD controllers/views for ambulances, types,
and equipment, plus the admin screens to add/manage your fleet. Say the word
when you're ready and I'll build that next, following the same pattern.