bot-with-admin-starter/README.md

# 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

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

### 2. Run with Docker (development)

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

### 3. Create super admin

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

### 4. Run frontend (development)

```bash
cd front
npm install
npm run dev
```

### 5. Run migrations

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

```bash
cd back
pnpm migration:run
```

### Create a new migration

```bash
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