The Telegram-first digital goods store platform
Run a complete store — catalog, wallet, orders, delivery, support — inside one Telegram bot.
Quickstart · Features · Architecture · Layout · Testing · Deployment · Security
Selling digital goods means juggling five tools: a storefront, a payment processor, a stock tracker, a support inbox, and a customer list that never syncs. X-Store replaces all of them with a single Telegram bot — the app your customers already have open.
No website to build. No admin dashboard to log into. Customers press buttons, pay by QR, and receive their goods in the same chat. You run the entire business from your phone.
- A storefront that fits in a chat window. Categories, product pages, and checkout — all inline buttons, no links to follow.
- Wallet-based checkout. Customers top up once (TNG / DuitNow QR), then buy in two taps.
- Instant delivery. Paid orders deliver digital goods straight into the chat — credentials, keys, access, or files.
- A support wizard built in. Customers open a ticket with attachments; your team replies from the admin panel.
- One message at a time. Navigation cleans up after itself, so the chat never turns into a wall of old menus.
- A full admin panel inside Telegram. Manage products, categories, stock, orders, refunds, and broadcasts without leaving the app.
- Role-based access control. Owner, admin, and support roles with per-permission control — one person can handle support while another owns the money.
- Multi-bot notifications. Route order, wallet, and support events to separate bots and chats (ops, finance, support) with configurable per-event rules.
- Audit trail. Every admin action is recorded — who changed what, and when.
- Store Mode. Open or close the storefront in one tap with a custom message; scheduled maintenance, no customer confusion.
- Broadcasts. Message every customer, or a segment, from the admin panel.
- Set up once. Create a Telegram bot with @BotFather, fill in
.env, run migrations. - Add your products. Create categories, products, and stock items from the admin panel.
- Open the store. Customers find your bot, browse, top up, and buy — entirely in chat.
- Answer support. Tickets arrive in your ops chat; reply with attachments in one tap.
Prerequisites: Node.js ≥ 20, pnpm 9, Docker.
cp .env.example .env # fill in BOT_TOKEN, ENCRYPTION_KEY, REDIS_PASSWORD, POSTGRES_PASSWORD
pnpm install
pnpm db:generate # generate Drizzle migrations
pnpm db:migrate # apply migrations
pnpm db:seed # seed default roles and settings
pnpm typecheck && pnpm lint && pnpm test
docker compose -f infrastructure/docker/docker-compose.yml up -d
pnpm bot:devOpen Telegram, message your bot, and press /start.
X-Store is a TypeScript pnpm monorepo. The bot and worker run on tsx with no build step; everything else is a workspace package.
apps/bot grammY Telegram bot — customer UI + admin panel
workers/worker BullMQ background jobs — delivery, broadcasts, cleanup
packages/database Drizzle schema, repositories, migrations, seed
packages/queue BullMQ queue definitions + Redis rate limiter
packages/shared Logger, Money, IDs, errors, state machines, AES-256-GCM crypto
packages/config Zod-validated environment configuration
infrastructure/ Hardened Dockerfiles + compose stack
| Layer | Choice | Why |
|---|---|---|
| Bot framework | grammY 1.x | TypeScript-first Telegram framework |
| Database | PostgreSQL + Drizzle ORM | Type-safe schema as code, SQL migrations |
| Jobs | BullMQ on Redis | Delivery and broadcast queues with retries |
| Runtime | Node 20 + tsx | No build step, direct TS execution |
| Tests | Vitest | Fast, per-workspace unit + integration projects |
| Deployment | Docker Compose | Hardened, non-root, loopback-only data stores |
Detailed contents for orientation:
apps/bot/src/
commands/ Customer + admin command and callback handlers
services/ Business logic — orders, wallet, support, notifications, RBAC
notifications/ Per-event notification renderers
messages/ Message template registry
packages/database/src/
schema/ 34 Drizzle tables
repositories/ Typed data access per aggregate
migrations/ 12 SQL migrations
seed/ Default roles, permissions, store settings
pnpm test # full monorepo suite
pnpm test:unit # unit projects only
pnpm test:integration # integration projects onlyCurrent status: 996 tests across 49 files — 986 passing. The bot workspace (855 tests / 37 files), shared, config, and database packages all pass. A pre-existing failure exists in packages/queue/tests/unit/rate-limiter.test.ts (10 tests) unrelated to the V6 work; it fails on the pushed HEAD and needs separate investigation.
All commands run from the repo root.
| Command | Purpose |
|---|---|
pnpm install |
Install dependencies |
pnpm dev / pnpm bot:dev |
Run the bot locally |
pnpm worker:dev |
Run the background worker |
pnpm typecheck |
TypeScript strict check, all workspaces |
pnpm lint |
ESLint across the monorepo |
pnpm test |
Full test suite |
pnpm db:generate |
Generate migrations from schema |
pnpm db:migrate |
Apply migrations |
pnpm db:seed |
Seed defaults |
pnpm db:backup |
Backup the database |
pnpm db:restore-test |
Test a restore |
X-Store is Telegram-first by design: no web dashboard, no inbound HTTP, no Mini App. The bot long-polls Telegram — the only open port you need is outbound HTTPS.
The Docker stack is hardened for VPS deployment:
- Non-root containers with shared base image
- Loopback-only Postgres and Redis by default (
127.0.0.1) - Redis AUTH required — no open rate-limiter backend
- No default passwords — compose refuses to boot without
POSTGRES_PASSWORDandREDIS_PASSWORD - Memory limits per service and log rotation
- Graceful shutdown — BullMQ workers finish active jobs before stop
docker compose -f infrastructure/docker/docker-compose.yml up -d
# Apply pending migrations (idempotent one-shot; re-run after pulling schema
# changes — e.g. 0012_store_custom_message). Required before first boot and
# after every migration bump, or admin Settings fails to load.
docker compose -f infrastructure/docker/docker-compose.yml --profile tools run --rm migrate- Secrets live in
.envonly — never committed (.gitignoreenforces.env*with!.env.example) - Sensitive stock payloads encrypted at rest with AES-256-GCM
- Zod validates every environment variable at boot — a misconfigured deploy fails fast
- Full admin audit log of every privileged action
- RBAC with 3 roles and per-permission grants
UNLICENSED — private project.