SP

Admin Guide

Admins have full access to all modules across all branches. This guide walks through every administrative workflow.

1. Logging In

Navigate to /admin/login. Use the credentials created at registration. If you have not yet created an admin account, visit /admin/register on first setup.

After login you are taken to the Admin Dashboard.

2. Dashboard

After logging in, the dashboard shows two rows of live stats for the currently selected branch.

Primary stats — Open Tasks, Day Rentals, Point Rentals, Customers.

Operational stats:

  • Pending Bookings — amber card; click it to jump directly to the filtered booking list
  • Active Items Out — combined count of all unreturned day + point rental items with a breakdown subtitle
  • Overdue Items — turns red with a red border when any items are past their due date
  • Revenue This Month — GHS sum of all payments collected this calendar month across day and point rentals

Bottom panels:

  • Recent Pending Booking Requests — the last 5 pending requests with customer name, type, item count, preferred start date, and a direct Review link
  • Due for Return Today — all unreturned items whose due_date is today, showing equipment name, serial number, customer name, and a View link to the rental

3. Branch Management

Everything in the system is scoped to a branch. Before doing anything else, ensure you have at least one branch and have selected it.

Create a branch

  1. Go to Branches in the sidebar
  2. Click Add Branch
  3. Enter the branch name and save

Switch branch

Use the branch switcher on the dashboard header. Your selected branch is stored for the session — all data you see and create will belong to this branch.

4. Managing Users

Customers

  • Branches → Customers → All Customers — view, edit, search
  • Add Customer — create a new customer account manually. A password is not required; customers log in via phone OTP
  • Customer history (rentals, point rentals, projects) is visible on their profile

Workers

  • Admins & Workers → Workers — full CRUD
  • Workers log in at /worker/login
  • Password resets are done by admins from the worker's edit page

Admins

  • Admins & Workers → Admins — add/remove admin accounts
  • Only admins can create other admins

5. Equipment & Inventory

Categories

Two category trees exist: Day Rental Categories and Point Rental Categories. Categories are purely organisational.

Equipment

Equipment represents a type of item (e.g., "Total Station", "GPS Receiver"). It belongs to a category. Multiple individual units of the same equipment type are managed as Specifications.

Specifications

A specification is a single physical unit (serial number). It has:

  • Serial number
  • Condition (new, good, fair, poor)
  • Status (available, rented, under_repair)
  • Price (price_per_day for day equipment, price_per_point for point equipment)
  • Last maintenance date

Important: Only specifications with status available will appear in the Rental POS and in customer booking requests. Set a specification to under_repair when it is out of service so it disappears from both. Equipment is not reserved when a booking is submitted — availability is checked at the time of approval.

6. Booking Requests

The Booking Requests module lets you review equipment requests submitted by customers from their portal.

When a customer submits a request, an SMS is sent immediately to the customer and to every worker at the branch with a phone number, so all staff are aware of new requests right away.

Viewing requests

Go to Bookings → Booking Requests in the sidebar. The sidebar badge shows the live count of pending requests for the current branch.

Use the status filter tabs (All / Pending / Approved / Rejected / Cancelled) to narrow the list.

Bulk actions from the list

On the Booking Requests list page, pending bookings show a checkbox in the first column. Select one or more, and a toolbar appears at the top of the table:

  • Approve Selected — confirms via a SweetAlert dialog, then approves all selected bookings in sequence. Each approval creates the rental, marks equipment as rented, and sends the customer an SMS. Any booking that cannot be approved (e.g. an item is no longer available) is skipped and reported in the error banner.
  • Reject Selected — opens a modal where you enter a single rejection reason that applies to all selected bookings.

Approving a single booking

  1. Click View on a pending request
  2. Review the customer's details, requested equipment, duration, and notes
  3. Check the estimated total at the bottom of the items table
  4. Click Approve & Create Rental
  5. Confirm in the dialog

What happens automatically:

  • The system checks every item is still available inside a database transaction — if any item is no longer available the approval is blocked with an error message
  • A Rental or PointRental record is created with all items
  • Each specification's status is set to rented
  • The booking is linked to the new rental
  • An SMS is sent to the customer's phone confirming approval
  • An audit log entry is recorded

After approval, a View Rental link appears on the booking detail page so you can jump straight to the created rental and make any adjustments (add payments, record deposit, etc.).

Rejecting a single booking

  1. On the booking detail page, fill in the Rejection Reason field
  2. Click Reject Request
  3. Confirm in the dialog

What happens automatically:

  • The booking status is set to rejected with the reason stored
  • An SMS is sent to the customer with the rejection reason
  • An audit log entry is recorded

Booking auto-expiry

Pending bookings that are not acted on within 3 days are automatically rejected by the app:auto-expire-bookings scheduled command (runs nightly at 02:00). The customer receives an SMS letting them know the request expired and to contact the branch to resubmit.

7. Rental POS (Day Rentals)

Creating a rental

  1. Go to Daily Rentals → Rental POS
  2. Search for a customer
  3. Add equipment items (by serial number)
  4. Set the duration (days) per item — the price calculates automatically
  5. Optionally enter a discount, amount paid upfront, and a deposit
  6. Submit

Viewing a rental

The rental show page (admin/rental-pos/{id}) displays:

  • All rented items with due dates, returned status, and item-level fees
  • Payment history
  • Financial summary with colour-coded balance row
  • Deposit card with a Return Deposit button (shown only if deposit is > 0 and not yet returned)
  • Action buttons: Download PDF, Process Return, Record Payment

Recording a payment

Click Record Payment on the rental show page. A modal appears. Enter:

  • Amount
  • Payment method (Cash / Mobile Money / Bank Transfer / Other)
  • Notes (optional)

Submit — total_paid is recalculated automatically.

