Raptors Freight and Courier Service
Web Application — System Workflow

Implementation

• One sequence table per prefix, allocated inside a transaction to prevent collision under load
• Sequences must be non-guessable — a customer must not be able to enumerate other customers' packages by incrementing a number in the tracking box
• Reference is immutable once issued
• Stored as prefix + sequence in separate columns; concatenated for display

Behaviour

• The tracking box resolves any of the four prefixes, plus USPS numbers and consolidation references, on one endpoint
• A package moving between service lines (sea to air, say) keeps its original reference and writes a service-change row to the activity log — history is never orphaned
• The prefix is emitted on every label, invoice, waybill, manifest, POD and API response

Captured

• Ghana Card number, validated against the GHA-XXXXXXXXX-X format
• Front and back images — JPG, PNG or PDF
• Alternatives: passport, driver's licence, voter ID
• Proof of address dated within 3 months
• Business: certificate of incorporation, TIN, VAT certificate

API & storage

• POST/me/verification
• PATCH/admin/verification/{id}
• Card number encrypted at column level; images outside the web root
• Served only via short-lived signed URLs — no public path emitted
• On approve: RFC issued, virtual address issued, WhatsApp + email fired, guards lift

Behaviour

• Staff open a client account and render the client's own views — dashboard, packages, prices, documents
• Session carries an impersonating_customer_id alongside the real user_id
• Persistent banner naming the client being viewed
• Time-limited; expires back to the staff session

Constraints

• Strictly read-only. Every write path checks for an impersonation flag and refuses. Do not rely on hiding buttons — enforce at the controller
• Session start and end both written to activity_log with staff member, client and duration
• Incognito cannot be nested, and cannot be entered on another staff account

Trigger

• Fires only when the engine returns price_source = null at intake — not in the item catalogue and weight pricing does not apply
• Package enters an Awaiting Pricing queue and cannot progress to consolidation
• POST/warehouse/{node}/scan-price

Screen & effect

• Shows intake photograph, weight, dimensions, category and a suggested price from nearest-match history
• Price flows straight to the invoice; customer notified on WhatsApp and email
• Officer can save the item into the pre-priced catalogue so it auto-prices next time
• Manual price is written with the officer's identity and stored as price_source = scan_and_price

Product categories new

• Consolidation exports weight and count per category — the figure customs and carriers ask for

Currency

• Rate set in admin; written onto the quote record at quote time
• A price never moves retrospectively when the admin rate changes

Discounts new

• Fixed amount or percentage; per invoice or standing per customer
• Above threshold requires approval; approver recorded
• Rendered as its own invoice line and tracked separately on the Financial Sheet — discounting stays visible rather than hiding inside a lower headline price

Sequence

• POST/payments/initiate with a client-generated idempotency key
• Router selects the provider on channel, currency, amount band and network
• Insert payment_attempts with status=pending
• The provider callback is the source of truth — never the browser redirect
• Callback signature verified before any state change; replays rejected and logged
• Sweeper re-queries anything pending beyond 15 minutes

Failover

• Health monitor tracks success rate and latency per provider on a rolling window; a breaching provider is demoted
• Failed or timed-out initiation retries once on the other provider, transparently
• The idempotency key travels with the retry — a switchover can never double-charge
• Admin can pin all traffic to one provider during a known outage
• Every routing decision, retry and switchover is logged on the payment trail

Model

• An invoice holds many payments rows, each with its own method, provider, reference, amount, currency and date
• Invoice state derives from the sum: unpaid → part_paid → paid
• Never store a single amount_paid field — derive it, or the two go out of step the first time a refund lands

Surfacing

• Running balance shown after each payment, on the invoice and to the customer
• Each split payment appears individually on the Financial Sheet
• Release and clearance rules read the derived balance, not the last payment

Endpoints consumed

• OAuth 2.0 — client credentials; key and secret in the encrypted secrets store
• Domestic Prices — live rate for the request screen and calculator
• Domestic Labels v3 — purchase; image decoded and stored
• Carrier Pickup — schedule collection at the customer address
• Scan Form — one scan accepts a whole day's batch
• Tracking — poll and mirror scans onto the tracking page

• Rate re-checked at purchase; drift beyond tolerance re-quotes rather than silently absorbing the difference

Label sizes new

• Size auto-selected from product category and package dimensions; staff override available
• In-house Raptors label carrying the RCP reference printed alongside or instead of the USPS label
• Reprints increment a counter and log — never mistaken for a second purchase
• Label cost posts automatically to cost_lines

Scan and match

• Barcode scan of carrier label, RCP label or pre-alert reference; manual entry as fallback
• Auto-match to a pre-alert on carrier tracking number
• POST/warehouse/{node}/intake
• No match → unidentified_stock with photographs, awaiting claim

Capture & consequence

• Actual weight and dimensions; category confirmed or corrected
• Variance beyond tolerance against declared figures re-prices automatically and re-issues the quote
• Not auto-priceable → Awaiting Pricing queue → Scan and Price (2.2)
• Photographs mandatory; video where condition needs recording; annotated photo required on damage → damage_register
• Shelf location assigned; location label printed; status → In Warehouse; storage clock starts after the free period

Inventory

• Live stock by node, customer, category, location and age
• Bin transfer as a scan-out / scan-in pair, both ledgered
• Stock counts by zone or customer with a variance report
• Repack with before/after photographs and a repack charge

Ageing

