AnonkaReforged 🚀

A sophisticated, extensible Telegram bot framework that enables anonymous message forwarding with a powerful plugin system. AnonkaReforged allows users to send anonymous messages to a designated channel while maintaining complete privacy and offering extensive customization through plugins.

📋 Table of Contents

• Features
• Requirements
• Installation
• Configuration
• Usage
• Project Structure
• Architecture Overview
• Core Components
• Plugin System
• Localization
• Environment Variables
• Error Handling
• Best Practices
• Contributing
• License

---

✨ Features

Core Functionality

• Anonymous Message Forwarding: Users send messages privately, which are then forwarded to a public channel anonymously
• Bot Ignition System: Automatically filters out messages from other bots to prevent spam
• Multi-language Support: Built-in localization system supporting English, Ukrainian, Russian, Polish, Spanish, German, and French
• Asynchronous Architecture: Uses aiogram (async Telegram bot API wrapper) for high-performance concurrent request handling

Extension & Customization

• Plugin System: Comprehensive plugin architecture for extending bot functionality without modifying core code
• Configuration Management: Environment-based configuration with fallback defaults
• Graceful Cleanup: Proper resource management with async cleanup handlers
• Comprehensive Logging: Detailed logging system for debugging and monitoring

---

📦 Requirements

• Python: 3.9 or higher
• Dependencies:
  • aiogram >= 3.0 (Telegram Bot API wrapper)
  • python-dotenv (Environment variable management)

Installation via pip

pip install aiogram python-dotenv

Installation via requirements.txt

pip install -r requirements.txt

---

🔧 Installation

Step 1: Clone the Repository

git clone https://github.com/cmpdchtr/AnonkaReforged.git
cd AnonkaReforged

Step 2: Create Virtual Environment (Recommended)

# On Windows
python -m venv venv
venv\Scripts\activate

# On macOS/Linux
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Configure Environment Variables

Create a .env file in the project root:

BOT_TOKEN=your_telegram_bot_token_here
CHANNEL_ID=your_target_channel_id_here
BOT_LANGUAGE=en

Step 5: Run the Bot

python main.py

---

⚙️ Configuration

Environment Variables

Variable	Required	Description	Example
BOT_TOKEN	✅ Yes	Telegram Bot API token from BotFather	123456789:ABCDefGHIjklmnoPQRstuvWXyz
CHANNEL_ID	✅ Yes	Telegram channel ID where messages are forwarded	-1001234567890
BOT_LANGUAGE	❌ No	Bot interface language (default: en)	en, uk, ru, pl, es, de, fr

Getting Credentials

1. BOT_TOKEN:

   • Chat with @BotFather on Telegram
   • Use /newbot command to create a new bot
   • Copy the token provided

2. CHANNEL_ID:

   • Create a channel in Telegram
   • Add the bot as an administrator
   • Send a test message and use telegram bot API to get the channel ID
   • Or find it in the channel info (usually starts with -100)

---

💬 Usage

For Users

1. Start the Bot: Send /start command to the bot
2. Send Anonymous Message: Simply type any message and send it
3. Confirmation: Receive a confirmation that your message was sent to the channel

For Administrators

1. Monitor Messages: View all anonymous messages in the configured channel
2. Manage Plugins: Place plugin folders in the plugins/ directory
3. Customize Language: Set BOT_LANGUAGE environment variable
4. View Logs: Check console output for operational details

---

📂 Project Structure

AnonkaReforged/
├── main.py                    # Bot entry point and core logic
├── plugin_system.py           # Plugin framework and manager
├── locales.json              # Multi-language translation strings
├── PLUGINS.md                # Plugin development documentation
├── README.md                 # This file
├── LICENSE                   # MIT License
├── .env                      # Environment variables (create manually)
├── .env.example              # Example environment file
├── requirements.txt          # Python dependencies
├── plugins/                  # Plugin directory
│   ├── __init__.py          # Makes plugins a Python package
│   ├── ban_plugin/          # Example: Ban management plugin
│   │   ├── plugin.py        # Plugin implementation
│   │   ├── config.json      # Plugin configuration
│   │   ├── README.md        # Plugin documentation
│   │   └── banned_users.json # Plugin data persistence
│   └── your_plugin/         # Template for new plugins
│       └── plugin.py
├── __pycache__/             # Python cache (auto-generated)
└── venv/                    # Virtual environment (recommended)

---

🏗️ Architecture Overview

Application Flow

┌───────────────────────────────────────────────────────┐
│                    Telegram Bot                       │
└───────────────────────────┬───────────────────────────┘
                            │
                ┌───────────┴───────────┐
                │                       │
        ┌───────▼──────────┐    ┌────────▼──────────┐
        │  /start Command  │    │  Regular Messages │
        └───────┬──────────┘    └───────┬───────────┘
                │                       │
        ┌───────▼──────────┐   ┌────────▼──────────────┐
        │  Send Welcome    │   │  Plugin Handlers      │
        │  Message         │   │  (if applicable)      │
        └──────────────────┘   └────────┬──────────────┘
                                        │
                                ┌───────▼──────────────┐
                                │  Forward to          │
                                │  Channel (Copy)      │
                                └───────┬──────────────┘
                                        │
                                ┌───────▼──────────────┐
                                │  Send Confirmation   │
                                │  to User             │
                                └──────────────────────┘

