Overview — what ShopBot is

ShopBot is a self-contained demo of a Telegram shopping bot that takes real orders and payments, backed by its own inventory service and a live dashboard. It exists to show someone how a chat-driven shop hangs together end to end: a customer messages a Telegram bot, an AI agent answers, checks stock, places an order, and hands back a Paystack payment link — and a business owner watches the whole thing happen in real time on a wall-board.

The two halves

ShopBot is one app, two services (/root/apps/shopbot/), run together by one docker-compose.yml:

1. n8n — the bot's brain and wiring. A self-hosted workflow tool hosting a single workflow: a Telegram trigger → an AI agent (OpenAI gpt-4o-mini) with conversation memory and a handful of HTTP "tools" → a Telegram reply. n8n is the thing that turns "2 power banks please" into the right backend calls. Lives at n8n.oaoisme.top.
2. The inventory backend — the shop itself. A small Fastify + SQLite service that owns the catalogue, stock, orders and payments, serves a live dashboard, and verifies Paystack webhooks. Lives at inventory.oaoisme.top.

The bot never holds shop data; it asks the backend over a private network. The backend never talks to Telegram; it just answers questions and emits live events. That separation is the whole point — either half could be swapped out.

What a customer does

"What do you sell?" → "Do you have 2 power banks?" → "Order 2" → (confirms) → "Here's your payment link" → (pays with a test card) → "Payment received ✓"

Every step is a real backend call. When the payment clears, Paystack calls the backend, the order flips to paid, and stock drops — and the dashboard shows it within the second.

What's real vs. what needs keys

This was built and proven without live third-party credentials:

• The inventory API, the Paystack logic (signature verify, mark-paid, stock decrement, idempotent replay — tested with a mock secret), and the dashboard (Playwright-tested against the live HTTPS URL, 26/26, zero console errors).
• The n8n workflow imports cleanly into n8n 2.27.

To go fully live, three credentials the owner must supply: a Telegram bot token, an OpenAI API key, and Paystack test keys. The RUNBOOK (/root/apps/shopbot/RUNBOOK.md) walks through turning those keys.

Where to read next

• Architecture — the two services, the private network, and why the ports are bound the way they are.
• The inventory backend — data model, the kobo money rule, and the API surface.
• Payments — the Paystack initialize + webhook flow and why stock decrements only on a verified payment.
• The live dashboard — Server-Sent Events, the "Counter" design language, and the e2e bar.
• The n8n agent — the workflow, its tools, and how the bot is kept honest.