# Bhoza Shift Manager

A shift management application for scheduling staff, tracking attendance, and generating timesheets. Built with Laravel 11 and Filament 3.

## Features

- **Shift Lifecycle** — Create, start, and complete shifts (planned → in_progress → completed)
- **Staff Roster** — Assign/remove staff to shifts
- **Attendance Tracking** — Mark attendance (present/absent/not_marked)
- **Active Shifts Dashboard** — Real-time view of in-progress shifts
- **Reports** — Filter by date, staff, and status
- **Timesheets** — Generate employee timesheets
- **Audit Trail** — Full history of all shift and attendance changes
- **Role-Based Access** — Admin, manager, editor, viewer roles with granular permissions

## Tech Stack

| Layer | Technology |
|-------|------------|
| Backend | Laravel 11, PHP 8.2+ |
| Admin Panel | Filament 3.3 |
| Frontend | Blade + Livewire |
| Database | MySQL 8 / PostgreSQL 16 / SQLite |
| Permissions | spatie/laravel-permission |
| Auditing | owen-it/laravel-auditing |
| API Auth | Laravel Sanctum |
| Testing | Pest |

## Quick Start

### Prerequisites
- Docker & Docker Compose

### Setup

```bash
git clone <repo-url> bhoza-shift-manager
cd bhoza-shift-manager

# Run setup (MySQL is default)
./setup.sh          # Linux/Mac
setup.bat           # Windows
```

### Access

| URL | Description |
|-----|-------------|
| http://localhost:8080/admin | Admin panel |
| http://localhost:8025 | Mailpit (email testing) |

**Default login:** admin@example.com / password

## Roles & Permissions

| Role | Access |
|------|--------|
| **admin** | Full access to everything |
| **manager** | All shift operations + reports + timesheets |
| **editor** | User view/edit |
| **viewer** | Read-only user list |

### 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`

## Project Structure

```
src/
├── app/
│   ├── Models/
│   │   ├── Shift.php              # Core shift model
│   │   ├── ShiftStaff.php         # Staff assignment pivot
│   │   ├── ShiftAttendance.php    # Attendance records
│   │   ├── User.php               # User with shift relationships
│   │   └── Setting.php            # Site settings
│   ├── Services/
│   │   └── ShiftService.php       # Business logic
│   ├── Policies/
│   │   └── ShiftPolicy.php        # Authorization
│   ├── Filament/
│   │   ├── Resources/
│   │   │   ├── ShiftResource.php  # Shift CRUD + pages
│   │   │   └── UserResource.php   # User management
│   │   ├── Pages/
│   │   │   ├── ActiveShifts.php   # In-progress shifts dashboard
│   │   │   ├── ShiftReports.php   # Report generator
│   │   │   ├── Timesheets.php     # Timesheet generation
│   │   │   ├── StaffManagement.php
│   │   │   └── Settings.php       # Site settings
│   │   └── Widgets/
│   │       ├── TodaysShifts.php
│   │       └── ShiftOverview.php
│   └── Providers/
├── database/
│   ├── migrations/
│   └── seeders/
│       ├── DatabaseSeeder.php
│       └── RolePermissionSeeder.php
├── resources/views/filament/       # Filament page views
├── routes/
│   ├── web.php                     # Redirects to /admin
│   └── api.php                     # API routes
└── tests/
```

## Common Commands

| Command | Description |
|---------|-------------|
| `make up DB=mysql` | Start containers |
| `make down` | Stop containers |
| `make shell` | Shell into app container |
| `make artisan cmd='migrate'` | Run Artisan commands |
| `make fresh` | Fresh migrate + seed |
| `make test` | Run tests |
| `make lint` | Fix code style |