Finance Bot

Telegram bot for family finance management built with Python 3.12, aiogram, FastAPI, and PostgreSQL.

Features

• 👨‍👩‍👧‍👦 Family group management
• 💰 Income/expense tracking
• 💳 Multiple accounts (wallets)
• 📊 Analytics and reports
• 🎯 Savings goals
• 💵 Budget management
• 📱 Telegram bot interface
• ⚡ FastAPI REST API (optional)

Project Structure

finance_bot/
├── app/
│   ├── bot/                 # Telegram bot handlers
│   │   ├── handlers/        # Command handlers
│   │   ├── keyboards/       # Keyboard layouts
│   │   └── services/        # Bot services
│   ├── core/                # Core configuration
│   ├── db/                  # Database models & repositories
│   │   ├── models/          # SQLAlchemy models
│   │   └── repositories/    # Data access layer
│   ├── schemas/             # Pydantic schemas
│   ├── services/            # Business logic
│   │   ├── finance/         # Finance operations
│   │   ├── analytics/       # Analytics reports
│   │   └── notifications/   # Notifications
│   └── main.py              # Application entry point
├── migrations/              # Alembic migrations
├── requirements.txt         # Python dependencies
├── docker-compose.yml       # Docker services
├── Dockerfile              # Docker image
└── .env.example            # Environment template

Quick Start

1. Clone and Setup

git clone <repo>
cd finance_bot
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env
# Edit .env with your bot token and database settings

3. Using Docker Compose (Recommended)

docker-compose up -d

This will start:

• PostgreSQL database
• Redis cache
• Telegram bot
• FastAPI web server

4. Manual Setup (Without Docker)

# Install PostgreSQL and Redis locally

# Create database
createdb finance_db

# Run migrations
alembic upgrade head

# Run bot
python -m app.main

Configuration

Edit .env file:

BOT_TOKEN=your_bot_token_here
DATABASE_URL=postgresql+psycopg2://user:pass@localhost:5432/finance_db
REDIS_URL=redis://localhost:6379/0
APP_ENV=development

Development

Database Migrations

# Create new migration
alembic revision --autogenerate -m "description"

# Apply migrations
alembic upgrade head

# Rollback last migration
alembic downgrade -1

Code Style

# Format code
black app/

# Check linting
pylint app/

# Run tests
pytest tests/

Architecture

• Clean Architecture: Separated domains, services, repositories
• SQLAlchemy ORM: Database models and relationships
• Pydantic Validation: Type-safe schemas
• Repository Pattern: Data access abstraction
• Service Layer: Business logic separation
• aiogram 3.x: Modern async Telegram bot framework

Next Steps

1. ✅ Initialize project structure
2. ⬜ Complete database models and repositories
3. ⬜ Implement transaction handlers
4. ⬜ Add budget and goal management
5. ⬜ Create analytics reports
6. ⬜ Build notification system
7. ⬜ Add FastAPI REST endpoints
8. ⬜ Deploy to production

---

Created: December 10, 2025