Tasuki · Last-mile delivery platform
The delivery side of a business, run in your own cloud.
- Status
- Phase 1 of 7 · proven locally
- Licence
- MIT
- On GitHub
- ★ 1 · ⑂ 0
- orders/h at full design scale, on one laptop
- 18,144
- GPS points/s, with 0 failed orders
- 641
- game-day plans; the first one run, with a postmortem
- 12
Why it exists
Tasuki is the delivery side of a business, as software you deploy next to your own. Your system creates a delivery over the API. Tasuki quotes a price and an arrival time, finds the nearest courier, streams the courier's position to the customer's phone, and reports every status change back.
The name is the sash that relay runners hand to each other in an ekiden race. The design is sized for 1.5 million orders a month in one city, and the repository builds a thin slice through each hard problem in a platform like this, with the reasoning written down.
The reference deployment is Tokyo's 23 wards on real Tokyo roads. The company is fictional, and the merchants, couriers and customers are simulated.
What it does
Orders that are never lost or charged twice
Every order carries an idempotency key, and a transactional outbox takes it from the API to Kafka, so a retry or a crash cannot create a second order.
Live fleet data
A Go service takes courier GPS updates into Kafka, and a cache is rebuilt from that log. The design target is about 750 updates a second.
Dispatch on real roads
Couriers are matched using road distances from OSRM on a bicycle graph of Tokyo. Without OSRM, dispatch falls back to straight-line distance and still works.
A live map and a tracking page
A React console shows the fleet on a map, and every order has a tracking link the customer can open.
A simulated city
A simulator plays merchants, customers and couriers through the public APIs, with scenarios such as a rainy Friday, so the platform can be tested under load.
Operated like a production service
Written SLOs with burn-rate alerts, dashboards kept as code, a runbook for each alert, a threat model, architecture decision records and game-day plans.
How it works
- 01
Your system creates a delivery
It sends the order to the API with an idempotency key. The API answers with a price, an arrival time and a tracking link.
- 02
The order is published
The order and an outbox row are saved in one PostgreSQL transaction. A relay publishes the event to Kafka.
- 03
A courier is assigned
Dispatch picks the nearest available courier.
- 04
The customer follows along
Courier positions flow through the ingest service to the tracking service, which sends them to the tracking page.
Run it yourself
One command builds and starts PostgreSQL, Kafka, Valkey and every service. You need Docker with Compose v2 and GNU Make 4 (on macOS: brew install make, then type gmake).
$ git clone https://github.com/codewithmuh/tasuki-delivery-platform.git$ cd tasuki-delivery-platform$ cp .env.example .env$ make up$ make sim-up- Live map: http://localhost:8088
- Orders API: http://localhost:8000
- make sim-up starts the simulator: it seeds merchants and couriers, then orders flow.
- make routing-up adds OSRM on real Tokyo roads (the first build takes 10 to 20 minutes).
Stack
Where it stands
Built
- Orders: quotes, idempotent orders and the outbox relay, tested against PostgreSQL races
- Fleet ingest, fleet state and tracking
- Routing on Tokyo roads, the simulator and the live console
- SLOs, alerts, the rollout gate and dashboards
Not yet
- Any city: zones from a GeoJSON file, with configurable currency and tax
- Signed webhooks and a dashboard with login
- A courier app
- A single-server install and a Helm chart
- The first run on a real AWS cluster, which is deliberately the last phase
The company is fictional and the traffic is simulated. The EKS and GitOps layers are written and checked, not yet run on a cluster.
Questions
- Is Tasuki a real delivery company?
- No. Tasuki is a fictional company, used to build a real platform. The traffic comes from a simulator.
- Can I run it on my laptop?
- Yes. One command starts PostgreSQL, Kafka, Valkey and every service with Docker Compose.
- Does it only work for Tokyo?
- The reference deployment uses Tokyo's 23 wards. Making zones, currency and tax configurable for any city is the next phase.
- Is it running on AWS?
- Not yet. The Terraform and GitOps layers are written and checked; running them on a cluster is the last phase of the roadmap.
- What licence is it under?
- MIT.
Want Tasuki running for your team, or something like it built?