This project is a Telegram bot that analyzes PINFL (Personal Identification Number for Individual Taxpayer) entered by users and provides detailed analysis including validity, structure breakdown, birth date, region code, and specific error descriptions.
PINFL is a unique identification number used in several countries to identify citizens. This project processes and analyzes PINFL to ensure correctness and provide information about birth date and other data contained in this number.
- Detailed PINFL Analysis: Comprehensive validation with structure breakdown and specific error identification
- Educational Information: Built-in help system explaining PINFL structure and validation process
- PINFL Generation: Generate random valid PINFL numbers for testing purposes
- Multi-language Support: Full internationalization in Uzbek (O'zbekcha), Russian (Русский), and English
- Database Integration: SQLite database for user management and request statistics
- Public Statistics: Monthly statistics available to all users for transparency and trust
- User Management: Automatic user registration and activity tracking
- Official Disclaimer: Clear warnings about unofficial status and limitations
/start- Start working with the bot and view command overview/help- Detailed information about PINFL structure and bot functionality/generate- Generate random valid PINFL for testing/language- Choose interface language (Uzbek/Russian/English)/stats- View monthly usage statistics (public for transparency)/issues- Report bugs or suggest improvements
You can also send any 14-digit number directly to the bot for detailed PINFL analysis.
When you send a PINFL to the bot, it provides:
- Visual Structure: PINFL formatted with clear separators (e.g.,
3 25 05 90 012 345 9) - Component Analysis: Each part explained (century/gender, birth date, region code, serial number, check digit)
- Validation Results: Clear indication of validity with specific error descriptions
- Birth Date Extraction: Automatic date parsing and validation
- Error Identification: Precise description of what's wrong with invalid PINFLs
The /help command provides comprehensive information about:
- What is PINFL and its purpose
- Detailed structure explanation (14-digit format breakdown)
- How the bot validates each component
- Limitations and unofficial status disclaimer
Valid PINFL:
📋 PINFL structure:
3 25 05 90 012 345 9
🔢 Century/Gender: 3 (male, 19 century)
📅 Day: 25
📅 Month: 05
📅 Year: 90 (1990 year)
🗺️ Area code: 012
🔢 Serial number: 345
✅ Check digit: 9
✅ PINFL is valid
📅 1990-05-25
Invalid PINFL:
❌ PINFL is invalid
🔍 Found errors:
❌ Check digit error: 6 (expected: 9)
- Uzbek (O'zbekcha) - uz
- Russian (Русский) - ru
- English - en
-
Navigate to the project directory.
-
Create a
.envfile with the required environment variables:
TELEGRAM_BOT_TOKEN=your_bot_token_here
ISSUE_LINK=https://github.com/your-repo/issues- Run with Docker Compose:
docker-compose up -dTELEGRAM_BOT_TOKEN- Your Telegram Bot API token (required)ISSUE_LINK- Link to your project's issue tracker (optional)
The bot uses SQLite database to store:
- User information (ID, username, language preference, registration date)
- Request statistics (generate/analyze requests with timestamps)
- Activity tracking
Database file is stored in data/pinfl_bot.db and is persisted through Docker volumes.
All users can access monthly statistics using the /stats command, which shows:
- Number of generate requests in current month
- Number of analyze requests in current month
- Number of new users registered in current month
- Total number of users
Statistics are public to provide transparency about bot usage and popularity.
-
The bot pre-validates entered text for digits only and minimum 14 character length.
-
Multi-language Interface: Users can switch between Uzbek, Russian, and English using the
/languagecommand. -
Database Persistence: All user data and statistics are stored in SQLite database with proper volume mounting.
-
Public Analytics: Statistics and usage data available for all users to understand bot popularity.
pinfl-helper-tbot/
├── main.py # Main bot logic
├── database.py # Database operations
├── translations.py # Multi-language support
├── pinfl_utilities_generator.py # PINFL generation utilities
├── pinfl_utilities_parser.py # PINFL parsing utilities
├── docker-compose.yml # Docker configuration
├── Dockerfile # Docker build file
├── data/ # Database storage directory
├── documentation/ # Project documentation
│ ├── SETUP.md # Local setup guide
│ └── USAGE_GUIDE.md # User manual
├── CLAUDE.md # AI project overview
└── README.md # This file
See documentation/SETUP.md for detailed setup instructions.
To add a new language:
- Add language code and name to
LANGUAGESdict intranslations.py - Add translations for all keys in
TRANSLATIONSdict - Test with
/languagecommand
To add new statistics:
- Add new fields to database schema in
database.py - Update
get_monthly_stats()method - Add translations for new statistics in
translations.py - Update
stats()function inmain.py
This is a personal pet project created in 2025 for:
- Company workflow optimization - Simplifying PINFL validation processes
- Portfolio demonstration - Showcasing technical skills to potential employers
- Best practices showcase - Modern development, testing, and deployment practices
This project demonstrates:
- Clean architecture with decorator patterns
- Comprehensive testing and CI/CD
- Multi-language support and internationalization
- Docker containerization and local development
- Database design and statistics tracking
This project is licensed under the MIT License - see the LICENSE file for details.
Personal Project Notice: This software is actively used in production and maintained as part of a professional portfolio.