How it works

Walk the product as a diagram

Click a flow, then step through it. Each step shows who acts, which API runs, and what is stored. Notifications and wallet moves fire from registered events—not from controllers.

Every actor (company, customer, driver, admin) uses the same login URL. The token is a JWT that lasts one month. Later calls send Authorization: Bearer {token}.

·

Tip: use ← → keys, or Play to auto-advance. Click a node in the diagram to jump to that step.

How records link

Click an entity to see what it owns

Company data is tenant-scoped. There is no global company query scope—callers filter by company_id.

Company

Connects to: Customers, Drivers, Assets, Orders, Trucks, Subscription

Tenant. Dashboard needs approved + active. Card payments need Finix merchant completed. Mutating jobs/orders may need an active subscription.

Request stack

What sits under every API call

Client apps

Company dashboard, customer app, driver app, guest web order

API gateway

/api/v1 — JWT Bearer token, throttling, actor middleware

Auth & gates

jwt.verify, checkType, ensure.*.user, check.company.subscription

Domain services

OrderService, BillingService, DriverJobBulkService, WalletService, FinixService

Persistence

MySQL — money as cents, job trees, snapshots, status history

Async & realtime

Queue, Pusher chat, FCM, attendance auto-close, delinquency

Written recap

Same flows as a checklist

Customer places an order

1

Customer app — POST /api/v1/customer/order/billing then POST /customer/orders

2

BillingService — Quote from asset_specification, payment term, promotion, taxes

3

OrderService::place — Pending order + pricing snapshot + line items + status history

4

Events — Customer\Order\PlaceEvent notifies the company

Company approves and plans jobs

1

Company — Approve with an assignable asset_id matching the spec

2

OrderService — awaiting_payment if upfront > 0, else approved; payment → confirmed

3

Jobs — Confirm creates todo delivery_job + retrieve_job shells (source=order)

4

Dispatcher — PUT /order/jobs/bulk (id = update, omit id = create) or POST /order/jobs/sync

Driver executes the tree

1

Driver — Attendance check-in, then start the planned root

2

Driver — Walk children; submit evidence; report issues

3

Order — Delivery complete → delivered; retrieve complete → picked_up / completed

Chat opens around the order / job

1

Company or customer — POST /api/v1/{role}/chats/{order}/create → order_company chat

2

Driver job start — StartedListener creates job_driver chat when the job has an order

3

Realtime — Pusher new_message on chat-{id} + actor list channels; unread via last_read_message_id

4

Job complete — job_driver chat closes; sends blocked on completed/cancelled orders