Recepta - Telegram Receipt Expense Tracker

A comprehensive Telegram bot for tracking expenses through receipt image processing with OCR, manual entry, budget management, and subscription features. Built specifically for Philippine users with support for PHP currency and local payment methods (GCash, Maya, Bank Transfers).

Features

🧾 Receipt Processing

• OCR Image Processing: Upload receipt photos for automatic text extraction and parsing
• Manual Entry: Template-based manual receipt entry with guided prompts
• Smart Parsing: Automatic detection of merchant names, amounts, dates, and line items
• Category Management: Organize expenses into customizable categories

💰 Budget Management

• Multiple Budget Types: Set daily, weekly, and monthly budgets
• Category-Specific Budgets: Create budgets for specific expense categories
• Real-time Tracking: Monitor spending against budgets with live updates
• Smart Alerts: Automated notifications when approaching or exceeding budgets

📊 Reports & Analytics

• Expense Summaries: Daily, weekly, and monthly expense breakdowns
• Category Analysis: See spending patterns by category with percentages
• Budget Comparison: Visual comparison of spending vs. budgets
• Export Features: CSV/PDF exports for Pro users

💳 Subscription System

• Free Plan: 10 receipts per month with basic features
• Pro Plan: Unlimited receipts with advanced features
• Local Payment Methods: GCash, Maya, and bank transfers
• Flexible Pricing: Monthly (₱249) and yearly (₱2,490) options

🔔 Smart Notifications

• Daily Summaries: Automated daily expense summaries
• Budget Alerts: Real-time budget warnings and notifications
• Weekly/Monthly Reports: Comprehensive periodic reports for Pro users
• Subscription Reminders: Automated renewal notifications

Tech Stack

• Backend: Python 3.9+, FastAPI, SQLAlchemy
• Database: PostgreSQL
• Telegram Bot: python-telegram-bot
• OCR: Tesseract OCR with OpenCV preprocessing
• Task Scheduling: APScheduler for notifications
• Payment Processing: GCash, Maya APIs, manual bank verification
• Caching: Redis for session management

Installation

Prerequisites

1. Python 3.9+
2. PostgreSQL database
3. Redis server
4. Tesseract OCR installed on system
5. Telegram Bot Token from @BotFather

System Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install tesseract-ocr tesseract-ocr-eng
sudo apt install postgresql postgresql-contrib
sudo apt install redis-server
sudo apt install python3-pip python3-venv

macOS:

brew install tesseract
brew install postgresql
brew install redis

Windows:

1. Download and install Tesseract from: https://github.com/UB-Mannheim/tesseract/wiki
2. Install PostgreSQL from: https://www.postgresql.org/download/windows/
3. Install Redis from: https://redis.io/docs/getting-started/installation/install-redis-on-windows/

Project Setup

1. Clone the repository:

git clone <repository-url>
cd recepta

2. Create virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

cp .env.example .env
# Edit .env with your configuration

5. Configure environment variables in .env:

# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
WEBHOOK_URL=https://your-domain.com/webhook

# Database Configuration
DATABASE_URL=postgresql://username:password@localhost:5432/recepta_db

# Redis Configuration
REDIS_URL=redis://localhost:6379/0

# Payment Configuration
GCASH_MERCHANT_ID=your_gcash_merchant_id
GCASH_API_KEY=your_gcash_api_key
MAYA_PUBLIC_KEY=your_maya_public_key
MAYA_SECRET_KEY=your_maya_secret_key

# OCR Configuration
TESSERACT_PATH=/usr/bin/tesseract  # Adjust for your system

# Subscription Plans (in PHP)
FREE_DAILY_RECEIPT_LIMIT=3
PRO_DAILY_RECEIPT_LIMIT=50
PRO_MONTHLY_PRICE=79
PRO_YEARLY_PRICE=249

6. Set up database:

# Create PostgreSQL database
createdb recepta_db

# The application will automatically create tables on first run

7. Run the application:

python main.py

This will start:

• Telegram bot (main thread)
• FastAPI web server on port 8000
• Notification scheduler service

Usage

Bot Commands

Basic Commands

• /start - Start the bot and show main menu
• /help - Display help information and command list
• /manual - Start manual receipt entry process
• /cancel - Cancel current operation