Data Flow with Plugins

1. Plugin Discovery: On startup, all plugins in plugins/ are discovered
2. Plugin Loading: Each plugin's plugin.py is loaded and instantiated
3. Plugin Setup: Each plugin's setup() method registers handlers
4. Message Processing: Incoming messages are processed by plugin handlers first, then core handlers
5. Plugin Cleanup: On shutdown, all plugins' cleanup() methods are called

---

🔧 Core Components

1. main.py - Bot Core

Responsibilities:

• Initializes the Telegram bot using aiogram
• Loads configuration from environment variables
• Manages localization system
• Registers message handlers
• Orchestrates plugin loading
• Handles message forwarding logic

Key Functions:

• load_locales(): Loads translation strings from locales.json
• t(key, **kwargs): Translation function with variable substitution
• cmd_start(): Handles /start command
• forward_to_channel(): Forwards user messages to the channel
• main(): Async entry point that starts the bot

Key Features:

# Configuration loading with validation
token = os.getenv("BOT_TOKEN")  # Required
channel_id = os.getenv("CHANNEL_ID")  # Required
language = os.getenv("BOT_LANGUAGE", "en")  # Optional, defaults to English

# Handler priority: Plugins first, then catch-all forward
# This prevents plugin commands from being forwarded as messages

---

2. plugin_system.py - Plugin Framework

Components:

Plugin (Abstract Base Class)

• Purpose: Base class for all plugins
• Required Implementation: setup() method
• Optional Implementation: cleanup() method
• Properties:
  • bot: Bot instance
  • dp: Dispatcher instance
  • plugin_dir: Path to plugin directory
  • name: Plugin class name
  • logger: Logger instance

class Plugin(ABC):
    async def setup(self) -> bool:
        """Initialize plugin - register handlers, load config, etc."""
        pass
    
    async def cleanup(self):
        """Clean up resources when plugin is unloaded."""
        pass

PluginManager (Plugin Orchestrator)

• Purpose: Discover, load, and manage all plugins
• Responsibilities:
  • Scan plugins/ directory for plugin folders
  • Load plugin modules dynamically using importlib
  • Instantiate plugin classes
  • Call setup/cleanup methods
  • Maintain plugin registry

Key Methods:

• discover_plugins(): Find all valid plugin directories
• load_plugin(plugin_dir): Load a single plugin
• load_all_plugins(): Load all discovered plugins (async)
• unload_all_plugins(): Cleanup all plugins (async)
• get_plugin(name): Retrieve loaded plugin by name
• list_plugins(): Get list of loaded plugin names

Plugin Loading Process:

# 1. Scan plugins/ directory for folders with plugin.py
# 2. Use importlib to load plugin.py module
# 3. Find class that inherits from Plugin
# 4. Instantiate the class
# 5. Call setup() method
# 6. If setup() returns True, add to registry

---

3. locales.json - Multi-language Support

Structure:

{
  "language_code": {
    "translation_key": "Translated text with {PLACEHOLDERS}"
  }
}

Supported Languages:

• en - English
• uk - Ukrainian
• ru - Russian
• pl - Polish
• es - Spanish
• de - German
• fr - French

Translation Keys:

• start_message: Welcome message on /start
• message_sent: Confirmation after message forwarding
• error_sending: Error message on forward failure
• bot_ignored: Message when bot tries to send

Variable Substitution: The t() function supports template variables:

t("start_message", CHANNEL_ID="@mychannel")
# Replaces {CHANNEL_ID} with @mychannel

---

🎮 Plugin System

Creating a Plugin

For detailed plugin development guide, see PLUGINS.md.

Quick Start:

# plugins/my_plugin/plugin.py
from aiogram import types
from aiogram.filters.command import Command
from plugin_system import Plugin


class MyPlugin(Plugin):
    async def setup(self) -> bool:
        """Setup handlers and initialize plugin."""
        try:
            self.dp.message.register(self.cmd_ping, Command("ping"))
            self.logger.info("MyPlugin initialized")
            return True
        except Exception as e:
            self.logger.error(f"Setup failed: {e}")
            return False
    
    async def cmd_ping(self, message: types.Message):
        """Example command handler."""
        await message.answer("Pong! 🏓")
    
    async def cleanup(self):
        """Called when plugin is unloaded."""
        self.logger.info("MyPlugin cleanup")

Plugin Features

