ADR-003: The kiosk never waits for generation

Who is this for

Developers and the owner — read this before adding anything that keeps a guest at the tablet.

TL;DR

After the photo is uploaded the tablet is free for the next guest at once.
The result is delivered later, by the bot, to the guest’s own Telegram chat.
Status: accepted. This is a hard project rule and a public promise on the landing page.

Context

Generation takes about a minute in the best case and several minutes in the worst. A station that shows a progress bar serves one guest per generation and builds a line of people. The value of the activation is throughput and a pleasant surprise, not watching a spinner.

Decision

POST /session/{token}/photo validates the image, stores it, creates a job with status queued and answers. The “Generating…” message to the guest is sent in a background task after the response (bot/api.py).
A worker loop inside the bot process takes jobs from the queue (bot/worker.py).
Delivery deadlines are measured from the moment the job was created and stored in the database, so they survive restarts: one delay notice after 5 minutes, failure after 15 (bot/delivery.py).

Alternatives considered

Alternative	Why not
Show the result on the tablet	Blocks the station; needs a second screen to scale.
Show a QR code to a result web page	The pack lives in Telegram anyway, and the bot chat is already open on the guest’s phone.

Consequences

The guest must have started the bot before the photo — which the consent step already guarantees.
Failures are invisible at the station. They need alerts and a manual path: see Pack not delivered.
If the guest blocks the bot, the link cannot be sent; staff can read it from the admin panel.

Evidence

CLAUDE.md, hard rule 5.
Load test report: with one guest every 60–90 seconds the queue wait averaged 0.4 s.

Where to go next

Last verified: 2026-11-13 against ai-sticker-pack@b715418 and ai-stickers-landing@e350ff5.