1. Main Application (main.py): Handles async initialization, dependency injection, and lifecycle management.
2. Command Modules (commands/): Each service has its own module, registered via a factory pattern with permission control.
3. Utility Modules (utils/):

• config_manager.py: Configuration management.
• cache_manager.py, redis_cache_manager.py: Cache management.
• mysql_user_manager.py: Database operations for users and permissions.
• task_scheduler.py, redis_task_scheduler.py: Task scheduling.
• permissions.py: Permission system.

4. Data Storage:

• Redis: Caching and message deletion scheduling.
• MySQL: User data and permission management.

• Command Factory: For unified command registration and permission handling.
• Dependency Injection: Core components are passed via bot_data.
• Asynchronous Programming: Fully supports async/await for all I/O operations.
• Decorator-based Error Handling: Unified error handling for commands.
• Direct Async Permission Checks: The complex adapter layer has been removed, and MySQL operations are now directly asynchronous.

• users: Basic user information
• admin_permissions: Administrators
• super_admins: Super administrators
• user_whitelist: Whitelisted users
• group_whitelist: Whitelisted groups
• admin_logs: Administrator action logs
• command_stats: Command usage statistics

The schema is defined in database/init.sql and is created automatically by the application on first run.

The project has been fully migrated away from SQLite compatibility adapters to a unified MySQL + Redis architecture:

• Direct Asynchronous Permission Checks: utils/permissions.py directly fetches the MySQL manager from context.bot_data['user_cache_manager'].
• Unified Data Storage: All permission data is stored in MySQL, preventing inconsistencies.
• Performance Improvements: The removal of synchronous-to-asynchronous complexities has increased response speed.

1. Public Access: All users and groups (whitelisted or not) can access streaming service pricing (/nf, /ds, /sp) and user information commands (/when, /id). Simply add the bot to any group to enable these features.
2. Whitelist Access: Required for advanced features like crypto prices, currency conversion, weather forecasts, Steam prices, BIN lookup, movie/TV information, and app store queries. Contact for whitelist access or future service plans.
3. Admin: Stored in the MySQL admin_permissions table.
4. Super Admin: Configured via the SUPER_ADMIN_ID environment variable.

Place Python scripts in the custom_scripts/ directory and set LOAD_CUSTOM_SCRIPTS=true to load them automatically. Scripts get access to:

• application: The Telegram Application instance.
• cache_manager: The Redis cache manager.
• rate_converter: The currency converter.
• user_cache_manager: The user cache manager.
• stats_manager: The statistics manager.

1. Create a new module in the commands/ directory.
2. Use command_factory.register_command() to register the new command.
3. Set the appropriate permission level.
4. Inject any necessary dependencies in main.py.

• Log File: logs/bot-YYYY-MM-DD.log
• Log Rotation: 10MB size limit with 5 backups.
• Log Levels: Supports DEBUG, INFO, WARNING, ERROR.
• Periodic Cleanup: Via cleanup_logs.py or a scheduled task.

• Command usage statistics
• User activity monitoring
• Error logging
• Performance metric collection

• Redis Cache: Used for high-frequency data like price information and weather location lookups.
• Unified Cache Management: Managed via redis_cache_manager.py.
• Smart Caching: Different services have configurable cache durations.
• Mathematical Expression Caching: Safe evaluation and caching of mathematical expressions in currency conversions.

• Redis Task Scheduler: Supports scheduled, recurring tasks.
• Message Deletion: Automatically cleans up temporary messages.
• Cache Cleanup: Periodically purges expired cache.

• Connection Pooling: Used for both MySQL and Redis.
• Asynchronous Client: Uses httpx for async HTTP requests.
• Graceful Shutdown: Cleans up resources and closes connections gracefully.

1. Error Handling: Use the @with_error_handling decorator.
2. Logging: Use appropriate log levels.
3. Permission Checks: Use the @require_permission(...) decorator.
4. Async Permissions: Fetch the user manager via context.bot_data['user_cache_manager'].
5. Caching: Use Redis caching to avoid duplicate requests.
6. Async Code: Use async/await for all I/O-bound operations.
7. Configuration: Manage all settings via environment variables.
8. Database Queries: Use parameterized queries to prevent SQL injection.

1. Database Connection Failure: Check MySQL configuration and connection.
2. Redis Connection Failure: Check Redis service status.
3. Permission Errors: Ensure the user is in the whitelist or admin list.
4. Commands Not Responding: Check the log file for errors.
5. Weather Command Fails: Ensure the QWEATHER_API_KEY is set correctly in your .env file and that it's a valid key.
6. BIN Lookup Fails: Ensure the BIN_API_KEY is set correctly in your .env file and that you have sufficient API quota.

1. Set LOG_LEVEL=DEBUG for detailed logs.
2. Use docker-compose logs -f appbot to view real-time logs.
3. Check Redis cache status.
4. Verify database table structure and data.

Removed Components:

• utils/compatibility_adapters.py - SQLite compatibility adapter
• utils/redis_mysql_adapters.py - Hybrid adapter
• utils/unified_database.py - Unified SQLite database
• Other SQLite-related files

Architectural Optimizations:

• Unified the architecture on MySQL + Redis.
• Implemented direct asynchronous permission checks, removing the complex adapter layer.
• Improved performance and code maintainability.
• Resolved an issue where whitelisted group users could not use the bot.

Migration Essentials:

• All permission data is now stored in MySQL.
• Redis is used for caching and message deletion scheduling.
• MySQL and Redis connection details must be configured in the .env file.

• CoinGecko Integration: Migrated ranking features to CoinGecko's free API, removing API key requirements for ranking functionality
• Interactive Menu System: New unified interface similar to finance module with button navigation and real-time data
• Multiple Ranking Categories: Hot trending coins, 24h gainers/losers, market cap rankings, and trading volume charts
• Smart Dual API Strategy: CoinGecko for rankings (free), CoinMarketCap for individual price queries (premium)
• Enhanced Data Display: Comprehensive coin information with prices, changes, market cap ranks, and real-time timestamps
• Caching Integration: Intelligent caching system with separate TTL for different data types and unified cache management
• User Experience: Clean markdown formatting, refresh functionality, and auto-deletion for chat cleanliness
• No Setup Required: Ranking features work out-of-the-box without API configuration
• New /finance Command: Comprehensive financial market data powered by Yahoo Finance API with real-time stock prices
• 15 Ranking Categories: Complete stock and fund rankings including day gainers/losers, most actives, growth tech stocks, undervalued stocks, and 6 mutual fund categories
• Multi-Market Support: US, Hong Kong (HK), China (CN), Malaysia (MY) stocks with flexible ticker format support
• Intelligent Stock Search: Support for ticker symbols (AAPL, 6033.KL) and company names (Apple, Tesla, Maybank) with multilingual matching
• Advanced Financial Data: Analyst recommendations with buy/sell/hold ratings, financial statements (income, balance sheet, cash flow)
• Categorized Interface: Separate stock rankings (9 types) and fund rankings (6 types) with interactive button navigation
• Smart Caching System: Intelligent Redis caching with different TTL for stock info (5min), rankings (3min), and search results (10min)
• Auto-deletion Management: All user commands and bot messages automatically deleted to maintain clean chat interface
• Real-time Market Data: Current prices, daily changes, volume, market cap, P/E ratio, and exchange information
• Technical Integration: yfinance library integration with pandas DataFrame processing and comprehensive error handling

• New /meme Command: Fetch random memes from memes.bupt.site API with support for 1-20 memes per request
• Parameter Validation: Smart input validation with clear error messages and usage guidance
• Auto-deletion System: Meme images automatically delete after 15 minutes to keep chats clean
• Intelligent Caching: Redis-powered caching system for improved performance with configurable TTL
• Fallback Support: Link-based fallback display when direct image sending fails
• Unified Cache Management: Integrated with /cleancache system for easy cache administration
• Error Handling: Comprehensive error handling with loading indicators and user feedback
• Pydantic Validation: Type-safe API response parsing using Pydantic models
• Weekly Cleanup: Configurable weekly cache cleanup via memes_weekly_cleanup setting

• Single Command Interface: Replaced 20+ individual *_cleancache commands with unified /cleancache system
• Interactive Menu: Button-based service selection with clear categorization and status feedback
• Command-line Support: Direct cache clearing via /cleancache [service] for power users
• Special Handling: Complex cache structures (weather with 7 prefixes) handled automatically
• Comprehensive Coverage: All services included - memes, news, crypto, movie, steam, weather, cooking, whois, app stores, streaming services, rate, and BIN
• Admin Permission: Secure admin-only access with proper error handling and logging
• Real-time Feedback: Immediate status updates during cache clearing operations
• Service Mapping: Clear service name mappings for better user experience

• Smart Command List Management: New /refresh_all admin command refreshes command lists for all users and groups
• User Self-Service: /refresh command allows any user to fix command visibility issues independently
• Telegram Cache Solution: Resolves Telegram client-side command caching when new features are added
• Global + Personal Updates: Updates both global default commands and individual user/group command lists
• Help Integration: Automatic guidance in help and start commands for troubleshooting command visibility
• New Feature Rollout: Streamlines deployment of new Permission.NONE features to all users
• Reduces Admin Burden: Users can resolve command display issues without contacting administrators

• Dual Information System: WHOIS registration data + actual server geolocation for IP addresses
• IP-API.com Integration: Real-time IP geolocation service providing accurate server location data
• Comprehensive Location Details: Country with flags, region, city, postal code, coordinates, and timezone
• ISP & Network Information: Actual ISP, organization, and AS number from geolocation service
• Smart Field Categorization: Separate display sections for registration info vs. actual location
• Enhanced Country Display: Country flags and Chinese names using existing country_data integration
• Intelligent Cloud Detection: Automatic detection of cloud providers (Microsoft, Amazon, Google) with explanatory notes
• Error Handling & Fallback: Graceful degradation when geolocation service is unavailable
• Rate Limit Compliance: Respects IP-API.com's 45 requests/minute free tier limitations
• Cache Integration: Redis caching for both WHOIS and geolocation data with configurable TTL
• User-Friendly Explanations: Clear distinction between "📍 注册位置" and "🌍 实际位置" for better understanding

• Public Time Queries: Available to all users - query current time in any timezone using country names, codes, cities, or IANA timezone identifiers
• Timezone Conversion: Convert time between different timezones with intelligent parsing of various timezone formats
• Comprehensive Timezone Support: Supports 200+ cities, 190+ countries with full IANA timezone database integration
• Country Data Integration: Leverages existing country_data.py for consistent flag display and localized country names
• Smart Input Recognition: Accepts Chinese/English country names, ISO country codes, major city names, and standard IANA timezone identifiers
• Interactive Help System: Context-aware help with complete IANA timezone documentation links
• Caching System: Redis-powered caching for timezone differences and location lookups for optimal performance
• Markdown V2 Formatting: Full compliance with Telegram's formatting requirements with proper character escaping

• JSON Storage Architecture: Replaced hardcoded data points with flexible JSON file storage system
• Real-time Statistics Display: Shows statistics for total, verified, and estimated data points
• Dynamic Management Features: Support for adding, removing, and viewing data points via Telegram commands
• Docker Volume Persistence: Ensures data integrity across container restarts
• Backward Compatibility: Fully compatible with existing estimation algorithms, no migration required

• Universal Public Access: All users and groups can use streaming service pricing and user information commands without any restrictions
• Group Integration: Add the bot to any Telegram group to enable public features for all members
• Enhanced Help System: Different help content displayed based on user permission level
• Improved User Experience: Clear distinction between free and premium features
• Admin Management Tools: Comprehensive user/group whitelist management via /add, /addgroup, and interactive /admin panel
• Whitelist Policy Update: Applications currently closed, future paid service plans under consideration

• Unified Button Interface System: Complete redesign with interactive buttons for intuitive navigation
• 3-Platform Data Integration: Combines TMDB, JustWatch, and Trakt APIs for comprehensive movie/TV information
• JustWatch Streaming Charts: Real-time streaming platform rankings integrated into unified /chart system
• Interactive Content Access: One-click access to recommendations, reviews, videos, platforms via button interface
• Smart Session Management: Multi-step interactions for season/episode selection with user input
• Enhanced Search: Intelligent movie/TV/person search with comprehensive result display
• Rich Details: Posters, ratings, cast, crew, trailers, and viewing platforms with full integration
• Community Statistics: Trakt integration provides watch counts, collector stats, and community engagement data
• Telegraph Integration: Seamless long content display for reviews, cast lists, and detailed information
• Unified Chart System: All trending, popular, and upcoming content consolidated in /chart command
• Simplified Commands: Just 4 main commands (/movie, /tv, /person, /chart) replace 25+ old commands
• Season/Episode Navigation: Interactive season and episode browsing with contextual information
• Platform Availability: Shows streaming platforms with intelligent geographic relevance
• Source Transparency: Clear indicators showing data sources (📊 TMDB, 📺 JustWatch, 🎯 Trakt) in all displays
• Multilingual Support: Chinese/English content fallback for better coverage
• Real-time Updates: JustWatch data includes timestamps and data freshness indicators

• New user caching infrastructure with MySQL storage and Redis performance optimization
• Flexible group monitoring via ENABLE_USER_CACHE and USER_CACHE_GROUP_IDS settings - leave empty to monitor all groups
• Admin cache debugging with /cache command for viewing cache statistics, user table size, and user lookup
• Flexible cache cleanup with /cleanid command supporting time-based and complete cleanup
• Automatic user data collection from all monitored group messages for username-to-ID mapping
• Enhanced username support in /when command leveraging cached user data

• Multi-format Game Search: /steam for individual games with multi-region pricing
• Bundle Price Lookup: /steamb for Steam bundle pricing and content information
• Comprehensive Search: /steams for combined games and bundles search results
• Region Comparison: Multi-country price comparison for better deals
• Smart Caching: Intelligent caching system for improved performance
• Unified Cache Management: Integrated with /cleancache steam command for cache control

• New /bin command for credit card BIN information lookup
• Comprehensive data display including card brand, type, issuing bank, and country
• Smart caching system for improved performance
• Unified cache management via /cleancache bin command
• Chinese localization support for card brands and countries
• Environment variable configuration via BIN_API_KEY