Assign drivers safely with expiring offers

Application background

A rider requests a car. The application looks at recent driver locations, offers the ride to a nearby driver and records an assignment if the driver accepts. Finding someone nearby does not yet reserve that driver's time.

Two riders may be offered the same driver. Location messages can also arrive late, and a dispatch process that paused may wake up after another process has taken over its work.

Example walkthrough

A lease grants temporary ownership of dispatch work. A fencing value is a newer ownership number that lets the data store reject writes from an old owner.

Your assignment

Deliver: Build driver offers and acceptance using recent location data. Prevent competing offers or an outdated dispatcher from assigning the same driver to two rides.

Required behavior: A ride and driver may belong to at most one active assignment. Location search suggests candidates. Accepting an offer conditionally commits the ride, driver and offer under the current dispatch epoch.

The required first milestone is a working local implementation of the behavior above. The numbered implementation steps define the scope. The cloud architecture is a later extension, not something the starter has already provisioned.

Get the code and run the supplied example

The code is in the public junior-to-staff repository. Install Git and Python 3.12+. No AWS account or Python packages are required for this first run. If you already have a checkout, use it and skip cloning.

git clone https://github.com/Soulful-Iris/junior-to-staff.git
cd junior-to-staff
python3 examples/architecture-starts/rideshare_dispatch.py

Supplied file: examples/architecture-starts/rideshare_dispatch.py. You can also read or download the source here (download file, source below).

"""Local mechanism demonstration for rideshare-dispatch. No AWS resources are created."""
rides={'r1':None,'r2':None}; drivers={'d7':None}
def accept(ride,driver):
    if rides[ride] is not None or drivers[driver] is not None: return '409 already assigned'
    rides[ride]=driver; drivers[driver]=ride; return 'assignment committed'
print(accept('r1','d7')); print(accept('r2','d7')); print(rides,drivers)
latest={'seq':9,'cell':'north'}
for seq,cell in [(8,'south'),(10,'east')]:
    if seq>latest['seq']: latest.update(seq=seq,cell=cell)
print('Latest location:',latest)

This program is a mechanism demonstration: it runs the small scenario in one process and prints the result. It is not an HTTP service, a complete application, or an AWS deployment. A successful run demonstrates this mechanism only. It does not establish the workload or failure guarantees of the application you will build.

Example output from the supplied run:

Generated IDs and timestamps may differ. Compare the state transitions and outcomes.

assignment committed
409 already assigned
{'r1': 'd7', 'r2': None} {'d7': 'r1'}
Latest location: {'seq': 10, 'cell': 'east'}

Set up your implementation workspace

Create work/rideshare-dispatch/ in your checkout (or use a separate repository). Copy the supplied mechanism into that directory as mechanism.py, then extract its state transitions into functions you can call from your implementation. The record and module names below describe what you must implement. They are not a promise that files with those names already exist. Keep a README.md beside your implementation with its exact run commands and observed results.

Local components and state to implement

This table names the records, interfaces or decision inputs for your deliverable. Unless a name is explicitly linked to supplied source above, it is something you create. Implement the local state transitions first, then connect the HTTP, storage or worker boundaries required by the steps.

Implement the assignment

1. Build regional candidate lookup

Partition positions by geographic cell and region. Accept only newer per-driver sequence updates. Expire stale locations. Query neighboring cells and rank by estimated pickup time. A geo index may contain a driver who is already assigned, so treat each candidate as provisional.

2. Create a versioned offer

Persist ride, driver, expiry and dispatcher epoch. Deliver the offer with a stable offer ID. The mobile client shows its expiration and sends that exact ID when accepting, rather than submitting a new free-form driver choice.

3. Commit both owners together

In DynamoDB TransactWriteItems, update ride and driver with availability conditions and update the offer with epoch/expiry conditions. All conditions belong to that single transaction. On conflict, fetch current ride status before trying another candidate.

4. Handle disconnects and cancellation

A new dispatcher increments ownership epoch before issuing replacement offers. Old acceptances and old dispatchers fail conditional writes. Cancellation releases a driver only if the assignment ID still matches. It cannot clear a newer assignment.

Demonstrate the completed local result

Handoff: In your implementation README, include the start command, one successful operation, the failure case above and the resulting stored state or decision. State which dependencies are simulated. Someone with a fresh checkout should be able to reproduce this without your chat history.

Workload assumptions and capacity decisions

These are constructed exercise assumptions. The stated workload is a design target. The local demonstration does not establish that throughput. Use the estimation constants to check units before choosing capacity.

Map the local implementation to AWS

Deployment status: local only. Running the supplied command creates no AWS resources and configures no cloud connections. The diagram is a proposed deployment of the completed application. Each box needs either a deployed runtime, a provisioned service or an explicitly external dependency.

Read the diagram by following the arrows from the entry point: application code accepts the request or event, the state owner commits it, and any worker produces the later result. The table ties those roles to code and adapter work. Multiple boxes do not imply multiple Python files already exist.

The high-volume location path can drop obsolete updates. The assignment path cannot drop ownership conflicts. Keeping those paths separate prevents a fast but stale geo cache from assigning one driver twice.

Provision resources, then connect the application

Use one disposable AWS environment for the cloud exercise. Put the named resources in infra/template.yaml or your existing IaC tool, pass resource IDs through configuration, and scope each runtime role to its own tables, buckets and queues. The diagram is a design to implement. It is not a claim that these resources have been deployed. Record the commands you used to deploy and remove the exercise resources.

For concrete provisioning commands, configuration wiring and cleanup, use the AWS foundation guide. It includes a deployable table/queue/object-storage foundation and explains which application and service adapters you still implement.

A provisioned queue or table does not make the local program use it. Configure resource IDs in the deployed runtime, replace the local adapter, and replay the same successful and failing operation against that runtime. Record the deployed commit and observable result, then remove the disposable resources using your infrastructure tool.

Extend the design after the baseline works

Worked follow-up: Keep one driver owner during a region crossing

A GPS update makes the driver visible in region B before an offer from A expires. If B treats location as ownership, it may assign the driver to another rider.

Revised architecture. Follow the changed responsibility and failure path below. This is a design to implement. The supplied local example does not provision these components.

What to implement. Separate the location index from an assignment record with owner_region and generation. Keep A authoritative until the active offer is accepted, rejected or expires. A later handoff first fences A, transfers the current assignment state, then enables B under a new generation. Stale offers carry the old generation and cannot be accepted. Regional indexes remain candidate discovery only. Use the conditional database write as the acceptance boundary.

Walk through the result. Driver D appears in B while offer O from A is active. B can discover D but cannot issue a competing accepted assignment. After transfer to generation 8, replay acceptance of generation 7. It must fail without changing the new assignment. Show both rider-facing outcomes.

Let a driver cross a regional boundary while an offer is active. Choose one assignment authority until the ride completes or perform an explicit authority transfer. Do not independently mark the driver free in both regions.