ACFS VBS Pickup Portal

Business Requirements Document

Version 0.7.0Status: draftUpdated: 2026-03-21

1. Purpose & Scope

The ACFS VBS Pickup Portal is a web-based system for managing container pickup bookings at ACFS facilities. It enables logistics service providers to view shipments, delegate pickup authority, book pickup slots, manage documentation, and make payments — with ACFS staff overseeing operations, slot configuration, and verification.

2. Actors — Who Is Involved

Logistics Service Provider (LSP)

Core registered user. Umbrella term covering NVOCC, wholesale Freight Forwarder, Freight Forwarder, Transporter, Farmers, and Customer/Clearing agents. Each LSP sees only shipments allocated to them. Can delegate to another LSP or a one-off P4TC. Replaces the previous WFF/FF/Carrier actor split. Note: roles are contextual per HBL — the same organisation can appear at different levels (e.g. top-level party on one HBL, delegatee on another). Visibility and role enforcement must be HBL-scoped, not user-scoped.

Authentication: Username + password. Created by ACFS admin in the portal.

Responsibilities:

View list of assigned HBLs with shipment status, milestone, payment, delegation, and booking info. Data auto-synced on login and on subsequent integration layer calls.
Select one or multiple shipments to take action on (delegate or book).
Delegate shipments to an existing LSP (search and select) or add a new one-off LSP, which creates a P4TC with email + secure link. Per HBL — if delegated, LSP cannot also book directly on that same HBL (BR-004).
Book pickup directly: system validates booking readiness (unpacked + customs cleared + DOs present) → upload missing docs → load calculation + pricing → select slot → enter truck and driver details (select existing or add new, scoped to account) → accept T&Cs + site induction → make payment (Stripe/Compay) → receive booking confirmation with reference number. Requires HBL milestone "unpacked" or later (BR-001).
Request missing docs when DOs are unavailable. Booking process is aborted (offline) until DO is received.
Upload Delivery Order for downstream enforcement.
Flag an HBL as under-bond. Manually set in portal — not synced from Maximus.
Modify booking before cutoff: change slot date/time and HBLs (add/remove) before booking cutoff. Change truck/driver at any time until shipment is collected. Cost-impacting changes after cutoff require ACFS (BR-015).

Party to Collect (P4TC)

Tertiary/one-off user with no portal credentials. Receives email with shipment roster and document portal URL. No persistent account or history. Replaces previous "One-off Customer" and "Freight Forwarder" (magic-link) actors.

Authentication: Magic link + OTP. No login required — clicks link from email, verifies via OTP. Portal access scoped to assigned shipments only. Link expires on collection.

Responsibilities:

