bhoza-shift-manager/AI_CONTEXT.md

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

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