• Alerts at 7 / 14 / 30 / 60 days, each notifying the customer
• Storage charges accrue daily to revenue_lines — visible before the package ships, billed on release
• Ready-for-collection date recorded here starts the 3-week auction clock (Phase Nine)

Air documents

• Master and House Air Waybill, printed with barcode
• Airline, flight number, ETD/ETA, IATA airport codes
• Dangerous Goods declaration required; air carriage blocked until cleared
• cost_lines: airline charge, duty and levies paid on behalf

Category breakdown

• Consolidation manifest exports total weight and package count per category — General Goods, Dangerous Goods, Electronics, Car Parts
• Export formats: Excel and PDF, matching the layout customs and carriers expect
• Any package with an unconfirmed category blocks the export — the number has to be right

What happens

• Consolidation → Break-out
• One delivery_jobs row per recipient, carrying the package list, address, contacts and derived outstanding balance
• WhatsApp broadcast to every recipient — each message lists only that recipient's own packages
• Ready-for-collection date set; auction clock starts

Financial effect

• cost_lines: duty and levies, terminal handling, destination haulage
• revenue_lines: clearance service fee, accrued storage
• Any package whose margin turns negative here is flagged on the Financial Sheet variance queue

Dispatcher

• All unassigned deliveries with zone, weight, category and value
• Assign singly or build a route; capacity checked by weight and volume
• POST/routes/{id}/assign
• Bulk scan-to-load — a package physically cannot be loaded onto the wrong route

Fee and commission

• Delivery fee defaults from the zone; overridable per job with the dispatcher and reason recorded
• Written to delivery_jobs.rider_fee at assignment and frozen
• Commission 10–15% calculated at the same moment into delivery_jobs.commission_rate and commission_amount; configurable per rider or per zone
• Freezing both at assignment means a later rate change never rewrites history — rider statements stay reproducible
• Net rider cost posts to cost_lines; commission posts as Raptors revenue

What the rider sees

• Assigned packages, each showing its delivery cost
• Amount to collect from the recipient, where any
• Daily total — deliveries, gross earnings, commission deducted, net due
• Earnings history and settlement statement
• One tap to navigate to the address

Technical

• GET/riders/me/manifest — jobs, fees, commission, collect amounts
• GET/riders/me/earnings
• Mobile-responsive web — no app install
• Manifest cached; completed stops queue locally and sync when signal returns
• Fee and commission visibility scoped to the rider's own jobs — a rider never sees another rider's rates

Proof of delivery

• Recipient name and relationship to the addressee
• On-screen signature; mandatory delivery photograph
• Video capture for high-value parcels or disputed handovers
• Delivery PIN by SMS for high-value parcels
• GPS and timestamp bound to the event
• POD PDF sent to the customer on WhatsApp and email; image and video attached to the tracking page

Failure handling

• Reasons: absent · address not found · refused · payment declined · no access
• Automatic re-delivery scheduling with a charge rule and an attempt ceiling
• Ceiling reached → return to warehouse, customer notified, storage clock restarts, auction clock restarts
• Failure analysis by zone drives which address field to prompt for at booking

Debt management new

• Balance per customer, aged into buckets, with contact details and last-reminder date
• One click fires a reminder on WhatsApp and email
• Debt threshold blocks new bookings until cleared; override requires approval and a reason
• Customer management page surfaces total paid and total debt on the client list itself

Reconciliation

• Paystack and Hubtel settlement files imported and auto-matched on reference and amount
• Unmatched items sit in an exceptions queue — never silently absorbed
• Rider cash-up: collected · handed in · outstanding · variance, per rider per day
• Variance requires a reason and supervisor sign-off
• Daily USPS Enterprise Payment Account reconciliation against labels issued
• Export to Excel, PDF and accounting-format CSV

Coverage

• Every action by every user across the whole platform — logins, price changes, discounts, payments, refunds, releases, overrides, verifications, assignments, deletions, incognito sessions, auction decisions
• Written by a central hook, not by each controller — a module that forgets to log is the failure mode

Record shape

• user_id, role, action, entity type and id, before_json, after_json, timestamp, IP
• Searchable and filterable by user, role, action type, entity and date range
• Append-only. No UPDATE or DELETE grant on the table for the application user
• Exportable for audit

Content

• One box resolves RFC, RAP, RSP, RCP, USPS and consolidation references
• Complete event history — date, time, location, and the action behind each event
• Package detail — weight, dimensions, category, contents, declared value
• Photographs from intake, repack and delivery on the timeline
• Video where captured — arrival condition, damage evidence, disputed handover
• Map view; consolidation view; delivery window and rider details once assigned

Access

• Basic detail public; full detail after login
• Price breakdown, payment status and documents render only for the authenticated owner — the public view must not leak commercial data on a guessed reference
• Media served through signed, expiring URLs
• Share button produces a link and a pre-filled WhatsApp message

Bulk messaging with media new

• Campaigns carry images — flyers, rate cards, notices
• Campaigns carry video — announcements, how-to clips, promotions
• Audience built by filtering on customer status, debt position, package status, category, zone or agency
• Preview before send; scheduled send; throttled to provider limits
• Campaign report: sent · delivered · read · failed · opted out

Dispatcher behaviour

• Queue-based with retry — three attempts, exponential back-off
• Persistent failure moves to a dead-letter queue and raises an alert
• Quiet hours — no SMS or WhatsApp 22:00–06:00 unless flagged urgent
• Per-customer channel preferences, opt-in and opt-out
• Message log with channel, status, timestamp and unit cost; cost posts to the Financial Sheet