Budget Management

• /setbudget - Set daily, weekly, or monthly budgets
• /budgets - View current budgets
• /summary - View expense summaries

Account Management

• /subscribe - Upgrade to Pro subscription
• /account - View account information

Receipt Processing

Image Upload

1. Take a clear photo of your receipt
2. Send the photo to the bot
3. Bot processes with OCR and extracts information
4. Select appropriate category
5. Receipt is saved automatically

Manual Entry

1. Use /manual command
2. Enter merchant name
3. Enter total amount (in PHP)
4. Enter date (YYYY-MM-DD or 'today')
5. Select category from menu
6. Receipt is saved

Budget Management

Setting Budgets

1. Click "💰 Set Budget" or use /setbudget
2. Choose budget type (daily/weekly/monthly)
3. Enter amount in PHP
4. Optionally select specific category
5. Budget is activated immediately

Monitoring Budgets

• Real-time alerts when approaching limits
• Daily summaries show budget progress
• Visual indicators in expense reports

Payment & Subscriptions

Upgrading to Pro

1. Click "💳 Subscription" button
2. Select "Upgrade to Pro"
3. Choose payment method:
   • GCash: Instant payment via GCash app
   • Maya: Instant payment via Maya app
   • Bank Transfer: Manual verification required
4. Complete payment process
5. Pro features activated immediately

Pro Features

• ✨ Unlimited receipt processing
• 📊 Advanced reports and analytics
• 📈 Export to CSV/PDF
• 🔔 Enhanced notifications
• 📱 Web dashboard access (coming soon)

API Endpoints

The bot includes a REST API for webhooks and integrations:

Payment Webhooks

• POST /webhook/gcash - GCash payment notifications
• POST /webhook/maya - Maya payment notifications

Payment Pages

• GET /payment/success - Successful payment redirect
• GET /payment/failure - Failed payment redirect
• GET /payment/cancel - Cancelled payment redirect

Admin Endpoints

• GET /admin/transactions - List all transactions

Development

Project Structure

recepta/
├── api/                    # FastAPI web server
│   ├── __init__.py
│   └── main.py
├── bot/                    # Telegram bot handlers
│   ├── __init__.py
│   ├── handlers.py
│   └── main.py
├── database/               # Database models and connection
│   ├── __init__.py
│   ├── database.py
│   └── models.py
├── services/               # Business logic services
│   ├── __init__.py
│   ├── budget_service.py
│   ├── notification_service.py
│   ├── ocr_service.py
│   └── payment_service.py
├── uploads/                # Uploaded receipt images
├── config.py              # Configuration management
├── main.py                # Application entry point
├── requirements.txt       # Python dependencies
└── README.md              # This file

Running Tests

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

Code Style

# Install formatting tools
pip install black flake8

# Format code
black .

# Check style
flake8 .

Deployment

Production Setup

1. Environment Setup:

   • Use production PostgreSQL database
   • Configure Redis for caching
   • Set up SSL certificates
   • Use environment-specific configurations

2. Web Server:

   • Deploy FastAPI with Gunicorn/Uvicorn
   • Configure reverse proxy (Nginx)
   • Set up domain and SSL

3. Bot Deployment:

   • Use webhook mode for production
   • Configure webhook URL in Telegram
   • Set up monitoring and logging

4. Payment Integration:

   • Configure production payment credentials
   • Set up webhook endpoints for payment providers
   • Test payment flows thoroughly

Docker Deployment

# Build Docker image
docker build -t recepta .

# Run with Docker Compose
docker-compose up -d

Support & Contributing

Getting Help

• 📧 Email: [email protected]
• 💬 Telegram: @recepta_support
• 📚 Documentation: [Link to docs]

Contributing

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

License

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

Roadmap

Upcoming Features

• 📱 Web dashboard for expense management
• 🤖 AI-powered expense categorization
• 👥 Family/team expense sharing
• 📈 Advanced analytics and insights
• 🔗 Integration with accounting software
• 🌍 Multi-language support

Version History

• v1.0.0 - Initial release with core features
• v1.1.0 - Enhanced OCR and payment integration
• v1.2.0 - Advanced reporting and notifications

---

Recepta - Making expense tracking simple and automatic for Filipino users! 🇵🇭