Returning items

Click Process Return → you are taken to the rental items edit view where you can mark individual items as returned and enter any damage fees.

Returning the deposit

Click Return Deposit on the rental show page. Confirm in the SweetAlert dialog. The system records deposit_returned = true and stamps deposit_returned_at.

Extending a rental

If a customer needs to keep equipment for longer, click Extend Rental on the rental show page (shown only when unreturned items exist). Enter the number of extra days. The system:

  • Extends the due date of every unreturned item
  • Adds extra_days × price_per_day per item to total_price
  • Records an audit log entry

Only unreturned items are extended; items already handed back are unaffected.

PDF receipt

Click Download PDF to generate a printable receipt showing customer details, all items, fees, payment history, and totals.

8. Point Rental POS

How point rental pricing works

Point rentals use a deferred pricing model. When equipment is rented out, the price is set to zero because the final charge depends on how many survey points the customer plots in the field. Only when the customer returns the equipment and a worker enters the number of points does the system calculate the final amount as points × price_per_point.

Creating a point rental

Access via Point Rentals → Point Rental POS. Select the customer, add equipment units by serial number, and set the expected duration in days (used only to calculate the due date, not the price). Submit — units are marked as rented and the rental record is created with price = 0.

Returning point rental equipment

Open the point rental's edit view, click Return on each item, enter the number of points plotted, any damage fee, and any late fee. The system calculates (points × price_per_point) + damage_fee + late_fee in real time before you confirm.

9. Returns Processing

Day rental items

Go to Daily Rentals → Rented Equipments → All Rented Equipments. Edit the item, mark it as returned, and the specification status reverts to available.

Point rental items

Same workflow under Point Rentals → Point Rented Items.

10. Equipment Availability

Go to Operations → Equipment Availability.

  • Select a From and To date and click Check
  • The page shows four tables: Available / Rented for both day and point equipment
  • An item appears as "rented" if it has a RentalItem or PointRentalItem with no returned_at date

Use this before creating a rental to confirm a specific unit is free. Workers also have access to this page at /worker/availability.

11. Maintenance Logs

Go to Operations → Maintenance.

Creating a log

  1. Click New Log
  2. Select equipment type (day or point)
  3. Choose the specification
  4. Set type (Routine / Repair / Inspection)
  5. Set status (Scheduled / In Progress / Completed)
  6. Optionally enter start and completion dates
  7. Save

Logs appear in the paginated table with status colour-codes. Edit or delete from the action column.

Tip: When an item goes in for repair, manually set the specification's status to maintenance so it is hidden from the POS and booking form.

12. Reports & Exports

Go to Reports → Financial Reports.

Report What it shows
Revenue Summary Total income by branch and period
Outstanding Balances Rentals with unpaid balance > 0
Overdue Items Items past their due date that haven't been returned
Equipment Revenue Income per equipment type
Customer Statements Per-customer balance across all rentals
Worker Performance Per-worker approvals, rejections, and revenue generated for a chosen date range

CSV exports are available on the Outstanding, Overdue, and Customer Statements pages. Click the Export CSV button — no server-side file is stored; the file downloads directly.

13. Audit Log

Go to Reports → Audit Log.

Filter by:

  • Action — dropdown of all distinct action types recorded
  • From / To — date range

The audit log records:

  • Every rental created or updated
  • Every booking approved or rejected
  • Every deposit returned
  • Any other AuditService::log() calls in the codebase

Records are read-only from the UI.

14. Tasks & Projects

Projects

  • Customers & Uploads → Projects — create and manage projects
  • Assign a project to a customer so they can view it from their portal
  • Upload files (PDFs, images, reports) for the customer to download

Tasks

  • Tasks → All Tasks — full task list for the current branch
  • Tasks → My Tasks — tasks assigned to you
  • Assign tasks to workers; workers update status and leave comments

15. Global Search

A search bar is available in the top navigation bar on every admin page. Type any of the following and press Enter:

  • Customer name, phone, or email
  • Rental or Point Rental ID (numeric)
  • Equipment serial number
  • Booking Request ID or customer name

Results are grouped by type. Each result has a direct link to the record. Searches are scoped to the currently selected branch.

16. Waitlist

Go to Bookings → Waitlist (or /admin/waitlist).

When a customer joins the waitlist for a rented-out item, the entry appears here. The sidebar badge shows the current count of waiting entries.

Column Description
Customer Name and phone
Type Day or Point rental
Equipment Name and serial number
Status waiting, notified, fulfilled, or cancelled
Notified At Timestamp when the customer received an SMS

Filters: Use the status tabs and type buttons to narrow the list.

Cancellation: Click Cancel on any waiting or notified entry to remove it. The customer is not notified when staff cancel their entry.

Automatic notification: When any specification's status changes to available (after a return, bulk return, or manual edit) the system automatically sends an SMS to all customers waiting for that serial. You don't need to do anything manually.

17. Branch Transfers

Go to Operations → Branch Transfers (or /admin/specification-transfers).

Use this to physically move a piece of equipment from the current branch to another branch. Only equipment with status available can be transferred.

To initiate a transfer:

  1. Choose Day or Point rental type
  2. Select the specific serial number from the dropdown
  3. Choose the target branch
  4. Optionally add notes (reason, driver name, etc.)
  5. Click Transfer Equipment

The equipment's branch_id is updated immediately and the item disappears from the current branch's inventory. The transfer is recorded in the history table on the right side with direction badges:

  • Out → (amber) — sent to another branch
  • ← In (green) — received from another branch

Every transfer is also written to the Audit Log.

18. Profile & Password

Go to Admin Profile (top-right dropdown or /admin/profile).

  • Update name, username, email
  • Change password (current password required)
Previous
Features
Next
Worker Guide