> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moorcheh.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Retail Kiosk
> In-store assistant demo with Admin + Customer UI, Arduino UNO Q voice, and Moorcheh Edge RAG.
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
```bash theme={null}
git clone https://github.com/moorcheh-ai/retail-kiosk.git
cd retail-kiosk
```
Overview and architecture: repo **[README](https://github.com/moorcheh-ai/retail-kiosk/blob/main/README.md)**. Full setup, configuration, and troubleshooting: **[QUICKSTART.md](https://github.com/moorcheh-ai/retail-kiosk/blob/main/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)](https://www.figma.com/board/YiBj2eVpuqvkqL2RNyDmp2/Retail-Kiosk-with-Moorcheh?node-id=17-113\&t=LmeUJtEsBJ6TDGrI-0)
Install and run Moorcheh Edge on the UNO Q first. See [Arduino UNO Q](/guides/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](/api-references/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:
```bash theme={null}
ssh arduino@
```
Install once (venv + CLI), then each session:
```bash theme={null}
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](#kiosk-audio-cache) commands. In a second terminal:
```bash theme={null}
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`](/cli/voice/setup):
```bash theme={null}
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`](/api-references/voice-serve#post-askstream), 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:
```powershell theme={null}
scp tests/brew-corner-catalog.json arduino@:~/
scp tests/upload-catalog-to-edge.py arduino@:~/
```
On the UNO Q:
```bash theme={null}
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
```bash theme={null}
cd retail-kiosk
pip install .
cd frontend && npm install
```
Run the API and UI (set `` from the board):
```powershell theme={null}
$env:MOORCHEH_EDGE_URL = "http://:8080"
$env:MOORCHEH_VOICE_PROXY_URL = "http://:8766"
retail-kiosk-api
```
Second terminal:
```powershell theme={null}
cd frontend
$env:VITE_API_URL = "http://127.0.0.1:8765"
npm run dev
```
* **Customer:** [http://localhost:5173/](http://localhost:5173/)
* **Admin:** [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`](/api-references/voice-serve#post-askstream) (embed + RAG on device) |
| **Admin save document** | PC API → UNO Q `:8766` [`POST /catalog/document`](/api-references/voice-serve#post-catalogdocument) → chunk, embed, upload to `:8080` |
| **Admin delete document** | PC API → Moorcheh Edge [`DELETE /items`](/api-references/delete) on UNO Q |
| **Sync from UNO Q** | Admin button or `POST /admin/sync-from-edge` on PC API → [`GET /export`](/api-references/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.
```bash theme={null}
curl -X POST "http://127.0.0.1:8765/admin/sync-from-edge"
```
```json 200 - OK theme={null}
{
"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
Install, configure, catalog upload, and troubleshooting
Architecture and Admin/Customer features
Board setup and Moorcheh Edge
`voice setup`, `voice serve`, and related commands
`GET /export` — chunk text for catalog sync
HTTP endpoints on port 8766
Figma guide for mic and speaker