Tasuki · Last-mile delivery platform

The delivery side of a business, run in your own cloud.

The delivery side of a business, as software you run next to your own. Your system creates a delivery over the API; Tasuki quotes a price and an ETA, dispatches the nearest courier on a real city road network, and streams the courier live to the customer's phone. Built to production standards: idempotent orders, a Kafka location pipeline, written SLOs, load tests and game days.
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
01

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.

02

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.

03

How it works

  1. 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.

  2. 02

    The order is published

    The order and an outbox row are saved in one PostgreSQL transaction. A relay publishes the event to Kafka.

  3. 03

    A courier is assigned

    Dispatch picks the nearest available courier.

  4. 04

    The customer follows along

    Courier positions flow through the ingest service to the tracking service, which sends them to the tracking page.

fig. 01orders · locations · operate
CLIENTSYour systemorders apiCouriergps · offersCustomertracking pageSimulatorplays the cityMONEY PATH · DJANGOordersidempotent · quotesPostgreSQLoutbox → relayLOCATION PATH · GOfleet-ingestgps → kafkatrackingsse · reads kafkadispatchoffers over sseKafka3 topics18,144 orders/hmeasured · one laptop641 gps/s · 0 failed ordersfleet-statenewest point / courierValkeycache · rebuilt from logOSRMtokyo roads · 23 wardsOPERATE · AP-NORTHEAST-1 · DASHED = WRITTEN, NOT YET APPLIEDEKS · KarpenterArgo CDKyvernoSLOs · burn raterollout gategame days
04

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).
05

Stack

Orders
DjangoDjango REST FrameworkPostgreSQLTransactional outbox
Fleet
GoKafkaValkey
Routing
OSRM
Console
ReactTypeScriptMapLibre
Platform
TerraformEKSKarpenterArgo CD
Observability
OpenTelemetrySloth SLOsGrafana
06

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.

07

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.
→Work with me

Want Tasuki running for your team, or something like it built?