expense-tracker-bot

module

v1.0.0 Latest Latest Go to latest Published: Jun 26, 2025 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/MitulShah1/expense-tracker-bot

Links

Open Source Insights

README ¶

🚗 Expense Tracker Bot

A robust, enterprise-grade Telegram bot for tracking personal expenses with PostgreSQL backend, built with Go. Features comprehensive expense management, category organization, vehicle expense tracking, and detailed analytics.

🚀 Quick Start • 🌟 Features • 🏗️ Architecture • 🧪 Testing • 🔧 Development • 🚀 Deployment

🌟 Features

💰 Core Functionality

📝 Expense Tracking: Add, edit, delete, and list expenses with ease
📂 Category Management: Organized expense categories with emojis
🚗 Vehicle Expenses: Special handling for fuel, service, and maintenance costs
📊 Reports & Analytics: Generate comprehensive expense reports and statistics
📈 Dashboard: Visual overview of spending patterns and trends

🏢 Enterprise Features

🛡️ Robust Error Handling: Custom error types with proper error categorization
✅ Input Validation: Comprehensive validation for all user inputs
🏗️ Service Layer Architecture: Clean separation of business logic
🔧 Middleware Support: Cross-cutting concerns like logging, rate limiting, and metrics
🧪 Comprehensive Testing: Unit tests with mocking and test coverage
📝 Structured Logging: JSON logging with context and correlation IDs
🗄️ Database Abstraction: Interface-based database layer with PostgreSQL support
⚙️ Configuration Management: Environment-based configuration with validation
🚦 Rate Limiting: Built-in rate limiting to prevent abuse
📊 Metrics Collection: Application metrics for monitoring

🏗️ Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Telegram API  │    │   Bot Handler   │    │  Service Layer  │
│                 │◄──►│                 │◄──►│                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │   Middleware    │    │   Validation    │
                       │                 │    │                 │
                       └─────────────────┘    └─────────────────┘
                                │                       │
                                ▼                       ▼
                       ┌─────────────────┐    ┌─────────────────┐
                       │  Database Layer │    │   Error Handler │
                       │                 │    │                 │
                       └─────────────────┘    └─────────────────┘
                                │
                                ▼
                       ┌─────────────────┐
                       │   PostgreSQL    │
                       │                 │
                       └─────────────────┘

🚀 Quick Start

🚀 One-Command Setup (Recommended)

For the fastest setup experience, use our automated setup script:

# Clone the repository
git clone https://github.com/MitulShah1/expense-tracker-bot.git
cd expense-tracker-bot

# Run the quick start script
./scripts/quick-start.sh

This script will automatically:

✅ Check all prerequisites (Go, Docker)
📝 Create and configure your .env file
🗄️ Start PostgreSQL database with Docker
🔧 Install dependencies and run migrations
🏗️ Build the application
🧪 Run tests
🚀 Provide next steps

📋 Prerequisites

Go 1.21 or higher
Docker and Docker Compose
Git (for cloning)

⚙️ Manual Setup

If you prefer manual setup or the automated script doesn't work:

Step 1: Clone the Repository

git clone https://github.com/MitulShah1/expense-tracker-bot.git
cd expense-tracker-bot

Step 2: Run Complete Setup Script

