Transport setup and usage

Transport is the most order-dependent module in the product, because each step is the prerequisite for the next. A stop cannot exist without a route, a duty cannot start without a vehicle that has a route, a roster cannot be seeded without student assignments, and billing cannot happen without a stop fee and a TRN fee type. Build it once in the right order and the daily routine is short; build it out of order and the failure usually appears days later as a driver who cannot start a trip or a family who is never billed.

Prerequisites

1. An account with Platform Admin, Principal or Vice Principal. Every setup write - routes, stops, vehicles, providers, drivers, assignments and the waitlist - is limited to those three roles.
2. An active academic year, because assignments and the fee sync are both scoped to one.
3. A fee type with code TRN at /fees/fee-types if stops carry a monthly fee. The fee structure is created on first use, but the fee type is not.
4. An active Transport role in the roles list, so provider driver profiles can be given a duty login.
5. Students already on the roster, since an assignment points at a student account.

Setup workflow

1. Create routes at /transport or /transport/routes with a name and code.
2. On /transport/[id], add stops with a sequence, pickup and drop times, a map pin, and the monthly fee. Optimise the stop order here if you added them out of sequence.
3. Add providers, then on provider detail create each driver with a duty login or link an existing user account.
4. Link vehicles to a route and driver under /transport/vehicles, and record insurance, fitness and licence expiry dates while you are there.
5. Assign students to a stop from route detail or /transport/assignments, or in bulk through the assignment import.

Who can do what

Daily duty workflow

1. The driver opens /transport/duty and starts pickup or drop. Both trips for the day are created and the roster is seeded from active assignments on that route.
2. On /transport/duty/[tripId] the browser takes an immediate position fix and then watches location, posting a ping about every fifteen seconds while the trip is in progress.
3. Mark each student present or absent for the board phase and again for the drop. Children the family has already reported as not riding today arrive pre-marked absent.
4. Finish the trip, which flags anybody still unmarked as absent, or cancel it with an optional reason.
5. Parents receive an in-app alert and an email for each board and drop mark, and an in-app alert when the trip starts, deep linked to /parent-dashboard/transport with their child id.

The fee handoff

A stop with a monthly fee above zero is the trigger. When a student is assigned, the sync creates one TRN fee instance per month from the current calendar month through to the end of the academic year, capped at twelve months, each due on the seventh. It is idempotent: every instance carries a marker of the assignment id and the year and month in its notes, so repeating the assignment cannot double-bill a month. Ending an assignment waives the unpaid pending, overdue and partial instances for it and leaves paid history alone.

• A stop fee of zero produces nothing at all, which is the intended way to run free transport.
• With no TRN fee type, or no active academic year, the sync returns a reason and writes nothing. There is no visible warning on the assignment screen.
• The fee structure for TRN is created on first use with twelve installments and a seven-day grace period, so no fee setup beyond the fee type is needed.
• From the moment an instance exists it is an ordinary finance item. Collection, receipts and any waiver happen in the fees module, and the transport screens cannot reverse one.

Where it goes wrong

• Assigning students before creating the TRN fee type. The assignment succeeds, billing silently does not, and it is usually noticed a month later.
• Reassigning a student rather than ending the old assignment first, which leaves the previous unpaid instances in place.
• Filling a vehicle past capacity. The assignment is refused with a capacity error and a waitlist suggestion; the waitlist at /transport/waitlist is where those students should go.
• Leaving a vehicle without a route. Duty cannot start, and the roster for that vehicle never seeds.
• Treating the documents screen as an alert. Expiry inside thirty days is calculated when you open /transport/documents or /transport/dashboard, and nothing is emailed.

Monitoring and reports

• Office live view: /transport/day-sheet, with the fleet map and a day export.
• Boarding history: /transport/reports, also exposed as report id transport-boarding at /api/transport/boarding-report. A query may span at most 92 days, and an export stops at 5,000 rows with a truncation flag rather than trimming quietly.
• Parents poll live status at /parent-dashboard/transport and students at /my-transport, both about every fifteen seconds.
• Retention is handled by the daily cron: GPS pings are deleted after 30 days and boarding events after 730, so the boarding report is the durable record and the live map is not.