Telegram SaaS Framework

A framework for building production-ready Telegram bots in one evening

Telegram SaaS Base is a private framework I use to launch my own Telegram products. 28+ ready-made modules, built-in multi-tenancy, 5 payment providers, AI integration, and Web Mini App support in a single codebase.

Score 1000 points Mail to TG

t.me/Nabery1000BalivBot

12,000 players in the first month

28+ modules out of the box

3 minutes to your first bot

Vadym Chief Architect

Tags

AsyncLocalStorage Bot Framework BullMQ Docker Gemini grammY HMAC-SHA256 JWT LiqPay Monobank Multi-Tenant Next.js Nodemailer OpenAI PostgreSQL Prisma React Redis S3 SaaS shadcn/ui Stripe Tailwind CSS Telegram Bot API Telegram Stars TypeScript Vertical Slice Architecture Web Mini App Zod Zustand

Stack

AsyncLocalStorage Bot Framework BullMQ Docker Gemini grammY HMAC-SHA256 JWT LiqPay Monobank Multi-Tenant Next.js Nodemailer OpenAI PostgreSQL Prisma React Redis S3 SaaS shadcn/ui Stripe Tailwind CSS Telegram Bot API Telegram Stars TypeScript Vertical Slice Architecture Web Mini App Zod Zustand

About the project

Telegram SaaS Base is a private personal framework I built to launch my own Telegram products quickly. Every time I need a new bot, I don’t start from scratch: I create a token, register the bot in the admin panel, select the required modules, configure them through the UI and set the webhook. The first bot with payments, localization and analytics takes about three minutes.

The framework is built on Next.js 16 with App Router, React 19, PostgreSQL 16, Redis 7, BullMQ for queues and grammY for the Telegram Bot API. All code is typed with TypeScript. The architecture follows vertical slices: each module is isolated and owns its route handlers, database schema, admin panel UI components and message handlers. Adding a new module requires no changes to the core.

The same codebase operates simultaneously in two modes: as a native Telegram Bot with commands, inline keyboards and callbacks, and as a Telegram Web Mini App with a full React interface. The admin panel manages all bots from a single point and supports multi-tenancy via AsyncLocalStorage with no direct tenant_id queries anywhere in the business logic.

Unified Dispatcher: one pipeline for the bot and the web

The central architectural challenge of the framework is this: a Telegram Bot runs via webhook or polling, receiving Update objects from the Telegram API — a server process with its own event loop. A Web Mini App runs via browser HTTP requests — standard Next.js routing. The admin panel makes REST calls to the API. These are three fundamentally different transport layers with different request-response models, different authorization systems and different data formats.

The naive approach is three separate code paths, with duplicated business logic or a separate abstraction layer per transport. Telegram SaaS Base solves this differently: a single Dispatcher — the Adapter pattern — normalizes all incoming events to a unified internal format. Telegram Update, HTTP Request and WebSocket messages pass through one middleware stack before reaching the module’s business logic. This stack sets the tenant context via AsyncLocalStorage, checks authorization, resolves the user and writes to the audit log. All of this happens once, regardless of transport.

The consequence: modules are written with no transport awareness. The same payment processing method works whether it is called via a Telegram command or via the Web Mini App. No duplication, no if (isTelegram) in business code.

@Module('referral')
class ReferralModule extends BaseModule {

  @BotCommand('/referral', 'Referral program')
  async handleReferral(ctx: BotContext): Promise<void> {
    const user = ModuleContext.getUser();
    const stats = await this.referralService.getStats(user.id);
    await ctx.reply(this.i18n.t('referral.stats', stats));
  }

  @CallbackQuery('referral:share')
  async handleShare(ctx: BotContext): Promise<void> {
    await ctx.answerCallbackQuery();
    await ctx.reply(this.referralService.buildShareLink());
  }

  @BotAction(/^referral_code_(.+)$/)
  async handleCode(ctx: BotContext): Promise<void> {
    const code = ctx.match[1];
    await this.referralService.applyCode(
      ModuleContext.getUser().id,
      code
    );
  }
}

Vertical slices: a module as a self-contained unit

Module architecture in Telegram SaaS Base follows the Vertical Slice pattern: each module contains everything it needs to operate. Not a service layer with shared repositories, not horizontal slicing by file type — a vertical slice from bot handlers through the database schema to admin panel UI components.

