Build restaurant discovery and authoritative checkout

Application background

A customer browses nearby restaurants, sees a meal for £12.50 and adds it to a basket. The browsing page uses a searchable copy of restaurant data so it can respond quickly. The restaurant may change a price or sell out before the customer pays.

At checkout, the application must ask the current menu and inventory records whether it can still accept the order. A price shown earlier is not permission to charge a different amount without telling the customer.

Example walkthrough

The search copy helps users discover meals. The authoritative records are the current records that decide whether an order may be accepted.

Your assignment

Deliver: Build restaurant browsing and order placement. At checkout, check the current price and availability before confirming what the customer agreed to buy.

Required behavior: GET /restaurants searches nearby open restaurants. POST /orders submits item IDs, displayed price version and request identity. The order service revalidates availability and returns either a committed priced order or an explicit change requiring customer acceptance.

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/food_delivery_marketplace.py

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

"""Local mechanism demonstration for food-delivery-marketplace. No AWS resources are created."""
menu={'meal7':{'price':1250,'version':3,'available':True}}
cart={'meal7':{'price':1250,'version':3}}
menu['meal7'].update(price=1400,version=4)
def checkout(cart):
    for item,seen in cart.items():
        current=menu[item]
        if not current['available']: return '409 item unavailable'
        if seen['version']!=current['version']: return {'status':409,'new_price':current['price'],'needs_acceptance':True}
    return 'order accepted'
print(checkout(cart))

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.

{'status': 409, 'new_price': 1400, 'needs_acceptance': True}

Set up your implementation workspace

Create work/food-delivery-marketplace/ 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 discovery as a projection

Store restaurant opening rules, service area and menu revision in the source database. Index geographic/search fields asynchronously. Return an as-of marker and stable IDs. Do not place the only copy of availability in the search index.

2. Make checkout authoritative

Load current items and versions inside the order transaction. Calculate integer minor-unit totals, currency, fees and taxes under an explicit pricing policy. A changed price returns a new quote for acceptance instead of silently charging more.

3. Track fulfillment transitions

Record created, restaurant_accepted, preparing, assigned, delivered or cancelled with conditional versions. A restaurant rejection and a payment success need an explicit refund/reconciliation path. Separate estimated delivery time from a guaranteed promise.

4. Add dispatch and degraded browsing

Use location/routing services for candidate travel estimates. When search indexing lags, show stale discovery honestly and keep authoritative checkout available where possible. Bound restaurant-level order intake so a viral promotion cannot create impossible kitchen demand.

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.

OpenSearch finds candidates. Aurora decides what is being purchased. A location service provides geography and routing, not inventory ownership or a restaurant’s ability to fulfill an order.

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: Coordinate restaurant acceptance before capturing payment

A restaurant cannot fulfill an item even though discovery showed it available. Capturing money and declaring success before acceptance leaves the system with a business obligation that a database rollback cannot erase.

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. Persist the accepted quote, promotion version and substitution permissions. Track restaurant acceptance and payment authorization separately. Capture only when the chosen policy permits fulfillment. On timeout, move the order to a visible unresolved or cancellation state and void authorization where supported. A changed price or unapproved substitution creates a new customer decision. Use durable workflow state and idempotent provider adapters, with compensation recorded as its own operation.

Walk through the result. Order O authorizes payment, then the restaurant proposes a more expensive replacement. Show awaiting customer approval with no capture. Decline the replacement and record cancellation plus the authorization-release outcome. If release is uncertain, retain repair work rather than marking every component rolled back.

Add restaurant-specific promotions and substitutions. Define which changes require renewed customer consent and which can be applied within the accepted quote. Preserve the exact accepted policy version.