# Architecture Notes

## Tenancy

`stancl/tenancy` initializes tenant context from the request host. Central routes are limited to configured central domains. Tenant routes use:

- `InitializeTenancyByDomain`
- `PreventAccessFromCentralDomains`
- `tenant.context`
- `tenant.subscribed` for paid application surfaces

The default target is multi-database tenancy. If you later choose single-database tenancy, keep the `BelongsToTenant` trait and add `tenant_id` to tenant tables.

## Billing

The central `Tenant` model is the Cashier billable customer. This avoids storing Stripe subscription state in every tenant database and makes suspended/canceled tenant access checks straightforward.

## RBAC

Spatie roles:

- Super Admin
- Agency Admin
- Scheduler
- Caregiver
- Client/Family

Policies should be created for every CRUD model. The included examples cover schedules and EVV logs.

## EVV Flow

1. Caregiver calls `POST /api/tenant/schedules/{schedule}/clock-in`.
2. API validates GPS/telephony payload.
3. EVV log is stored with `verified` or `exception` status based on distance.
4. GPS breadcrumb is stored.
5. `CaregiverLocationUpdated` broadcasts to the private dispatch channel.
6. Dispatch page receives live updates over Reverb.

## Screenshot Functional Mapping

The legacy app examples imply these first-release bounded contexts:

- Agency admin settings and EVV defaults
- Client/caregiver master records
- Schedule planning and matching
- EVV calls and map verification
- Alert/message center
- Reporting and exports

Keep those as separate controllers, policies, and Inertia page folders as the product grows.