The module structure is fixed: handlers/ with decorated methods, services/ with business logic, schema.prisma with the database schema, admin/ with React components and admin API routes, i18n/ with translations, index.ts as entry point. When setting up a new bot, modules are connected via the manifest in one line. Database schemas are merged automatically by a merge script, then a single Prisma migration is run.

A practical consequence for development: when working on a specific module, you open one directory and see everything — handlers, logic, schema, UI. No need to jump between controllers/, services/, repositories/, models/ in different parts of the tree. This is especially valuable when moving or removing a module: it moves as a single package.

// modules/referral/schema.prisma
model ReferralCode {
  id         String   @id @default(cuid())
  botId      String
  code       String   @unique
  ownerId    String
  usageCount Int      @default(0)
  reward     Int      @default(0)
  createdAt  DateTime @default(now())

  bot        Bot           @relation(fields: [botId], references: [id])
  usages     ReferralUsage[]
}

model ReferralUsage {
  id         String   @id @default(cuid())
  codeId     String
  userId     String
  createdAt  DateTime @default(now())

  code       ReferralCode @relation(fields: [codeId], references: [id])
}

// After merge: npx prisma migrate dev

Multi-tenancy: one framework, many bots

When the framework serves multiple bots simultaneously, the classic multi-tenant problem arises: how to guarantee data isolation between tenants without business logic ever knowing multi-tenancy exists. Adding WHERE bot_id = $1 to every SQL query is not a solution — it is a source of bugs.

In Telegram SaaS Base, multi-tenancy is implemented via Node.js AsyncLocalStorage. When the Dispatcher receives an incoming request it identifies the tenant (bot) by token or request header, loads the tenant configuration and stores it in the AsyncLocalStorage store for the duration of the request. Any code within that request — module business logic, Payment Service, AI adapter — retrieves the tenant context via ModuleContext.getTenant() without any explicit argument.

The result: modules are written with no awareness of multi-tenancy. The referral service calculates stats — it simply works with data from the current tenant. The payment module selects a provider — from the current tenant’s configuration. No passing tenantId through call chains, no data leaks between bots. AsyncLocalStorage guarantees isolation at the event-loop level, even with parallel requests inside a single Node.js process.

AI integration: two providers out of the box, any new one in two lines

The framework ships with two AI providers: OpenAI (GPT-4o, GPT-4-Turbo and all models via a single API) and Google Gemini (Gemini 1.5 Pro and Flash). Both providers implement a common IAIProvider interface with complete(), chat() and embed() methods. A module that needs AI retrieves the provider via ModuleContext.getAI() — the tenant selects the provider in settings, while the module code has no dependency on any specific AI.

Adding a new provider means implementing the IAIProvider interface and registering the class in the factory. This takes roughly two lines in the configuration file. No changes to modules already using AI. Strategy Pattern in its pure form: the algorithm (provider) is swapped without changing the context (module).

The most impactful practical feature is AI-driven bot translation. The admin panel collects all localization strings from all active modules, sends them to AI with a system prompt to preserve formatting, receives translations and saves them to the database. The administrator reviews the result in a table and edits manually if needed. The entire bot is translated into a new language in a single request with no deployment.

Localization: i18n as a first-class citizen

Every module in the framework contains an i18n/ directory with translation files in JSON format. Translation keys are typed: TypeScript knows all available localization keys for a module, autocomplete works in the IDE, and errors in keys are caught at compile time. On startup the application loads translations from all active modules and merges them into a single namespace partitioned by module name.

Calling a translation in code: this.i18n.t('referral.invite_text', { count: stats.referrals }). No magic strings, no runtime errors from missing keys. Supports interpolation, pluralization and nested keys. Language is resolved from the tenant’s settings, or from the Telegram user’s language preferences where needed.

AI translation is integrated into the admin panel: one button collects all strings from active modules, sends them to AI and saves the results. The entire bot is translated in a single request. A diff mechanism translates only the added or changed strings when modules are updated.

Other our projects

All projects

Full-Stack Development

Exif Cleaner: Privacy-First Metadata Remover

Privacy-first mobile app for viewing and removing EXIF metadata from photos

Full-Stack Development

MUDRAVA Admin Tweaks: 30+ WordPress admin tweaks in a single, lightweight plugin

Drop-in toolkit of 30+ admin-area tweaks for WordPress

Full-Stack Development

Kepler-452 Mobile: React Native Funding Rate Tracker

iOS and Android funding rate tracker for crypto traders across 7 exchanges