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 Desktop installed
• Docker Compose (usually included with Docker Desktop)

Quick Start

1. Clone the repository:

   git clone <your-repo-url>
   cd bhoza-shift-manager
   

2. Copy the example environment file:

   cp src/.env.example src/.env
   # Or manually create src/.env based on src/.env.example
   

3. Start the app with MariaDB:

   docker-compose --profile mysql up -d
   

   This will start the app, Nginx, MariaDB, Redis, and Mailpit containers.

4. Install Composer dependencies:

   docker-compose exec app composer install
   

5. Generate the application key:

   docker-compose exec app php artisan key:generate
   

6. Run database migrations and seeders:

   docker-compose exec app php artisan migrate --seed
   

7. Access the app:

   • Web: http://localhost:8080
   • Admin: http://localhost:8080/admin/login
   • Mailpit: http://localhost:8025

Setup(Maybe you should run the one above 🤷🏿‍♂️)

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