work · orderly

Orderly

WhatsApp ordering for kirana shops

Solo: owner app, WhatsApp bot · 2026

ReactSupabaseClerkNode.jsBuilderBot

Orderly: WhatsApp ordering for kirana shops

Problem

Kirana customers already order over WhatsApp, but owners lose track of messages. Orderly adds an always-on bot that answers price and stock questions from the live catalogue, with no app install for the buyer.

In short

-Crash supervisor and 45-second heartbeat, shown live in the owner app.
-Owner replies are relayed to WhatsApp through the bot.
-State-machine order flow, integer paise, Supabase row-level security.

Architecture

A Node.js WhatsApp bot under a crash supervisor, reading the shop catalogue from Supabase and reporting health to the owner app.

System designOne bot process per shop, kept alive by a supervisor. Dashed = logical link; exact transport not shown.

user
external
service
guard
data
client
call
logical link
← scroll →

01Buyer sends a WhatsApp message
02Bot parses the intent and looks up the live catalogue
03Order moves through a state machine in Supabase
04Owner app shows orders and bot heartbeat; owner replies are relayed back

Decisions

+ Rule-based parsing for now- Adding an LLM before the channel is reliable  Reliability of the WhatsApp channel was the bigger problem; an AI parser is the planned next step.

Failure handling

failurehandling

Bot process crashes

Supervisor restarts it; missed heartbeats show in the owner app.

fig.1 System designOne bot process per shop, kept alive by a supervisor. Dashed = logical link; exact transport not shown.

user
external
service
guard
data
client
call
logical link
← scroll →

fig.2 System architectureCurrent build: a QR-linked whatsapp-web.js session, one bot process per shop.

Customer on WhatsApp
no app install
user
whatsapp-web.js session
linked to the shop's number by QR
external
Bot process (Node.js, BuilderBot)
runs under a crash supervisor
service
reads + writes
Supabase Postgres
shops · items · orders · RLS
data
Owner app
React + Vite · Clerk · orders, chats, inventory
client

fig.3 Message handlingWhat the bot does with one incoming WhatsApp message.

Message arrives
user
group or channel message → ignored
Normalise the phone number
service
Look up the shop in Supabase
data
no shop linked → reply "not linked yet", stop
Classify: greeting · hours · address · delivery · item
service
Item request: search the live catalogue
partial name match · up to 5 results · live price and stock
data
Compose and send the reply
service
lookup fails → log it, still send a short apology
Order status changes go through the state machine
guard

fig.4 Bot supervisorHow the owner knows the bot is alive.

Supervisor starts the bot
service
Heartbeat every 45 s
owner app shows the bot as live
data
Bot crashes
service
restarted automatically
5 crashes within 30 s
supervisor stops restarting; missed heartbeats show in the owner app
guard

fig.5 Order statesFrom the Orderly design notes; the owner drives every transition.

● draft
pending_payment
placed
confirmed
ready
completed

cancelled → refunded
cancelled orders move to refunded once money is returned

fig.6 Decisionswhat I rejected → what I chose, and why

Adding an LLM before the channel is reliable
Rule-based parsing for now
Reliability of the WhatsApp channel was the bigger problem; an AI parser is the planned next step.

fig.7 Failure pathswhat can break → what the system does

Bot process crashes
Supervisor restarts it; missed heartbeats show in the owner app.

Numbers

45 s

Heartbeat interval

○ Hinglish message → structured, priced order with an LLM
○ Eval set of real order messages