# Make scripts executable
chmod +x scripts/*.sh

# Run the complete setup
./scripts/setup.sh

Step 3: Manual Environment Configuration

Create the environment file:

cp .env.example .env  # if .env.example exists
# or create manually:

Configure your environment variables:

# Telegram Bot Configuration
TELEGRAM_TOKEN=your_telegram_bot_token
BOT_ID=your_bot_id

# Database Configuration
DATABASE_URL=postgres://postgres:password@localhost:5432/expense_tracker?sslmode=disable

# Application Configuration
LOG_LEVEL=info
IS_DEV_MODE=true

# Database Connection Pool (optional)
DB_MAX_OPEN_CONNS=25
DB_MAX_IDLE_CONNS=5
DB_CONN_MAX_LIFETIME=5m

Note: You'll need to create a Telegram bot first. Visit @BotFather on Telegram to create your bot and get the token.

Step 4: Manual Database Setup

Start PostgreSQL using Docker Compose:
```
docker-compose up -d postgres
```
Run database migrations:
```
make migrate
```

Step 5: Manual Application Setup

Install dependencies:
```
make deps
```
Build the application:
```
make build
```
Run the application:
```
make run
```

🎯 After Setup

Once setup is complete:

Update your bot token: Edit .env file and replace your_telegram_bot_token_here with your actual bot token
Start the bot: ./expense-tracker-bot or make run
Test the bot: Use ./scripts/test_bot.sh to test functionality
Access pgAdmin: Visit http://localhost:8080 (admin@expense-tracker.com / admin)

🔧 Available Scripts

./scripts/quick-start.sh - One-command setup with confirmation
./scripts/setup.sh - Complete automated setup
./scripts/setup_database.sh - Database-only setup
./scripts/test_bot.sh - Test the bot functionality

🧪 Testing

🏃‍♂️ Running Tests

# Run all tests
make test

# Run tests with coverage
make test-coverage

# Run specific test package
go test ./internal/services/...

📊 Test Coverage

The application includes comprehensive unit tests with:

✅ Service layer testing with mocked dependencies
✅ Input validation testing
✅ Error handling testing
✅ Database operation testing

🔧 Development

🎯 Code Quality

# Format code
make fmt

# Run linter
make lint

# Run all quality checks
make all

🚀 Adding New Features

Service Layer: Add business logic in internal/services/
Validation: Add input validation in internal/validation/
Database: Add database operations in internal/database/
Tests: Add corresponding tests in the same package
Documentation: Update this README and add inline documentation

⚠️ Error Handling

The application uses custom error types for better error categorization:

ValidationError: Input validation errors
NotFoundError: Resource not found errors
DatabaseError: Database operation errors
TelegramError: Telegram API errors
UnauthorizedError: Authorization errors
RateLimitError: Rate limiting errors

📊 Monitoring & Observability

📝 Logging

The application uses structured JSON logging with:

🔗 Request correlation IDs
👤 User context
⚡ Performance metrics
❌ Error details

📈 Metrics

Built-in metrics collection for:

📊 Request counts
❌ Error rates
⏱️ Response times
👥 Active users

🏥 Health Checks

Database connectivity and application health monitoring.

🔒 Security

🛡️ Input Validation

✅ Comprehensive validation for all user inputs
🛡️ SQL injection prevention through parameterized queries
🚦 Rate limiting to prevent abuse
🔐 User authorization checks

🔐 Data Protection

🔒 Secure database connections
⚙️ Environment-based configuration
🚫 No sensitive data in logs

🚀 Deployment

🐳 Docker Deployment

# Build Docker image
docker build -t expense-tracker-bot .

# Run with Docker Compose
docker-compose up -d

🏭 Production Considerations

⚙️ Use environment-specific configurations
📝 Set up proper logging aggregation
🗄️ Configure database connection pooling
📊 Implement monitoring and alerting
💾 Set up backup strategies

🤝 Contributing

We welcome contributions! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Contribution Guidelines

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-feature)
✏️ Make your changes
🧪 Add tests for new functionality
✅ Ensure all tests pass (make test)
📤 Commit your changes (git commit -m 'Add some amazing feature')
🚀 Push to the branch (git push origin feature/amazing-feature)
📋 Open a Pull Request

📏 Code Standards

📚 Follow Go coding standards and conventions
🧪 Add comprehensive tests for new functionality
📖 Update documentation for any new features
💬 Use meaningful commit messages
🔍 Ensure code passes linting (make lint)

📝 License

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

🆘 Support

Need help? Here are your options:

🐛 Create an issue in the GitHub repository
📚 Check the documentation in the docs/ directory
🧪 Review the code examples in the test files
💬 Join our community discussions

🙏 Acknowledgments

Built with Go and PostgreSQL
Uses Telegram Bot API for messaging
Inspired by the need for better personal expense tracking

Made with ❤️ using Go and PostgreSQL

⬆️ Back to top

Directories ¶

Path	Synopsis
cmd
internal
application Package application provides the main application struct and lifecycle management for the expense tracker bot.	Package application provides the main application struct and lifecycle management for the expense tracker bot.
bot Package bot implements the Telegram bot functionality for expense tracking.	Package bot implements the Telegram bot functionality for expense tracking.
config Package config provides configuration management for the expense tracker bot.	Package config provides configuration management for the expense tracker bot.
database Package database provides PostgreSQL database operations for the expense tracker bot.	Package database provides PostgreSQL database operations for the expense tracker bot.
errors Package errors provides custom error types for the expense tracker bot.	Package errors provides custom error types for the expense tracker bot.
logger Package logger provides logging functionality for the application.	Package logger provides logging functionality for the application.
models Package models defines the data structures used throughout the application.	Package models defines the data structures used throughout the application.
services Package services provides business logic services for the expense tracker bot.	Package services provides business logic services for the expense tracker bot.
validation Package validation provides input validation utilities for the expense tracker bot.	Package validation provides input validation utilities for the expense tracker bot.
pkg
utils Package utils provides utility functions used throughout the expense tracker application.	Package utils provides utility functions used throughout the expense tracker application.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL