Skip to content
shaarurPublic

About

X Store — multi-tenant Telegram-native digital commerce platform

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

X-Store

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


Why X-Store

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.

What X-Store does

For your customers

  • 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.

For your team

  • 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.

How it works

  1. Set up once. Create a Telegram bot with @BotFather, fill in .env, run migrations.
  2. Add your products. Create categories, products, and stock items from the admin panel.
  3. Open the store. Customers find your bot, browse, top up, and buy — entirely in chat.
  4. Answer support. Tickets arrive in your ops chat; reply with attachments in one tap.

Quickstart

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:dev

Open Telegram, message your bot, and press /start.

Architecture

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

The 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

Repository layout

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

Testing

pnpm test              # full monorepo suite
pnpm test:unit         # unit projects only
pnpm test:integration  # integration projects only

Current 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.

Commands

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

Deployment

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_PASSWORD and REDIS_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

Security

  • Secrets live in .env only — never committed (.gitignore enforces .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

License

UNLICENSED — private project.

About

X Store — multi-tenant Telegram-native digital commerce platform

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages