Commit 82b5926

@@ -0,0 +1,130 @@
+```
+# 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:
+
+```bash
+# Install dependencies
+uv sync
+
+# Activate virtual environment
+uv venv
+source .venv/bin/activate  # macOS/Linux
+```
+
+Alternatively, use Conda:
+
+```bash
+conda env create -f environment.yml
+conda activate bennybot
+```
+
+### Running the Bot
+
+```bash
+# 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:
+
+```bash
+# 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
+
+| Category                 | Tools/Libraries                                                    |
+| ------------------------ | ------------------------------------------------------------------ |
+| **Core Framework**       | Pyrogram (Telegram MTProto API), asyncio, uvloop                   |
+| **AI/ML**                | Anthropic, OpenAI, Google Gemini, DashScope, ONNX Runtime          |
+| **Media Processing**     | ffmpeg, Pillow, soundfile, yt-dlp                                  |
+| **Web/APIs**             | httpx, beautifulsoup4, bilibili-api-python, youtube-transcript-api |
+| **Databases**            | aioboto3 (Cloudflare R2), Turso, Cloudflare KV/D1                  |
+| **Utilities**            | loguru, cacheout, glom, orjson, pyaml                              |
+| **Internationalization** | zhconv, cutword                                                    |
+| **Development**          | uv, Ruff, pre-commit, pytest                                       |
+
+## Docker Deployment
+
+The project includes Docker configuration for deployment:
+
+```bash
+# 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.