# AI Assistant Context — Bhoza Shift Manager

## What This App Does

Bhoza Shift Manager handles shift scheduling, staff assignment, attendance tracking, and timesheet generation. The entire UI is the Filament admin panel at `/admin`.

## Technology Stack

| Layer | Technology |
|-------|------------|
| Backend | Laravel 11, PHP 8.2+ |
| Frontend | Blade + Livewire (NO Vue/React/Inertia) |
| Admin Panel | Filament 3.3 |
| Database | MySQL 8 / PostgreSQL 16 / SQLite |
| Permissions | spatie/laravel-permission 6.x |
| Audit | owen-it/laravel-auditing 14.x |
| API Auth | Laravel Sanctum |
| Testing | Pest |

## Domain Model

### Shift Lifecycle
```
planned → in_progress → completed
```

### Core Models

- **Shift** — Title, date, planned/actual times, status, notes, creator, starter
- **ShiftStaff** — Junction table linking users to shifts
- **ShiftAttendance** — Attendance records per shift per staff (present/absent/not_marked)
- **User** — Extended with shift relationships + HasRoles
- **Setting** — Key-value site configuration

### Relationships
- Shift belongsTo creator (User), starter (User)
- Shift belongsToMany staff (User) via shift_staff
- Shift hasMany attendances (ShiftAttendance)

## Business Logic

All shift operations go through `app/Services/ShiftService.php`:

- `createShift()` / `quickStartShift()`
- `startShift()` / `completeShift()`
- `assignStaff()` / `removeStaff()`
- `markAttendance()` / `bulkMarkAttendance()`
- `getShiftReport()` / `getTimesheet()`

## Roles & Permissions

**Roles:** admin, manager, editor, viewer

**Shift Permissions:** shifts.view, shifts.create, shifts.edit, shifts.delete, shifts.start, shifts.complete, shifts.manage_roster, shifts.mark_attendance, shifts.view_reports, shifts.generate_timesheets

**User Permissions:** users.view, users.create, users.edit, users.delete, settings.manage

## Key File Locations

| What | Where |
|------|-------|
| Models | `src/app/Models/` |
| Business logic | `src/app/Services/ShiftService.php` |
| Authorization | `src/app/Policies/ShiftPolicy.php` |
| Filament resources | `src/app/Filament/Resources/` |
| Filament pages | `src/app/Filament/Pages/` |
| Filament widgets | `src/app/Filament/Widgets/` |
| Filament views | `src/resources/views/filament/` |
| Migrations | `src/database/migrations/` |
| Seeders | `src/database/seeders/` |
| Routes | `src/routes/` |
| Tests | `src/tests/` |

## Architecture Notes

- The root `/` route redirects to `/admin`
- Filament handles all authentication (login at `/admin/login`)
- No Breeze auth scaffolding — Filament has its own auth
- Admin panel configured in `app/Providers/Filament/AdminPanelProvider.php`
- Module system available via `php artisan make:module` for future features

## Code Conventions

- Business logic goes in **Services**, not Controllers
- Use **Policies** for authorization
- Use **Filament Resources** for admin CRUD
- Follow Laravel naming conventions
- No JavaScript frameworks — Blade + Livewire only

## Development

```bash
make shell                           # Enter container
php artisan migrate                  # Run migrations
php artisan db:seed                  # Seed roles/permissions
php artisan db:seed --class=RolePermissionSeeder  # Re-seed permissions
```

## Debugging

1. Check `storage/logs/laravel.log` first
2. Container logs: `make logs`
3. Ignition error pages in browser when `APP_DEBUG=true`