Retail Kiosk

Deploy a retail kiosk for a demo store like The Brew Corner: shoppers ask about products and policies by text or voice; answers stream to the screen and play on the Arduino UNO Q speaker. Staff manage the catalog and prompts from an Admin screen; customers use a separate Customer screen (both in one web app for this demo).

Clone the repo

git clone https://github.com/moorcheh-ai/retail-kiosk.git
cd retail-kiosk

Overview and architecture: repo README. Full setup, configuration, and troubleshooting: QUICKSTART.md.

What you need

Machine	Role
Display PC (Windows, Linux, or macOS)	React UI, `retail-kiosk-api`, local SQLite catalog mirror
Arduino UNO Q	Moorcheh Edge (Docker), Ollama, mic + speaker, on-device embed

Hardware (mic, speaker, wiring): Retail Kiosk with Moorcheh (Figma)

Install and run Moorcheh Edge on the UNO Q first. See Arduino UNO Q for venv, Docker, and moorcheh-edge up.

Architecture

Port	Machine	Service
5173	PC	React UI
8765	PC	`retail-kiosk-api`
8766	Arduino UNO Q	`moorcheh-edge voice serve`
8080	Arduino UNO Q	Moorcheh Edge (search + RAG + export)
11434	Arduino UNO Q	Ollama

Quick start (summary)

1. Arduino UNO Q

Find the board IP in Arduino App Lab → Settings → Network Connections. Connect via SSH:

ssh arduino@<UNO_Q_IP>

Install once (venv + CLI), then each session:

source ~/moorcheh-venv/bin/activate
moorcheh-edge up --with-llm --warm-llm -y

After the first successful up, run voice setup once. For the full kiosk experience (welcome + thinking audio), also run the kiosk audio cache commands. In a second terminal:

source ~/moorcheh-venv/bin/activate
moorcheh-edge voice serve --port 8766

Kiosk audio cache

These commands are only for the retail kiosk demo - they pre-generate WAV files used when the Customer UI streams with speak: true. Run once per board after voice setup:

source ~/moorcheh-venv/bin/activate
moorcheh-edge voice cache-holding    # fixed welcome line while RAG runs
moorcheh-edge voice cache-thinking   # soft ambient loop until the answer streams

Command	WAV	When it plays
`voice cache-holding`	Holding welcome	In parallel with search + LLM (`holding_enabled`, default on)
`voice cache-thinking`	Ambient loop	After holding, until answer tokens arrive (`thinking_enabled`, default on)

voice setup tries to create both files automatically; re-run the cache commands if a file is missing or you change voice assets. Disable at runtime with holding_enabled: false or thinking_enabled: false on POST /ask/stream, or set MOORCHEH_THINKING_SOUND=0 on the device.

2. Load demo catalog (before Customer)

Copy the demo catalog to the UNO Q and upload vectors to Moorcheh Edge:

scp tests/brew-corner-catalog.json arduino@<UNO_Q_IP>:~/
scp tests/upload-catalog-to-edge.py arduino@<UNO_Q_IP>:~/

On the UNO Q:

source ~/moorcheh-venv/bin/activate
python ~/upload-catalog-to-edge.py --catalog ~/brew-corner-catalog.json -y

If embedding_model and dimension were null in moorcheh-edge status, they are set after this upload.

3. Display PC

cd retail-kiosk
pip install .
cd frontend && npm install

Run the API and UI (set <UNO_Q_IP> from the board):

$env:MOORCHEH_EDGE_URL = "http://<UNO_Q_IP>:8080"
$env:MOORCHEH_VOICE_PROXY_URL = "http://<UNO_Q_IP>:8766"
retail-kiosk-api

Second terminal:

cd frontend
$env:VITE_API_URL = "http://127.0.0.1:8765"
npm run dev

Customer: http://localhost:5173/
Admin: http://localhost:5173/admin

Configuration

Variable	Where	Description
`MOORCHEH_EDGE_URL`	PC API	Moorcheh Edge on UNO Q (e.g. `http://192.168.1.50:8080`)
`MOORCHEH_VOICE_PROXY_URL`	PC API	Voice server on UNO Q (e.g. `http://192.168.1.50:8766`) — required for customer ask and Admin catalog saves
`VITE_API_URL`	Frontend	API URL (e.g. `http://127.0.0.1:8765`)

Catalog and sync

The UNO Q Moorcheh Edge store is the source of truth for vectors. The PC keeps a SQLite mirror for the Admin UI.

Flow	What happens
Customer ask	PC API → UNO Q `:8766` `/ask/stream` (embed + RAG on device)
Admin save document	PC API → UNO Q `:8766` `POST /catalog/document` → chunk, embed, upload to `:8080`
Admin delete document	PC API → Moorcheh Edge `DELETE /items` on UNO Q
Sync from UNO Q	Admin button or `POST /admin/sync-from-edge` on PC API → `GET /export` on edge → replaces SQLite

After the initial demo upload (step 2), open Admin → Sync from UNO Q to populate the local catalog, or save documents from Admin (each save updates both edge and SQLite).

POST /admin/sync-from-edge

retail-kiosk-api on the PC (port 8765). No request body.

curl -X POST "http://127.0.0.1:8765/admin/sync-from-edge"

{
  "edge_url": "http://192.168.1.50:8080",
  "documents": 12,
  "chunks": 48
}

Requires MOORCHEH_EDGE_URL and MOORCHEH_VOICE_PROXY_URL on the PC API.

Next steps

Quick start

Install, configure, catalog upload, and troubleshooting

Overview

Architecture and Admin/Customer features

Arduino UNO Q

Board setup and Moorcheh Edge

Voice CLI

voice setup, voice serve, and related commands

Export store

GET /export — chunk text for catalog sync

Voice server API

HTTP endpoints on port 8766

Hardware wiring

Figma guide for mic and speaker

Getting Started

Hardware guides

Examples

Clone the repo

What you need

Architecture

Quick start (summary)

1. Arduino UNO Q

Kiosk audio cache

2. Load demo catalog (before Customer)

3. Display PC

Configuration

Catalog and sync

POST /admin/sync-from-edge

Next steps

Quick start

Overview

Arduino UNO Q

Voice CLI

Export store

Voice server API

Hardware wiring

​Clone the repo

​What you need

​Architecture

​Quick start (summary)

​1. Arduino UNO Q

​Kiosk audio cache

​2. Load demo catalog (before Customer)

​3. Display PC

​Configuration

​Catalog and sync

​POST /admin/sync-from-edge

​Next steps

Quick start

Overview

Arduino UNO Q

Voice CLI

Export store

Voice server API

Hardware wiring

Clone the repo

What you need

Architecture

Quick start (summary)

1. Arduino UNO Q

Kiosk audio cache

2. Load demo catalog (before Customer)

3. Display PC

Configuration

Catalog and sync

POST /admin/sync-from-edge

Next steps