Telegram Bot with Admin Panel Starter

A starter template for building a Telegram bot with a web-based admin panel.

Stack:

• Backend: NestJS 11, TypeORM, PostgreSQL, Grammy (Telegram Bot)
• Frontend: React, Vite, Mantine UI
• Infrastructure: Docker Compose

Requirements:

• Node.js v20+ (v22 recommended)
• pnpm 9+

Getting Started

1. Set up environment

cp .env.example .env
# Edit .env with your values (database credentials, Telegram bot token, etc.)

2. Run with Docker (development)

docker compose -f compose.dev.yml up -d

3. Create super admin

docker exec -it ${PROJECT_NAME}_back sh
pnpm console admin create {username} {email}

4. Run frontend (development)

cd front
npm install
npm run dev

5. Run migrations

Migrations are run automatically on container start. To run manually:

cd back
pnpm migration:run

Create a new migration

cd back
pnpm migration:generate --name=my-migration-name

Project Structure

├── back/                # NestJS backend
│   └── src/
│       ├── admin-console/   # CLI commands (create admin)
│       ├── admins/          # Admin user management
│       ├── auth/            # JWT authentication
│       ├── bot/             # Telegram bot service
│       ├── common/          # Shared utilities, decorators, entities
│       ├── config/          # Environment validation
│       └── database/        # TypeORM setup & migrations
├── front/               # React admin panel
│   └── src/
│       ├── api/             # API client (axios, react-query)
│       ├── components/      # Reusable UI components
│       ├── guards/          # Auth & guest route guards
│       ├── hooks/           # Custom hooks (auth, API)
│       ├── layouts/         # Auth & dashboard layouts
│       ├── pages/           # Page components
│       ├── providers/       # Context providers
│       ├── routes/          # Routing configuration
│       └── theme/           # Mantine theme customization
├── compose.yml          # Docker Compose (production)
├── compose.dev.yml      # Docker Compose (development)
└── backup.sh            # Database & uploads backup script

Features

• JWT-based admin authentication
• Admin CRUD with role management (superadmin / admin)
• Telegram bot skeleton with Grammy
• Data table with pagination, sorting, filtering
• Dark/light theme
• Docker-based development & production setup
• Database backup with Telegram notification
• Localization system - Multi-language support for bot messages

🌐 Localization System

The project includes a comprehensive localization system that allows admins to manage translations for bot messages.

Overview

The localization system consists of:

• Languages (langs) - Supported languages with settings (slug, title, active status, text direction, date format)
• Wordbooks (wordbooks) - Collections of words grouped by functionality (e.g., "commands", "errors", "messages")
• Words (words) - Individual translation keys (marks) within a wordbook
• Translations (word_translations) - Actual translated text for each word in each language

Admin Usage

Managing Languages

1. Navigate to Dashboard → Localization → Languages

2. Create a new language:

   • Click "Create Language"
   • Fill in:
     • Slug: Language code (e.g., en, ru, uk)
     • Title: Display name (e.g., "English", "Русский")
     • Active: Enable/disable language (only active languages are loaded for bot)
     • Direction: Text direction (ltr or rtl)
     • Date Format: Date format preference (en or ru)
   • Save

3. Edit/Delete languages:

   • Click on a language in the table to edit
   • Protected languages (marked as defended) cannot be deleted

Managing Wordbooks

1. Navigate to Dashboard → Localization → Wordbooks

2. Create a new wordbook:

   • Click "Create Wordbook"
   • Fill in:
     • Name: Unique wordbook identifier (e.g., commands, errors, messages)
     • Load To: Where the wordbook is used:
       • all - Available for both bot and admin panel
       • bot - Only for Telegram bot
   • Optionally add words during creation
   • Save

3. Edit a wordbook:

   • Click on a wordbook in the table
   • Edit wordbook name and load_to setting
   • Manage words:
     • Add word: Click "Add Word" button
     • Edit word: Modify the mark (key) or translations
     • Delete word: Click delete icon (⚠️ words with translations will be removed)

Adding Translations

1. Open a wordbook for editing

2. For each word, you'll see translation fields for all active languages

3. Add translations:

   • Enter translated text in the corresponding language field
   • Translations are saved automatically when you update the wordbook
   • Empty translations are allowed (will be null in database)

4. Translation workflow:

   • When you add a new word, translation fields are automatically created for all existing languages
   • When you add a new language, you'll need to add translations for existing words manually
   • Use the language tabs to switch between languages while editing

Best Practices

• Wordbook naming: Use descriptive, lowercase names (e.g., commands, errors, buttons)
• Word marks: Use clear, descriptive keys (e.g., start_command, error_not_found, button_submit)
• Language slugs: Follow ISO 639-1 standard (2-letter codes) or ISO 639-2 (3-letter codes)
• Protected items: Mark system languages and wordbooks as defended to prevent accidental deletion
• Active languages: Only mark languages as active if translations are ready (inactive languages won't be loaded by bot)

Bot Integration

The bot automatically loads all active wordbooks marked with load_to: 'all' or load_to: 'bot' on startup. Translations are cached in memory for fast access. The cache is automatically reloaded when wordbooks are updated through the admin panel.

🤖 Development with AI Assistants

This project is optimized for development with LLM assistants like Cursor AI, GitHub Copilot, etc.

Key Files for AI Understanding:

• .cursorrules - Project conventions, code style, and common patterns
• AGENTS.md - Comprehensive architecture documentation and system design
• EXAMPLES.md - API usage examples, code patterns, and implementation guides

Quick Start for AI:

1. Read .cursorrules for code style and conventions
2. Check AGENTS.md for architecture overview and module structure
3. See EXAMPLES.md for implementation patterns and API usage
4. Follow the module structure: Entity → DTO → Service → Controller → Module

Common Tasks:

• Adding a new feature: See AGENTS.md → Development Workflow
• Creating API endpoints: See EXAMPLES.md → Frontend Usage Examples
• Adding bot commands: See EXAMPLES.md → Telegram Bot Examples
• Database migrations: See EXAMPLES.md → Database Migration Examples