Crew Fleet Manager — User Manual

Getting started

There are two front doors into the system. Which one you use depends on your role.

Both apps share the same sign-in: your work email and password. Open the correct address for your role, enter your credentials, and select Login (console) or Log In (portal). If you're logged into one, the other will ask you to sign in again — they're separate apps.

Who uses what

Five roles, two apps. This is the shape of the whole system in one table.

Dashboard

The landing page after login. Four numbers, updated live.

• Total Vehicles — vehicles registered in the fleet, active or not.
• Active Crews — crew members currently marked active.
• Active Trips — trips in progress right now.
• API Status — a quick self-check that the backend is reachable. ✓ Healthy means everything behind the scenes is working; anything else, contact your administrator before relying on the rest of the app.

Users

Every account that can sign into the admin console or the portal — dispatchers, hub managers, drivers, and crew members with login access — is managed here.

Add a user

1. Select Add User.
2. Enter their first name, last name, and work email.
3. Choose a role: Hub Manager, Dispatcher, Driver, or Crew Member.
4. Select Save User. A temporary password is generated for their first login.

Edit or deactivate

Select Edit on any row to change their name, email, or role. Select Deactivate to immediately block their login without deleting their history — useful when someone leaves, without losing the trips or records tied to their account. Activate reverses it.

Vehicles

The registry of every cab and van in the fleet, whether company-owned or contracted from a vendor.

Add a vehicle

Select Add Vehicle and fill in registration number, make, model, year, seating capacity, vehicle type (sedan, SUV, or van), fuel type, and current odometer reading. Set Ownership correctly:

• Company Owned — your own fleet vehicle.
• Vendor Leased — contracted from an outside operator. This is what makes the vehicle show up for invoicing later, so get it right at entry.

Status colors

Crew

Everyone who needs a ride to or from a shift: employee ID, contact details, designation, department, and — critically — their home address as latitude/longitude.

Use Add Crew to register someone new, Edit to update their details, and Deactivate to remove them from future rostering without deleting their trip history.

Hubs

Hubs are the fixed pickup/drop points — depots, offices, stations — that anchor every route. Each one has a code, name, address, coordinates, and a processing time in minutes: how long crew typically take to sign on or off once they arrive, which routing uses to avoid over-tight schedules.

Routing

This is the heart of the day's work: turning a list of scheduled crew into vehicles with routes and drivers.

Run the automatic scheduler

The fastest path for a normal day: select Run Scheduler under Automatic Scheduler. It clusters every crew member rostered for the selected date and assigns vehicles in one pass. This is the same logic that runs on its own every night for the next day — use the button when you need it sooner, or need to re-run it after a late roster change.

Work a cluster by hand

Under Clusters (Pickup Groups), pick a date and select Load Clusters. Each row is one pickup group, showing its hub, shift, crew count, and status.

• View / Edit opens the cluster's member list — add a crew member the automatic pass missed, or remove one who's no longer riding.
• Optimize Route reorders the stops for the shortest drive.
• Assign Vehicle (once optimized) opens a picker for vehicle and driver.

Open Vehicle Assignments is a shortcut to the Vehicles page for a broader view of who's driving what today.

Tracking

A live map of every vehicle currently on a trip, plotted against hub locations, alongside a status table of vehicle, driver, current trip, and how many crew are onboard. Tick Auto-refresh (10s) to keep it current without manually reloading — useful to leave running on a dispatch desk screen.

Cab Requests

Ad-hoc pickup or drop requests that fall outside the planned roster — a late shift change, a one-off need. Crew submit these themselves from the portal; you review them here.

For each pending request, Approve or Reject. Either action notifies the crew member automatically — see Notifications. Approving doesn't create a vehicle assignment by itself; treat it as confirming the ride is needed, then route it through Routing & clustering or a manual trip as your process requires.

Invoices

Billing for vendor-leased vehicles. Select Generate Invoice, choose the vehicle and a billing period (start and end date), and the system totals up trips run in that window. Use View for a line-item breakdown or Print for a print-ready copy.

Reports

Planned vs. actual utilization

Set a date range and select Apply. For every vehicle, this compares the distance the route was planned for against what the driver's odometer and the vehicle's GPS actually recorded — trips run, completed, planned km, actual km, and the deviation between them. A large, consistent deviation on one vehicle is usually worth a closer look: a longer real-world route, detours, or an odometer entry error.

Activity history

A searchable audit log of who changed what — filter by entity type (e.g. vehicles) or action (e.g. vehicle.updated) and select Apply. Step through results with Previous / Next.

Settings

System-wide configuration grouped by area — billing terms and tax rate, clustering limits and time windows, and other values that shape how routing and invoicing behave. Edit a value and select Save next to it.

Driver portal

Everything a driver needs, in the order a shift actually happens.

1. Find today's trips

After logging in, the Date field defaults to today. Change it to check a different day. Each card shows the vehicle, number of stops, and current status — tap one to open it.

2. Start the trip

Enter the vehicle's current odometer reading in Start Odometer (km). A photo of the odometer is optional but recommended — it backs up the reading if it's ever questioned. Select Start Trip. Your location is recorded at this moment.

