# haul

> An open, end-to-end marketplace storefront in Kotlin, running in public: catalog, search, cart, sign-in, checkout, an order split across sellers, delivery, returns and refunds — every screen a tree the server sends and Compose on WebAssembly draws.

Page: https://kotlin.website/haul

## Why it exists

[haul](https://github.com/youndie/haul) puts a whole Kotlin stack through a real product rather than
a demo app, and it runs in public at **[haul.kotlin.website](https://haul.kotlin.website)**. Every
screen is a tree the server builds and the browser draws with Compose Multiplatform on WebAssembly;
an order is a saga that reserves, authorises and undoes in reverse; and synthetic shoppers walk the
stand every ten minutes, so there is always an order moving through it.

The sellers, the couriers and the card processor are simulated inside the server, so the stand
integrates with nothing and charges nobody.

## What to look at in five minutes

1. **Open [the stand](https://haul.kotlin.website)**, and its [About this demo](https://haul.kotlin.website/about)
   page, which says what is real and what is not.
2. **Read a page as the server sends it** — `curl https://haul.kotlin.website/ui/home` is the home
   page you just saw.
3. **Open «Under the hood»** in the line above the page: it outlines the tree the page is drawn from,
   each component linked to the view that draws it and the server file that builds it, and the request
   that brought it with its size and the server's time.
4. **Change a filter with the network tab open.** Only the parts that changed arrive, as an update
   naming the nodes it replaces, and the address follows without a reload.
5. **Watch [Live orders](https://haul.kotlin.website/live)** — the last twenty sagas, each step
   lighting up as it happens, and one walk in ten declined with the steps before it undone.
6. **Read [The stack in numbers](https://haul.kotlin.website/numbers)** — start with and without the
   AOT cache, latency and CPU per request, memory inside the chart's limit, with the raw runs committed.

## The stack

| Layer | What | |
|---|---|---|
| Server | Ktor on the JVM, PostgreSQL through Exposed and Flyway, an AOT cache trained at image build | [zavarnik](https://kotlin.website/zavarnik) |
| Screens | every screen a server-driven tree; filters, steppers and tabs answer with partial updates | [kompot](https://kotlin.website/kompot) |
| Client | Compose Multiplatform for the web (Kotlin/Wasm); the same code renders the screenshot tests | [viddik](https://kotlin.website/viddik) |
| Order | reserve stock, a delivery slot and points, authorise the card, open the order — and undo in reverse | [petich](https://kotlin.website/petich) |
| Sign-in | an OpenID Connect provider of its own, deployed beside the store | [shildik](https://kotlin.website/shildik) |
| Watching | logs and traces, route metrics, crash reports — each order's saga is one list in the log | [tracy](https://kotlin.website/tracy), [metrik](https://kotlin.website/metrik), [katcher](https://kotlin.website/katcher) |

The same storefront also runs as a desktop app, drawing the same server trees with the same
renderers in a window, and signing in through the system's browser.

## Run it

The image is public. A database and the server, seeded with the sample catalogue:

```bash
docker network create haul
docker run -d --name haul-db --network haul -e POSTGRES_DB=haul -e POSTGRES_USER=haul -e POSTGRES_PASSWORD=haul postgres:18-alpine
docker run -d --name haul --network haul -p 8080:8080 -e HAUL_DB_URL=jdbc:postgresql://haul-db:5432/haul -e HAUL_DB_USER=haul -e HAUL_DB_PASSWORD=haul -e HAUL_SEED=true ghcr.io/youndie/haul-server:v0.7.2
```

Then open <http://localhost:8080>. Sign-in stays off until the server is given a provider; browsing,
search and a guest's cart work without one. The Helm chart in `charts/haul` is what the public stand
runs.

## Numbers, honestly

- **First load**: the first frame at about **0.6 s** on loopback, **5.2 s** on DevTools' Fast 4G and
  **26 s** on Slow 4G. The app is 1.27 MB of brotli-compressed WebAssembly; a static frame stands in
  while it loads.
- **Checks on every pull request**: about 540 server tests against a real PostgreSQL, about 490 client
  tests, about 180 screenshot goldens, the image with its AOT cache, the chart, and the whole
  buy-receive-return path over HTTP.
- **Releases are walked** against a catalogue of 155 QA cases, and each run's result is committed.

## What it is not

A storefront, not a marketplace business: nobody sells, ships or pays, and the cards are test cards.
The catalogue is generated and its pictures are drawn by the server. Screen readers get a name for
every control, but Compose for the web (1.12) does not yet tell them a box is ticked — the name says it
instead.
