Part V - Business and Device Extensions

Chapter 25 - Dispatch, Tasks, and Proof of Delivery

A dispatch module turns location into operational workflow. It should build on subjects, teams, sessions, and realtime events rather than creating a second tracking model.

Task model

A general task can represent delivery, pickup, service visit, inspection, patrol, or field assignment:

tasks
  id
  organization_id
  type
  status
  priority
  assigned_subject_id
  assigned_team_id
  planned_start
  planned_end
  route_policy
  external_reference
  version

Task stops contain ordered actions:

task_stops
  id
  task_id
  sequence
  kind
  location
  geofence_radius_m
  contact_reference
  time_window_start
  time_window_end
  status
  instructions

Sensitive recipient details should be minimized and accessed only by assigned workers during the relevant window.

State transitions

A delivery task might use:

planned -> offered -> accepted -> in_progress -> completed
                    \-> rejected
                               \-> failed
planned -> cancelled

Every transition validates actor, version, and prerequisites. Completing a delivery may require all mandatory stops and proof fields. Offline mobile actions carry client event IDs and timestamps for idempotent synchronization.

Dispatch

Dispatch can begin manually. The operator sees eligible couriers based on team, shift, capacity, current task, freshness, and distance. Automated optimization can be added later behind an interface.

Do not make a routing optimizer the source of task truth. It proposes an assignment or order; the task service records the accepted decision and reason.

Arrival and completion

A geofence can suggest arrival, but the mobile user confirms when business rules require it. GPS uncertainty, multi-story buildings, and poor reception make automatic completion unsafe.

Store evidence separately:

proofs_of_delivery
  id
  task_stop_id
  proof_type
  file_id
  captured_at
  captured_by
  latitude_coarse
  signature_metadata
  retention_policy_id

Files use a provider-neutral storage adapter. Metadata and authorization remain in PostgreSQL. File paths are generated by the server and never accepted directly from a client.

Upload workflow

A safe upload process can be:

1. create an upload intent for an authorized task;
2. return size, type, and checksum rules;
3. upload to a temporary server endpoint or mounted storage;
4. scan and validate the file;
5. move it to immutable content-addressed storage;
6. attach it to the proof record;
7. delete abandoned temporary files.

Limit image dimensions and decode safely. A claimed content type is not proof of file format.

Signatures

A drawn signature is sensitive and may have legal implications. Record consent text, signer role, time, task, and checksum. Avoid claiming stronger legal status than the workflow provides.

ETA

ETA can begin as a simple calculation based on current distance, recent speed, stop service time, and route integration when available. Expose confidence and last update. A stale location should not produce a precise ETA.

Offline task work

The mobile app maintains an event queue for task transitions and proofs. Each command has an idempotency key and expected resource version. Conflicts are resolved explicitly:

• a task cancelled while the phone was offline cannot simply become completed;
• duplicate completion returns the existing result;
• a proof uploaded for an unassigned task is rejected and retained locally for support review;
• server time and device time are both recorded.

Chapter checklist

A dispatch module should:

• reuse core subjects, sessions, and teams;
• implement explicit task and stop state machines;
• treat optimization as a proposal;
• combine geofence hints with business confirmation;
• store proofs through a validated file workflow;
• handle offline commands idempotently;
• expose ETA confidence and data freshness.