3. Work the stops

The Stops list shows every crew member on this route, in driving order. As you reach each one, mark them Picked Up or Dropped. If someone isn't there, use No-Show instead of skipping them silently — it keeps the record accurate and lets dispatch follow up.

4. Complete the trip

Once every stop is handled, enter the End Odometer (km) reading (again, a photo is optional), add any notes about the trip, and select Complete Trip. The distance you logged becomes part of the utilization report dispatchers see.

Crew portal

What a crew member sees and can do, start to finish.

Today's roster

After logging in, your card shows whether you're rostered for the selected date, which hub and shift, and your current status (Scheduled, Picked Up, Dropped, and so on). Change the Date field to check another day.

Where's My Cab

Once your driver starts the trip, this section appears automatically with a live map: your vehicle's current position, the hub, and your driver's name and phone number. It refreshes on its own every 15 seconds — no need to reload.

Request a cab

Need a ride outside your normal roster — a schedule change, a one-off trip? Select New Request, fill in the date, approximate time, type (pickup, drop, or round trip), pickup address, and a short reason, then select Submit Request. Track its status — Pending, Approved, or Rejected — on your home screen. You can Cancel a request yourself as long as it's still pending.

Notifications

You'll receive an automatic text message when:

• A trip you're scheduled on starts.
• You're marked picked up or dropped.
• A cab request you submitted is approved or rejected.

Roles & permissions

The complete picture, for reference.

Troubleshooting

Minimum requirements to host

For whoever stands this up on a real server. Three moving parts: a web/database stack, a self-hosted routing engine, and a network path in front of it.

Web & database server

Routing engine

Road-network distances and directions come from a self-hosted routing engine (GraphHopper) — not a paid mapping API. It needs its own Java runtime and a map extract for the area you actually cover.

Network

• A domain name, pointed at the server.
• An HTTPS certificate — logins and session tokens shouldn't travel in the clear. A free certificate (Let's Encrypt) is sufficient.
• Outbound internet access from users' browsers — map imagery is drawn from a public map-tile service, so whoever is viewing a map needs their own connection to it. The server itself doesn't need continued internet access once the routing engine's map data is downloaded.
• The routing engine's port and the database port should never be reachable from outside the server — see the security note in the next section.

Deploying to the web

From a working copy to a live, internet-reachable install.

1. Provision a server. A small Linux VPS (Ubuntu 22.04 LTS or similar) is the most common, cost-effective choice, and every step below assumes one — the same stack runs on Windows Server too, just with different install commands and a Scheduled Task in place of cron.
2. Install the stack. Install PHP 8.1+ with the pdo_mysql extension, MySQL or MariaDB 8+, and Apache with mod_rewrite enabled.
3. Install the routing engine. Install a Java 17 runtime, then set up GraphHopper with a map extract covering your service area (see requirements above for sizing). Keep it bound to 127.0.0.1 — it should only ever be reached from this same server, never from the internet.
4. Copy the project onto the server. Place the whole project folder (both the web/ and api/ directories together, as siblings) anywhere convenient on disk.
5. Create the database. Create a database and application-specific database user, then import the schema files in order, followed by the setup script that creates the first tenant and admin account.
6. Configure the environment. Copy the environment template to .env and fill in your real values: the domain name, database credentials, and the routing engine's address. Generate a long, random value for the JWT signing secret — logins depend on it, and the placeholder value must not reach production.
   Don't skip this An unchanged, default signing secret means anyone who reads the source could forge a valid login for any account. Generate a fresh one for every install.

   SMS and email credentials are optional — leave them blank and the app still works fully, it just won't be able to actually send the text messages described in Notifications.

7. Point your domain at the project. Set your domain's document root directly at the project folder — not a parent folder. That puts the admin console at yourdomain.com/web/ and the API at yourdomain.com/api/, matching the routing rules already built into the included .htaccess files. Visiting the bare domain redirects to the admin console automatically.
8. Set storage permissions. The web server's user needs write access to the application's upload and log storage folders — this is where odometer photos and local activity logs are written.
9. Run the routing engine as a service. Set it up to start automatically on boot and restart if it crashes, rather than running it in a terminal session that ends when you log out.
10. Schedule the nightly clustering run. Add a scheduled job (cron, or a Scheduled Task on Windows) that runs the clustering script once a day ahead of the next day's shifts — this is what the Run Scheduler button also triggers on demand, so the daily job simply saves dispatchers from doing it by hand every evening.
11. Turn on HTTPS. Issue a certificate for your domain and make sure plain HTTP requests redirect to HTTPS. Login credentials and session tokens are sent on every request — they shouldn't ever travel unencrypted.
12. Verify.
    • Load the admin console and confirm API Status on the Dashboard reads ✓ Healthy.
    • Log in, add a hub and a vehicle, and confirm they save.
    • Open Tracking and confirm the map background actually draws (proof the browser can reach the public map-tile service).
    • Run the scheduler once by hand and confirm a cluster appears — proof the routing engine is reachable from the app.