Access portal via emailed link (no login). Verify identity with OTP.
View list of assigned HBLs from the delegation.
Delegate shipments further: enter P4TC name + email ID, optionally upload new DO. System sends email with shipment roster and secure link to the new P4TC.
Book pickup: validate booking readiness → load calculation + pricing → select slot → enter truck and driver details (name, license#, phone — no saved drivers for P4TC) → accept T&Cs + site induction → make payment → receive booking confirmation with reference.
Upload missing DO or contact ACFS for support if DO is unavailable.

Driver

Secondary user. No portal access. No direct system communication — the booking party manages driver rostering externally and forwards booking details to the driver.

Authentication: No portal auth. No system emails. Booking party forwards confirmation externally.

Responsibilities:

Receive booking reference from booking party (forwarded externally — system does NOT email the driver directly).
Present booking reference and identity at gatehouse for pickup verification.

ACFS Internal

Internal ACFS staff. Two sub-roles: Admin (full privileges) and User (predefined/restricted privileges). Manages HBL assignment, slot configuration, booking operations, DO validation, pickup verification, and user management.

Authentication: SSO-based access. Admin and User sub-roles with predefined privileges.

Responsibilities:

HBL Assignment (remedial/optional): manually assign or reassign HBLs to LSPs via searchable dropdown (search LSP by name → assign). Same UX for reassignment — search and select a different LSP. System lists unassigned FAK shipments. Low priority for Phase 1 — data fix preferred over UI.
ECST Assignment: assign ECST to shipments. Parked for Phase 1 — flow details to be defined later.
Slot Configuration: select site → select days of week → set start/end time per slot (flexible, overlapping allowed) → configure booking cutoff and change cutoff (relative day + time, e.g. "previous working day, 4 PM") → optionally set heat map threshold value (nice-to-have) → block holidays via calendar overlay → save/update slots.
Manage Booking: search bookings by booking ref# or by truck/driver details → view details (slot date/time, booking party, HBLs, fees paid, driver/truck) → inline edit: change pickup slot, change driver/truck, add/remove HBLs. All edits available on non-cancelled/non-collected bookings. Admin can override cutoffs. When HBLs are added/removed, fee total recalculates but no additional payment is collected (fee-free modifications for Phase 1). No truck capacity validation — that is the carrier's responsibility. Booking update notification sent via email to booking party.
DO Validation (separate from pickup verification): view list of bookings with unvalidated DOs → validate DO against lowest-level HBL details → mark as validated. HBL-centric, not booking-centric. Can be done by offshore team. Prioritise by slot date/time.
Pickup Verification: search bookings by ref# or truck/driver → view details + DO validation status + audit tracking → validate or reject. If validated, change booking status to "processed". If not validated, booking is flagged. Includes DO validation if not already done.
User Management: create, update, and remove users (LSP and ACFS internal). Configure feature permissions per user.
Override missing DO requirement. Restricted to Admin role. Audit trail with reason required. One-time per HBL, lives until collected.
FOC rebooking for no-shows: admin edits the pickup slot (and optionally driver/truck) on the existing booking — no new booking created. Fee-free. No separate FOC rebook action — uses the same inline edit capability as acfs:r4.
Flag an HBL as under-bond.
Partially process bookings — clear HBLs proceed while blocked ones are rebooked separately.
Edit HBL details and update milestones/statuses manually when corrections are needed.
Edit delegation — reassign or revoke delegation between parties.

Gatehouse

ACFS gatehouse staff who verify and confirm physical vehicle entry/exit for pickups. Part of the Pickup Verification flow.

Authentication: SSO via OAuth/Okta.

Responsibilities:

Verify booking reference, driver identity, and truck rego on arrival.
Confirm vehicle exit to mark booking as collected.

3. Entities — Key Data with Lifecycle

House Bill of Lading (HBL)

Primary tracking unit for a shipment. Sourced from Maximus via periodic batch (once or twice daily). Two orthogonal dimensions: milestone (physical progress) and HBL status (delegation/booking state). HBLs exist in a hierarchy: AGS issues master HBLs (often 500-prefix), freight forwarders issue lower-level HBLs (e.g. 4033-prefix for Mondial). Mostly 1:1 parent-child relationship. The portal primarily deals with the lowest-level HBL as the primary identifier. Full audit trail lives on HBL — shows all hops, delegation chain, assignment changes, and status transitions.

Key Fields:

Field	Type	Description
hbl_number	string	Primary identifier — lowest-level house bill number from Maximus.
alt_hbl_reference	string	Alternative/parent HBL reference (e.g. AGS master HBL). Optional — present when hierarchy exists. Relationship established via AGS data feed, not Maximus. ⚠️ Exact data source for HBL hierarchy relationship TBD — Matt and William resolving (OQ-034).
container_number	string	Container reference — ties HBL to the top-level container.
ocean_bl	string	Ocean bill of lading. Multiple containers may share one ocean BL.
consignee	string	Next party in the chain. Data source is AGS feed (not ICS/Maximus — too inconsistent). Identified by account name or account code.
weight_kg	number	Weight measurement for fee calculation.
volume_m3	number	Volumetric measurement for fee calculation.
chargeable_weight	number	Max of weight vs volume per HBL. Used for fee calculation: chargeable_weight × rate. Calculated and stored as a field.
quantity	number	Number of packages (e.g. 3 boxes). Optional — may not be required for decision-making.
pack_type	string	Package type description. Optional — may not be required for decision-making.
description	string	Goods description. Two source fields exist in Maximus: "description" and "marks and numbers" — may consolidate.
milestone	'on_vessel' \| 'at_wharf' \| 'in_yard' \| 'unpacked' \| 'collected'	Physical progress milestone. Linear progression. Sourced from Maximus batch sync.
hbl_status	'unassigned' \| 'assigned' \| 'delegated' \| 'booked'	Delegation/booking status. Separate dimension from milestone. "assigned" means allocated to an LSP. "delegated" means LSP has passed to another party. "booked" means pickup is scheduled.
customs_clearance_status	string	Customs clearance state including quarantine. Must be fully cleared (not partial) for booking. Shown in HBL table. Sourced from Maximus — update frequency from ICS unclear.
under_bond	boolean	Flag — NOT a lifecycle state. Goods moving between bonded facilities before customs clearance (Australian Border Force customs bond). Manually set by LSP/ACFS in portal. Movement permission replaces DO requirement. Not synced from Maximus.
under_bond_verified	boolean	Whether ACFS has verified the under-bond marking. Verification happens outside the portal; portal records the result. Set by ACFS staff only.
storage_fee_flag	boolean	Visual indicator that storage fees apply. Derived from last_free_storage_date — auto-calculated, not manually set.
last_free_storage_date	date	Last date of free storage. After this date, storage_fee_flag is automatically set to true. Sourced from Maximus or set by ACFS.
release_type	'do_required' \| 'free_release'	Determines DO requirements. Phase 1 supports two types: "do_required" (default — DO must be uploaded and validated) and "free_release" (no DO needed for that tier). Under-bond HBLs skip DO requirement entirely via the under_bond flag.
assigned_lsp	string	LSP this HBL is allocated to. Set by ACFS during HBL/WFF assignment or auto-assigned from data.

Lifecycle States:

on_vesselat_wharfin_yardunpackedcollected

⚠️ Milestones only — delegation and booking are tracked via hbl_status, a separate dimension. Delegation can happen at any milestone (BR-001). Booking requires milestone "unpacked" or later (BR-001).

Transitions:

From	To	Trigger	Guard
on_vessel	at_wharf	Vessel arrives at port	Maximus batch sync
at_wharf	in_yard	Container moved to yard	—
in_yard	unpacked	Container unpacked at warehouse	—
unpacked	collected	Goods physically picked up from warehouse	Booking in "processed" state + gatehouse confirms exit

Booking

Groups one or more HBLs into a pickup window with driver/truck details. Created by LSP or P4TC. No truck type distinction for Phase 1 — booking party is responsible for bringing the correct truck. Slim audit trail at booking level (created, payment confirmed). Full hop history lives on the HBL entity instead. "Collected" status is derived — booking becomes collected when all its HBLs reach the "collected" milestone (no manual status change).

Key Fields:

Field	Type	Description
booking_id	string	System-generated unique reference number.
pickup_window	PickupWindow	Selected date/time slot.
hbl_ids	string[]	HBLs included in this booking. Can span multiple LSPs.
driver_name	string	Driver performing pickup.
driver_license	string	Driver license number.
truck_rego	string	Vehicle registration.
fee_amount	number	Sum of (chargeable_weight × rate) per HBL + minimum charge. Backend-calculated and returned per HBL from the API. Rate and minimum charge are backend-configurable. Frontend displays calculated values only — no fee logic in frontend.
booking_party	string	LSP or P4TC who created the booking.
tc_accepted	boolean	Whether booking party accepted terms and conditions.
site_induction_accepted	boolean	Whether driver site induction was acknowledged. Skipped if driver already has site_induction = true.

Lifecycle States:

draftbookedpending_processingprocessedcollectedcancelled

⚠️ "collected" is a derived status — automatically set when all HBLs in the booking reach the "collected" milestone. No manual status change.

Transitions:

From	To	Trigger	Guard
draft	booked	LSP or P4TC confirms, accepts T&Cs + site induction, and pays	All HBLs at milestone "unpacked" or later + fully customs cleared + release conditions met + missing docs uploaded + T&Cs accepted
booked	pending_processing	ACFS staff begins pickup verification	—
pending_processing	processed	ACFS validates DOs + audit tracking and marks ready. Partial processing allowed — clear HBLs proceed, blocked ones rebook separately.	—
processed	collected	Gatehouse confirms vehicle exit	—
booked	cancelled	LSP or ACFS cancels booking. Cancellation reason required (ACFS). Refund processed outside system.	—

Pickup Slot

A configurable time window at a specific site. Configured by ACFS admin. No truck type distinction for Phase 1. Default granularity is hourly (1-hour slots) — ACFS configures available hours per day. Visual presentation uses primary color with varying opacity levels to show booking density per slot without exact numbers.

Key Fields:

Field	Type	Description
slot_id	string	System-generated unique ID.
site	string	Physical site/location for pickup (references site entity).
days_of_week	string[]	Days this slot template applies to (e.g. Monday-Friday).
start_time	time	Slot start time.
end_time	time	Slot end time.
booking_cutoff	{ relative_day: string, time: string }	Booking cutoff — relative day (e.g. "previous_working_day", "same_day") + time (e.g. "16:00"). Bookings not accepted after this point.
change_cutoff	{ relative_day: string, time: string }	Change cutoff — same format as booking cutoff. Changes to slot/date/HBLs not allowed after this point (truck/driver changes exempt).
heat_map_threshold	number	Threshold value for density indicator. Primary color with varying opacity levels applied to slot cards (low opacity = empty, high opacity = busy). No exact booking counts shown. Nice-to-have for Phase 1.
is_blocked	boolean	Whether slot is blocked due to holiday/blackout date.

Lifecycle States:

activeblockedpast

Transitions:

From	To	Trigger	Guard
active	blocked	ACFS adds blackout/holiday date	—
blocked	active	ACFS removes blackout/holiday date	—
active	past	Slot end time passes	—

Site

Physical warehouse/pickup location. Seeded directly in the database — no admin CRUD UI for Phase 1.

Key Fields:

Field	Type	Description
site_name	string	Human-readable site name (e.g. "Port Botany Warehouse").
branch_code	string	Branch code (e.g. "SY", "MB", "BR"). Multiple sites can share a branch code.

Lifecycle States:

active

⚠️ Static entity — DB-seeded, no state transitions in Phase 1.

Driver Record

Saved driver details for reuse across bookings. Built up organically by booking parties — no pre-population. Scoped per LSP account — drivers are NOT globally visible across accounts.

Key Fields:

Field	Type	Description
driver_name	string	Driver full name.
driver_license	string	Driver license number. Paired with name.
truck_rego	string	Default vehicle registration.
site_induction	boolean	Whether driver has completed site induction. If true, site induction acceptance is skipped during booking.

Lifecycle States:

active

⚠️ Static entity — created during booking flow, no state transitions.

Delivery Order (DO)

Document required per HBL for pickup authorization. One-to-many relationship: each HBL can have multiple DOs (one per delegation tier in the hierarchy). Each DO is validated individually by ACFS. Uploaded by LSP or P4TC, validated by ACFS. Each tier in the HBL hierarchy uploads independently — no inheritance. Free release removes the DO requirement for that tier. Under-bond HBLs skip DO requirement entirely.

Key Fields:

Field	Type	Description
do_id	string	System-generated unique ID.
hbl_id	string	HBL this DO belongs to.
uploaded_by	string	LSP or P4TC who uploaded the document.
upload_date	date	When the DO was uploaded.
document_url	string	Stored document reference/URL.
tier_level	string	Which level in the HBL hierarchy this DO covers. Each tier uploads independently.

Lifecycle States:

not_provideduploadedpending_validationvalidatedflaggednot_required

Transitions:

From	To	Trigger	Guard
not_provided	uploaded	LSP or P4TC uploads DO document	—
not_provided	not_required	HBL has free_release flag or under_bond flag	—
uploaded	pending_validation	ACFS begins DO review	—
pending_validation	validated	ACFS confirms DO matches HBL details	—
pending_validation	flagged	ACFS flags DO as incorrect — requires correction	—
flagged	uploaded	LSP or P4TC re-uploads corrected DO	—

Delegation

Records the delegation of one or more HBLs from one party to another. Tracks the chain of custody. Can be revoked by ACFS.

Key Fields:

Field	Type	Description
delegation_id	string	System-generated unique ID.
delegator	string	LSP or P4TC who initiated the delegation.
delegatee	string	Target party — existing LSP (by ID) or new P4TC (by email).
delegation_method	'existing_lsp' \| 'one_off_p4tc'	Whether delegating to a registered LSP or creating a one-off P4TC.
hbl_ids	string[]	HBLs included in this delegation.
created_at	date	When the delegation was created.

Lifecycle States:

activerevoked

Transitions:

From	To	Trigger	Guard
active	revoked	ACFS revokes the delegation (acfs:r13)	HBLs revert to delegator

Maximus Integration (Inbound)

Primary data source for HBL shipment data. Periodic batch sync from custom cargo table. Portal fetches data starting 7 days before vessel arrival. Provides lowest-level HBL references, weight, volume, customs clearance status, and consignee data. Does NOT provide HBL hierarchy relationships or freight forwarder party assignments.

Key Fields:

Field	Type	Description
direction	string	Inbound — Maximus → Portal
frequency	string	Batch: once or twice daily. Auto-synced on LSP login.
data_provided	string	Lowest-level HBL number, weight, volume, customs clearance status (from ICS — update frequency unclear), consignee, quantity, pack type, description, marks and numbers.
data_not_provided	string	HBL hierarchy relationships (parent-child), freight forwarder party assignments, alternative HBL references.
status	string	Known — data structure understood. Frontend displays customs status as provided by the API. Staleness is a backend/integration concern. UI shows last sync timestamp if available.

Lifecycle States:

active

⚠️ Integration spec — no state transitions.

AGS Data Feed (Inbound)

Provides master HBL references, HBL hierarchy (parent-child relationships), and freight forwarder party data (name, account code). Data is consistent (unlike ICS which has variations across organisations). Matt and William are defining the exact data format and delivery mechanism.

Key Fields:

Field	Type	Description
direction	string	Inbound — AGS → Portal
frequency	string	TBD — Matt and William resolving (OQ-034).
data_provided	string	Master HBL references (500-prefix), HBL hierarchy (parent-child), freight forwarder party assignments (account name, account code), consignee at each level.
data_not_provided	string	Lowest-level HBL details (comes from Maximus instead).
status	string	BLOCKER — exact data format, delivery mechanism, and frequency TBD. This is the single biggest technical risk. ⚠️ Cannot build auto-assignment or HBL hierarchy without this feed. Matt and William working on it.

Lifecycle States:

active

⚠️ Integration spec — no state transitions.

Payment Integration (Outbound)

Payment processing for booking fees. Stripe embedded checkout for Phase 1. Payment integration is abstracted behind a single checkout redirect — provider can be swapped later if needed.

Key Fields:

Field	Type	Description
direction	string	Outbound — Portal → Stripe
frequency	string	Real-time — triggered on each booking.
provider	string	Stripe for Phase 1. Abstracted behind checkout redirect so provider can be swapped to Compay or another provider in a later phase.

Lifecycle States:

active

⚠️ Integration spec — no state transitions.

Email Notifications (Outbound)

Event-driven email notifications sent by the portal.

Key Fields:

Field	Type	Description
direction	string	Outbound — Portal → Email
triggers	string	Delegation (secure link + OTP), booking confirmation (to account email), booking update (to booking party), booking cancellation (to booking party), DO flagged for correction (to booking party — Phase 1 sends to booking party, future may send to the party who uploaded the DO), user creation (welcome email with signin link).
not_sent_to	string	Driver — no system emails. Booking party forwards details externally.

Lifecycle States:

active

⚠️ Integration spec — no state transitions.

LSP Registry Seed (One-time)

One-time bulk upload of LSP party data from AGS portal/party manager into the portal local DB.

Key Fields:

Field	Type	Description
direction	string	Inbound — AGS → Portal (one-time)
frequency	string	One-time bulk upload at system launch. No ongoing sync.
data_provided	string	Company name, email, company ID, branch code.

Lifecycle States:

active

⚠️ Integration spec — one-time seed, no state transitions.

4. User Journeys

ACFS Internal Journeys

ACFS Assigns HBLs to LSP (Remedial)

⚠️ Low priority for Phase 1. Matt indicated this may not be needed if auto-assignment is reliable within the 8-week timeline. Mark as optional.

Preconditions:

ACFS admin is logged in
HBLs have been synced from Maximus
Target LSP user exists in the portal
Auto-assignment has failed or data issue exists

View unassigned shipments — System lists FAK shipments that are unassigned or incorrectly assigned. Can filter by assignment status.
Select and assign — ACFS selects shipments and assigns them to an LSP. HBL status moves to "assigned". This is a remedial step — primary assignment comes from data integration.

Outcome: HBLs are assigned to the target LSP and visible in their shipment list on next login.

ACFS Configures Pickup Slots

Preconditions:

ACFS admin is logged in
Site exists in the database

Select site — ACFS selects a site (one at a time — no multi-site simultaneous config).
Configure slot template — Select days of week (typically Mon-Fri). Set available hours per day (default: hourly granularity). Multiple slots per day allowed, flexible, overlapping OK.
Configure cutoff rules — Set booking cutoff (relative day + time, e.g. "previous working day, 4 PM") and change cutoff (same format). Relative to the slot day.
Optional: set heat map threshold — Set threshold value for density indicator. System shows primary color at varying opacity levels based on booking density. Nice-to-have.
Block holidays — Overlay holiday calendar to block specific dates.
Save — Save/update slot configuration.

Outcome: Pickup slots are configured and available for LSP/P4TC booking.

ACFS Validates Delivery Orders

⚠️ DO validation can be done by offshore team independently from pickup verification. Same people doing pickup verification can also validate DOs, but DO validation is a separate capability.

Preconditions:

Bookings exist with unvalidated DOs

View unvalidated DOs — ACFS views list of HBLs with unvalidated DOs. HBL-centric view — not booking-centric. Can filter/prioritise by slot date/time for upcoming bookings.
Review DO against HBL — View lowest-level HBL details alongside the uploaded DO. Slot date/time and booking reference shown for context.
Validate or flag — If DO matches HBL details, mark as validated. If DO is incorrect, flag for follow-up with booking party (using booking reference).

Outcome: DO is marked as validated for that HBL, or flagged for correction.

ACFS Verifies Pickup

⚠️ Detailed field-level requirements for this view TBD — to be covered in next session with Matt.

Preconditions:

Booking exists in "booked" or "pending_processing" state

Search booking — ACFS searches bookings by booking ref# or by truck/driver details.
Review details — View booking details + DO validation status + audit tracking history. Includes DO validation if not already done.
Validate or reject — If all documents and details validate, change booking status to "processed". If validation fails, booking is flagged — does not proceed to collection.

Outcome: Booking status changed to "processed" and ready for gatehouse collection, or flagged for issues.

ACFS Cancels a Booking

Preconditions:

ACFS admin is logged in
Booking exists

Search booking — ACFS searches by booking ref, truck rego, or driver name/license.
Cancel booking — ACFS initiates cancellation. Must provide cancellation reason.
Notification — Cancellation update sent to the booking party via email.

Outcome: Booking is cancelled. HBLs revert. Refund processed outside the system. Booking party notified.

ACFS Creates a User

Preconditions:

ACFS admin is logged in

Select user type — Choose role: Logistics Service Provider, ACFS Admin, or ACFS User.
Enter user details — LSP: company name, company ID, branch code, contact name, contact email. Username + password based access. ACFS: company name = ACFS, company code, contact name, contact email. SSO-based access.
System sends welcome email — Welcome email with signin link sent to user. Link expires in 72 hours.
User activates account — LSP: clicks link and sets password. ACFS: clicks link and SSO login is requested. Successful login completes activation.

Outcome: User account is created and active. User can log in.

ACFS Updates a User

Preconditions:

ACFS admin is logged in
Target user exists

Select user — Search and select the user to update. Available for LSP, ACFS Admin, and ACFS User roles.
Update details — LSP: can update everything except username. ACFS: can update everything except SSO details.

Outcome: User details are updated.

ACFS Removes a User

Preconditions:

ACFS admin is logged in
Target user exists

Select user — Search and select the user to remove.
Archive user — User is archived on removal. Access is disabled and email notification is disabled.

Outcome: User is archived. Cannot log in. No further notifications sent.

Logistics Service Provider (LSP) Journeys

LSP Delegates Shipments

Preconditions:

LSP is logged in
LSP has assigned HBLs visible in their list

Select shipments — LSP views list of assigned HBLs with shipment status. Selects one or multiple shipments to delegate.
Choose delegation target — Either select an existing LSP (search and select from pre-populated registry — company name, email, branch code) or add a new one-off party (email only — creates a P4TC).
System sends notification — Email sent to the delegate with a message and secure link. No shipment data in the email body — all details visible after login/OTP.

Outcome: Shipments are delegated. Target LSP or P4TC receives email with secure access link. HBL status moves to "delegated".

LSP Books a Pickup

Preconditions:

LSP is logged in
Selected HBLs are at milestone "unpacked" or later (BR-001)
HBLs are not already delegated (BR-004)

Select shipments — LSP selects one or multiple HBLs from their assigned list to book for pickup.
Validate booking readiness — System checks: (1) HBL milestone is "unpacked" or later, (2) fully customs cleared (including quarantine), (3) all applicable DOs are present. If docs missing, LSP can upload them or request missing docs (aborts booking — offline process).
Load calculation + pricing — System calculates fee per HBL: chargeable_weight (max of weight vs volume) × rate. Individual HBL charges summed + minimum charge = total fee.
Select slot — LSP selects an available hourly slot. Density indicator shows booking volume per slot using opacity levels (no exact numbers). Does not block booking.
Enter truck and driver details — Select existing driver from account-scoped list (search/dropdown) or enter new driver details (name, license, truck rego). New drivers are saved to the account for future reuse. P4TC users always enter fresh details.
Accept T&Cs and site induction — Booking party must accept: (1) booking terms and conditions (legal document), (2) driver site induction acknowledgement (document). If driver already has site_induction = true, the second acceptance is skipped.
Make payment — Payment via Stripe embedded checkout. Redirects to payment interface.
Confirmation — Booking confirmation with booking reference sent to the account email. No email sent to driver — booking party forwards details externally.

Outcome: Booking is confirmed with reference number. HBLs move to hbl_status "booked". Confirmation sent to account email.

LSP Modifies a Booking

Preconditions:

LSP is logged in
Booking exists in "booked" state

View booking details — LSP opens an existing booking from their bookings list.
Choose modification type — LSP can: (a) change truck/driver details — allowed anytime until collection, (b) change slot date/time — allowed before change cutoff only, (c) add/remove HBLs — allowed before change cutoff only.
System checks cutoff — If change cutoff has passed: truck/driver changes proceed, but slot/HBL changes are blocked. Cost-impacting changes after cutoff require ACFS admin override (BR-015).
Apply changes — For truck/driver: update in-place. For slot: re-validate availability, recalculate fees if HBLs changed. For HBL removal: treated as partial cancellation with offline refund. For HBL addition: additional fee charged.
Confirmation — Updated booking confirmation sent to account email. Booking reference remains the same.

Outcome: Booking is updated with new details. Confirmation sent. If fee changed, payment difference handled.

LSP Cancels a Booking

Preconditions:

LSP is logged in
Booking exists in "booked" state

View bookings — LSP views current and past bookings list.
Open booking details — LSP opens the booking they want to cancel.
Cancel booking — LSP initiates cancellation. Refund is processed outside the system (C-003).

Outcome: Booking is cancelled. HBLs revert to previous hbl_status. Refund handled offline by ACFS.

Party to Collect (P4TC) Journeys

P4TC Books a Pickup

Preconditions:

P4TC has received email with shipment roster and portal URL
HBLs are at milestone "unpacked" or later

Access portal — P4TC clicks link in email to access portal. No login required. Verifies via OTP sent to the same email. OTP verification serves as email security validation.
View assigned HBLs — P4TC sees list of assigned HBLs from the delegation.
Choose action — P4TC can either delegate shipments further (enter P4TC name + email, optionally upload new DO) or proceed to book pickup.
Validate booking readiness — System checks unpacked status, customs clearance, and DO presence. P4TC can upload missing DO or contact ACFS for support.
Load calculation + pricing — System calculates fees per HBL (chargeable_weight × rate + minimum charge). P4TC reviews pricing.
Select slot — Select available hourly slot. Density indicator shows booking volume using opacity levels (no exact numbers). Does not block.
Enter truck and driver details — Enter driver name, license#, truck rego. No saved driver list for P4TC (one-off users).
Accept T&Cs and site induction — Accept booking terms and conditions + driver site induction acknowledgement.
Make payment — Payment via Stripe/Compay.
Confirmation — Booking confirmation sent to P4TC email containing: booking reference, pickup slot (date/time), HBL numbers with weight/volume, fee total, and site address. No upstream delegation chain or LSP details exposed. No email to driver.

Outcome: Booking confirmed. Confirmation sent to P4TC email. HBLs move to "booked".

P4TC Manages Booking (One-off)

Preconditions:

P4TC has an active booking

Contact ACFS — P4TC contacts ACFS for any booking modifications. No self-service modification for one-off booking parties.

Outcome: ACFS handles the modification on behalf of the P4TC.

5. Business Rules

BR-001

Delegation can happen at any milestone — no unpack gate. Booking requires all included HBLs to have milestone "unpacked" or later AND fully customs cleared (including quarantine). This means delegate button is always enabled; book button is gated by milestone + customs clearance.

Applies to: hbl, bookingSource: BRD s4.2 + discussion between Rahul, Roni, and Matt on 2026-03-17 and 2026-03-18

BR-002

Under-bond HBLs skip the DO requirement. Under-bond is a boolean flag set manually by LSP/ACFS staff in the portal. Not synced from Maximus. Verification happens outside the portal.

Applies to: hblSource: BRD s4.3 + discussion between Rahul, Roni, and Matt on 2026-03-17

⚠️ Under-bond is an LSP/ACFS manual flag — not a lifecycle or automated process.

BR-003

DO rules follow a multi-level hierarchy. Each level uploads its own DO independently — no inheritance or cascading. Bottom-most party must have ALL DOs present across all tiers. Free release removes the DO requirement for that tier.

Applies to: hbl, lsp, p4tc, acfsSource: BRD s4.4 + discussion between Rahul, Roni, and Matt on 2026-03-17

BR-004

LSP can either delegate or book directly per HBL — never both on the same HBL. Mutual exclusivity enforced at the HBL level.

Applies to: hbl, lspSource: OQ-003 resolution + March 18 flow

BR-005

Slot cutoffs are relative day + time (e.g. "previous working day, 4 PM" or "same day, 10 AM"). Booking cutoff and change cutoff configured separately per slot template. Per-site configuration.

Applies to: booking, slotSource: discussion between Roni and Matt on 2026-03-18

BR-006

No-show rebooking: ACFS admin edits the pickup slot (and optionally driver/truck) on the existing booking. No new booking is created. Fee-free for Phase 1. No separate FOC rebook button — uses inline edit on the booking detail view. LSP must call ACFS — no self-service for no-show rebooking.

Applies to: booking, acfsSource: discussion between Rahul, Roni, and Matt on 2026-03-17 + discussion between Rahul and Roni on 2026-03-20

BR-007

ACFS can partially process bookings — HBLs that have cleared customs proceed while blocked ones are rebooked separately.

Applies to: booking, acfsSource: discussion between Rahul, Roni, and Matt on 2026-03-17

BR-009

LSP can only view shipments allocated to them. Shipment visibility is scoped per LSP — no cross-LSP visibility.

Applies to: hbl, lspSource: March 18 flow diagram

BR-010

Data is auto-synced on LSP login and on the next call to the integration layer. No manual refresh needed.

Applies to: hbl, lspSource: March 18 flow diagram

BR-011

Missing doc request aborts the booking process. Booking is blocked (offline) until the DO is received. This is a hard stop, not a warning.

Applies to: booking, hblSource: March 18 flow diagram

BR-012

Booking confirmation is sent to the account email (LSP) or P4TC email only. No system email is sent to the driver — the booking party forwards the booking reference to the driver externally via their own rostering process.

Applies to: bookingSource: discussion between Roni and Matt on 2026-03-18

BR-013

P4TC can delegate shipments further to another P4TC by entering name + email. The new P4TC receives an email with shipment roster and secure link. Chain delegation is supported.

Applies to: p4tc, hblSource: March 18 flow diagram

BR-014

ACFS manages user lifecycle: create, update, remove LSP and ACFS internal users. Feature permissions can be configured per user.

Applies to: acfs, lspSource: March 18 flow diagram

BR-015

Booking modifications by external users: truck/driver can be changed at any time until shipment is collected (no cutoff restriction). Slot date/time and HBL changes (add/remove) allowed before change cutoff only. Cost-impacting changes after cutoff require ACFS admin intervention. ACFS admin can override all cutoffs.

Applies to: booking, lsp, p4tc, acfsSource: discussion between Roni and Matt on 2026-03-18

BR-016

Driver records are scoped per LSP account. Drivers added by one LSP user are visible to all users within that same account, but NOT visible to other accounts. P4TC users do not have saved driver records.

Applies to: lsp, driver_recordSource: discussion between Roni and Matt on 2026-03-18

BR-017

Booking requires acceptance of two separate documents: (1) booking terms and conditions (legal), (2) driver site induction acknowledgement. If the selected driver already has site_induction = true, the induction acceptance is skipped.

Applies to: booking, driver_recordSource: discussion between Roni and Matt on 2026-03-18

BR-018

DO validation is HBL-centric, not booking-centric. It is a separate capability from pickup verification. Can be performed by an offshore team. Warehouse staff doing pickup verification may also validate DOs inline.

Applies to: hbl, acfsSource: discussion between Roni and Matt on 2026-03-18

BR-019

Fee calculation: chargeable_weight (max of weight vs volume) per HBL × rate (single flat value). Sum individual HBL charges + minimum charge = total booking fee. Rate is a single configurable value for Phase 1 — may become per-slot or per-region in future.

Applies to: booking, hblSource: discussion between Roni and Matt on 2026-03-18

BR-020

Booking update notifications are sent to the booking party's account email when ACFS makes changes to a booking.

Applies to: booking, acfsSource: discussion between Roni and Matt on 2026-03-18

BR-021

Each HBL requires either a DO upload or a free release flag — one or the other per shipment. Free release removes the DO requirement for that tier entirely. This is a per-HBL choice made during the booking readiness step.

Applies to: hbl, lsp, p4tcSource: March 18 Miro board — "Either DO or Free release per shipment Free Release Flag"

BR-022

Booking cancellation: LSP can cancel their own bookings. ACFS can cancel any booking (requires cancellation reason). Cancellation notification sent to booking party. Refund processed outside the system. HBLs revert to previous status.

Applies to: booking, lsp, acfsSource: March 18 Miro board — cancel booking flows

BR-023

P4TC (one-off booking party) cannot self-service modify bookings. Must contact ACFS for any changes.

Applies to: booking, p4tcSource: March 18 Miro board — "CONTACT ACFS FOR ANY BOOKING MODIFICATIONS"

BR-024

User account removal is soft-delete (archive). Access is disabled and email notifications are disabled. User data is retained.

Applies to: acfs, lspSource: March 18 Miro board — "ARCHIVE USER ON REMOVAL"

BR-025

Welcome email signin link expires in 72 hours. User must click and set password (LSP) or complete SSO login (ACFS) within this window.

Applies to: acfs, lspSource: March 18 Miro board — "LINK EXPIRY 72 HOURS"

BR-026

Slots with active bookings cannot be removed. ACFS must cancel or reschedule bookings before removing a slot.

Applies to: slot, acfsSource: March 18 Miro board — "ACTIVE BOOKINGS? YES → CANNOT REMOVE SLOT"

BR-027

Admin booking modifications (add/remove HBLs, change slot) are fee-free for Phase 1. When HBLs are added or removed, the fee total recalculates to reflect the new weight but no additional payment is collected. No truck capacity validation on HBL add — carrier's responsibility.

Applies to: booking, acfsSource: discussion between Rahul and Roni on 2026-03-20

BR-028

Booking "collected" status is derived, not manually set. A booking becomes "collected" when all its HBLs reach the "collected" milestone. No manual status change needed.

Applies to: booking, hblSource: discussion between Rahul and Roni on 2026-03-20

BR-029

Audit trail: slim version on booking (booking created, payment confirmed). Full hop history lives on the HBL — shows all delegation chain hops, assignment changes, and status transitions per shipment.

Applies to: booking, hblSource: discussion between Rahul and Roni on 2026-03-20

BR-030

LSP "My Bookings" reuses the same booking list and detail view as the ACFS admin bookings interface. LSP can edit truck/driver at any time and slot/HBL before change cutoff (per BR-015). Same component as ACFS admin, different permissions.

Applies to: booking, lspSource: discussion between Rahul and Roni on 2026-03-20

BR-031

Multiple DOs per HBL — one DO per delegation tier (one-to-many relationship). Each DO is validated individually by ACFS. ACFS browses between DOs for a given HBL and marks each as validated or flagged.

Applies to: hbl, delivery_order, acfsSource: discussion between Rahul and Roni on 2026-03-20

6. Constraints

capacity

C-001: Pickup slots have NO hard capacity limits. Density indicator only (low/moderate/high based on configurable threshold). Does NOT block booking. Per-site configuration. Nice-to-have for Phase 1.

temporal

C-002: Slots with existing bookings cannot be modified in Phase 1. Blackout dates enforced via holiday calendar overlay.

pricing

C-003: Refunds are completely outside the portal. Handled offline by ACFS. Portal is refund-agnostic.

access

C-004: Driver has no portal access. No system emails to driver. Booking party manages driver communication externally.
C-005: P4TC (one-off) has no persistent credentials. Services shipments via magic link + OTP only. No account history. No saved driver records.

admin

C-006: Site management is DB-seeded for Phase 1 — no admin CRUD UI. Sites have name + branch code only.

platform

C-007: Desktop/laptop only. No tablet or mobile responsive design required. Portal is not meant for warehouse staff walking around — it is for counter/desk use.

notification

C-008: Email is the primary notification channel. In-app notifications are available for logged-in users (LSPs, ACFS) but are not a Phase 1 blocker. P4TC (no login) receives email only. DO flag-for-correction triggers email to booking party.

7. Open Questions & Decision Log

7a. Open Questions

OQ-034open

What is the exact data source for HBL hierarchy relationships?

Maximus has both lowest-level and master HBL references but NOT the parent-child relationship between them. AGS can provide the hierarchy. Matt and William are working on this — need confirmed approach before building the data integration.