Setup & Installation

1. Requirements

2. Installation

2.1 Clone the repository

git clone <repository-url>
cd surveyor-pos

2.2 Install PHP dependencies

composer install

2.3 Install frontend dependencies

npm install

2.4 Configure environment

cp .env.example .env
php artisan key:generate

Open .env and set your database credentials:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=surveyor_pos
DB_USERNAME=root
DB_PASSWORD=your_password

2.5 Run migrations

php artisan migrate

2.6 Build frontend assets

npm run build

For local development with hot-reload:

npm run dev
# or
composer run dev

2.7 Create the storage symlink

php artisan storage:link

2.8 Start the server

php artisan serve

The application is now accessible at http://localhost:8000.

3. First-Time Admin Account

There is no default seeded admin. Create the first admin account by registering at:

/admin/register

After creation, disable public registration by removing the admin register route (or protecting it) if needed.

4. Branch Setup

The system is branch-scoped — all data (rentals, equipment, customers, etc.) belongs to a branch. Create at least one branch before creating any other data:

1. Log in as admin
2. Go to Branches → Add Branch
3. Select your active branch from the dashboard using the branch switcher

5. SMS — Wigal Configuration

Surveyor POS uses the Wigal SMS API to send booking notifications and OTP verifications. Add these keys to your .env:

WIGAL_BASE_URL=https://frogapi.wigal.com.gh
WIGAL_API_KEY=your_api_key_here
WIGAL_USERNAME=your_wigal_username
WIGAL_SENDER_ID=BDT

SMS is sent:

• When a booking request is submitted (to the customer confirming receipt, and to all branch workers with a phone number)
• When a booking request is approved (to the customer)
• When a booking request is rejected (to the customer, includes the reason)
• When a rental item is due tomorrow (daily reminder to the customer)
• When a rental item is overdue (daily notice to the customer including the current late fee amount in GHS)
• When a phone number OTP is needed for verification

If WIGAL_API_KEY is blank, SMS calls will fail silently (logged to storage/logs/laravel.log) and will not break the application.

6. Scheduled Commands

Two Artisan commands run on the scheduler. Add a single cron entry to your server:

* * * * * cd /path/to/surveyor-pos && php artisan schedule:run >> /dev/null 2>&1

To test a command manually:

php artisan app:send-rental-reminders
php artisan app:calculate-rental-late-fees

7. Queue Configuration

By default the queue driver is sync (jobs run immediately, in-process). This is fine for small workloads. For production with high volume, switch to a real driver:

QUEUE_CONNECTION=database

Then run:

php artisan queue:table
php artisan migrate
php artisan queue:work

8. PDF Receipts

PDF generation uses barryvdh/laravel-dompdf. No additional binary installation is needed — it is a pure PHP renderer. Ensure the storage/ directory is writable.

9. Route Cache (Production)

Do not run route:cache in local development — it creates a compiled snapshot and any new routes added to web.php will be invisible until the cache is cleared.

In production:

php artisan route:cache
php artisan config:cache
php artisan view:cache

To clear all caches:

php artisan optimize:clear

10. Running Tests

php artisan test

To run a specific test file:

php artisan test tests/Feature/ExampleTest.php

To filter by test name:

php artisan test --filter=testName