• Dynamic Loading: Plugins loaded at runtime without bot restart (requires code restart currently)
• Isolated Logging: Each plugin has its own logger with plugin.PluginName prefix
• Configuration Files: Access plugin config via get_config_path()
• Data Persistence: Store data in self.plugin_dir
• Full Bot Access: Access to bot instance and dispatcher for handler registration
• Error Isolation: Plugin errors don't crash the main bot

---

🌍 Localization

How It Works

1. Language Selection: Set via LANGUAGE environment variable
2. Key-Based Translation: Use t("key") function to get translated strings
3. Fallback System: Missing translations fall back to English
4. Variable Substitution: Template variables like {CHANNEL_ID} are replaced

Adding New Language

Edit locales.json:

{
  "pt": {
    "start_message": "👋 <b>Bem-vindo!</b>\n\nEnvie-me qualquer mensagem...",
    "message_sent": "Sua mensagem foi enviada! 🚀",
    "error_sending": "Desculpe, não consegui enviar sua mensagem.",
    "bot_ignored": "Mensagens de bots não são aceitas."
  }
}

Then set LANGUAGE=pt in .env.

---

🔐 Environment Variables

Setup Instructions

Create .env file in project root:

# .env
BOT_TOKEN=123456789:ABCDefGHIjklmnoPQRstuvWXyz
CHANNEL_ID=-1001234567890
LANGUAGE=en

Validation

The bot validates required variables on startup:

# Raises RuntimeError if missing
token = os.getenv("BOT_TOKEN")
channel_id = os.getenv("CHANNEL_ID")

---

⚠️ Error Handling

Logging Levels

# In main.py
logging.basicConfig(level=logging.INFO)  # Production
logging.basicConfig(level=logging.DEBUG)  # Development

Error Scenarios

Scenario	Handling
Missing BOT_TOKEN	Raises RuntimeError at startup
Missing CHANNEL_ID	Raises RuntimeError at startup
Missing locales.json	Uses fallback English messages
Invalid JSON in locales.json	Raises JSONDecodeError
Forward to channel fails	User receives error message, exception logged
Plugin setup fails	Plugin not added to registry, error logged
Plugin cleanup fails	Error logged, but other plugins still cleaned up

Best Practices

• Check logs regularly for warnings and errors
• Use try-except blocks in plugin setup() methods
• Return False from setup() if initialization fails
• Implement cleanup() for proper resource management
• Test plugins before deploying to production

---

🎯 Best Practices

For Bot Operators

1. Security:

   • Never commit .env file to version control
   • Use strong, unique bot tokens
   • Restrict channel access to trusted administrators

2. Maintenance:

   • Regularly check bot logs
   • Monitor message forwarding success rate
   • Back up plugin configuration files

3. Performance:

   • Use appropriate logging levels
   • Test plugins in development before production
   • Monitor bot response times

For Plugin Developers

1. Code Quality:

   • Inherit from Plugin base class
   • Implement proper error handling in setup()
   • Use self.logger for all logging

2. Resource Management:

   • Close file handles in cleanup()
   • Stop background tasks properly
   • Release database connections

3. Documentation:

   • Add docstrings to all methods
   • Create README.md in plugin folder
   • Document configuration options in config.json

4. Compatibility:

   • Target Python 3.9+
   • Use aiogram v3.x
   • Test with different bot configurations

---

🤝 Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

Plugin Contributions

To contribute a plugin:

1. Create plugin following guidelines in PLUGINS.md
2. Include comprehensive documentation
3. Add test cases if applicable
4. Submit PR with [PLUGIN] prefix

---

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

MIT License Summary:

• ✅ Commercial use allowed
• ✅ Modification allowed
• ✅ Distribution allowed
• ✅ Private use allowed
• ⚠️ Liability limited
• ⚠️ Warranty not provided

---

📞 Support & Contact

• Issues: Report bugs via GitHub Issues
• Documentation: See PLUGINS.md for plugin development
• Author: @cmpdchtr

---

🗺️ Roadmap

Future enhancements planned:

• Hot plugin reload without bot restart
• Web dashboard for configuration
• Plugin marketplace
• Message scheduling
• Advanced statistics and analytics
• Rate limiting and abuse prevention
• Database integration for persistence
• Plugin dependency management

---

⚡ Quick Commands

# Setup
git clone https://github.com/cmpdchtr/AnonkaReforged.git
cd AnonkaReforged
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

# Configure
cp .env.example .env
# Edit .env with your BOT_TOKEN and CHANNEL_ID

# Run
python main.py

# Create Plugin
mkdir plugins/my_plugin
# Create plugins/my_plugin/plugin.py following PLUGINS.md

# View Logs
# Check console output or configure logging to file

---

📊 Statistics

• Lines of Code: ~500 (core bot logic)
• Supported Languages: 7
• Plugin System: Dynamic loading with error isolation
• Architecture: Fully asynchronous using aiogram 3.x
• Python Version: 3.9+

---

Last Updated: 1.11.2025
Version: V0.4 Status: Active Development

Made with ❤️ by @cmpdchtr