↓Skip to main content
  1. System Design Components/

Archetype 12 — Matching / Assignment #

What this archetype is #

Requests must be matched to one candidate under time and availability constraints.

Examples: rideshare dispatch, courier assignment, matchmaking queue.

We will use driver assignment as the running example.

Layer 1: Entities and Postgres table design #

RequestState
AssignmentState
ExecutionState

create table ride_requests (
  request_id uuid primary key,
  rider_id bigint not null,
  pickup_point point not null,
  status text not null default 'OPEN',
  created_at timestamptz not null default now()
);

create table driver_assignments (
  request_id uuid primary key references ride_requests(request_id),
  driver_id bigint not null,
  status text not null,
  expires_at timestamptz,
  created_at timestamptz not null default now()
);

Spatial/candidate indexes depend on actual location storage.

Layer 2: Write path mechanics #

Use location index or precomputed candidate set.

Assign one driver #

insert into driver_assignments (
  request_id, driver_id, status, expires_at
) values (
  $1, $2, 'OFFERED', now() + interval '20 seconds'
)
on conflict (request_id) do nothing;

Accept assignment #

update driver_assignments
set status = 'ACCEPTED'
where request_id = $1
  and driver_id = $2
  and status = 'OFFERED'
  and expires_at > now();

Layer 3: Fault tolerance #

  • duplicate assignment
  • stale candidate accepted
  • timeout/reassignment race
  • assignment accepted after expiry

Layer 4: Scale #

Default hotspots:

  • candidate lookup breadth
  • hot assignment pool
  • reassignment churn
  • timeout worker load

Common mitigations:

  • narrow candidate set first
  • lease-like expiry on offers
  • separate matcher from execution/driver state
←→ →←