# Homecare EVV SaaS Laravel 11 Scaffold

Production-oriented starter scaffold for a multi-tenant homecare SaaS inspired by the functional areas in the provided screenshots: clients, caregivers, schedules, EVV calls, GPS map verification, messages/alerts, reports, and admin settings.

This is an architecture overlay for a fresh Laravel 11 application. Create the Laravel app, then copy or keep these files in place and install the listed packages.

## Stack

- Laravel 11, PHP 8.3+
- Inertia.js, React, TypeScript
- Tailwind CSS, shadcn/ui, lucide-react
- stancl/tenancy for domain/subdomain tenancy
- Laravel Cashier for Stripe billing
- spatie/laravel-permission for RBAC
- Laravel Reverb for real-time GPS/EVV updates

## Install Sequence

```bash
composer create-project laravel/laravel homecare-saas "^11.0"
cd homecare-saas
composer require inertiajs/inertia-laravel laravel/cashier laravel/reverb stancl/tenancy spatie/laravel-permission tightenco/ziggy
composer require laravel/breeze --dev
php artisan breeze:install react --typescript
php artisan install:broadcasting
php artisan tenancy:install
php artisan vendor:publish --tag="cashier-migrations"
npm install lucide-react class-variance-authority clsx tailwind-merge @radix-ui/react-slot
```

Then merge this scaffold into the generated app and run:

```bash
php artisan migrate
php artisan tenants:migrate
php artisan db:seed --class=RolePermissionSeeder
```

The scaffold includes tenant-side Spatie-compatible permission tables in `database/migrations/tenant`; do not also run the default Spatie migration centrally unless you want central-office roles too.

## Folder Structure

```text
app/
  Enums/RoleName.php
  Events/CaregiverLocationUpdated.php
  Http/
    Controllers/Billing/*
    Controllers/Tenant/*
    Middleware/BindTenantContext.php
    Middleware/EnsureTenantIsSubscribed.php
  Models/
    Concerns/BelongsToTenant.php
    Caregiver.php
    Client.php
    EvvLog.php
    GpsBreadcrumb.php
    Schedule.php
    SubscriptionPlan.php
    Tenant.php
    User.php
  Policies/*
  Providers/AuthServiceProvider.php
bootstrap/
  app.php
  providers.php
config/
  tenancy.php
database/
  migrations/* central migrations
  migrations/tenant/* tenant migrations
  seeders/RolePermissionSeeder.php
routes/
  web.php
  tenant.php
  api.php
  channels.php
resources/js/
  Layouts/AuthenticatedLayout.tsx
  Pages/Billing/Plans.tsx
  Pages/Tenant/Dashboard/Dispatch.tsx
```

## Domain Model

- Central app: `app.yourdomain.com`, `admin.yourdomain.com`
- Tenant app: `{agency}.yourdomain.com`
- Each tenant has one or more `domains` rows, so custom domains can be added later.
- Stripe customer and subscription records live on the central `tenants` table.
- Operational PHI-like data lives in tenant databases when multi-database mode is enabled.

## Functional Modules From Screenshots

- Home dashboard: actionable module launcher and alert counts.
- Clients: client master list, payors, physicians, referral sources, wellness questions.
- Caregivers: credentialing, applicant list, notes, payroll fields, reminders.
- Schedule: day/week/month/grid views and schedule matching.
- Timesheets: create/edit/maintain weeks and invoicing exports.
- EVV: schedules, calls, alert log, audit trail, messaging, GPS map verification.
- Admin: company settings, security, EVV defaults, audit logs, notifications.

## Operational Notes

- Use HTTPS-only cookies and HSTS in production.
- Queue broadcasts and Stripe webhook work.
- Put Reverb behind a process manager.
- Encrypt or minimize sensitive EVV metadata where regulation or customer contract requires it.
- Add audit tables for schedule edits, EVV exception resolution, and user access before launch.