# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

About This Project

Bennybot is a feature-rich Telegram bot built with Python 3.13 and Pyrogram. It provides a wide range of services through Telegram messages, including media downloading/conversion, AI chat/image generation, social media link previews, OCR, voice transcription, and price tracking.

Architecture Overview

The codebase follows a modular, async architecture with clear separation of concerns:

src/
├── main.py                 # Bot entry point and Telegram client setup
├── config.py               # Central configuration with environment variables
├── messages/               # Message parsing, command routing, and processing
├── database/               # Multi-backend database/storage integration (Cloudflare KV/R2/D1, Turso, memory)
├── ai/                     # AI service integrations (Anthropic, OpenAI, Google Gemini)
├── preview/                # Social media link previews for 20+ platforms (YouTube, Twitter, GitHub, etc.)
├── services/               # Modular feature components (media, OCR, transcription, etc.)
└── utils/                  # Shared utility functions

Key architectural features:

• Async-first design using asyncio and uvloop for high performance
• Modular feature system - each feature is a separate module with its own logic
• Multiple storage backends - abstracted storage layer supporting Cloudflare services, Turso, and in-memory storage
• Extensible AI integration - supports multiple AI APIs with a unified interface
• Comprehensive message handling - parses and routes commands, text messages, and media

Development Setup

Dependencies

The project uses uv (Unified Venv) for dependency management:

# Install dependencies
uv sync

# Activate virtual environment
uv venv
source .venv/bin/activate  # macOS/Linux

Alternatively, use Conda:

conda env create -f environment.yml
conda activate bennybot

Running the Bot

# Run the bot (requires valid Telegram API credentials)
python src/main.py

# Generate Telegram session string
python scripts/auth.py --appid <APP_ID> --apphash <APP_HASH>

Configuration

All configuration is via environment variables. Key variables:

• TELEGRAM_API_ID and TELEGRAM_API_HASH - Telegram API credentials
• TELEGRAM_BOT_TOKEN - Bot token from @BotFather
• Various API keys for AI services (Anthropic, OpenAI, Google Gemini, etc.)
• Storage backend configuration (Cloudflare credentials, Turso URL, etc.)

Linting and Formatting

The project uses Ruff for linting and formatting:

# Run Ruff linter
uv run ruff check src/

# Auto-fix fixable issues
uv run ruff check src/ --fix

# Run Ruff formatter
uv run ruff format src/

# Run all pre-commit hooks
pre-commit run --all-files

Key Technologies and Libraries

Docker Deployment

The project includes Docker configuration for deployment:

# Build Docker image
cd docker
docker build -t bennybot .

# Run Docker container
docker run -d --name bennybot \
  --env-file .env \
  bennybot

Project Structure Details

• Messages Module: Handles all message types (text, commands, media) and routes to appropriate handlers
• Database Module: Abstracts storage operations with support for multiple backends
• AI Module: Provides unified interface to various AI services for chat and image generation
• Preview Module: Handles link previews by scraping and parsing content from 20+ platforms
• Services: Contains specialized feature implementations (media processing, OCR, transcription, check-in services, etc.)

This architecture allows for easy extension - new features can be added as separate modules without modifying core bot logic.