# 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

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

### 2. Configure Environment

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

### 3. Using Docker Compose (Recommended)

```bash
docker-compose up -d
```

This will start:
- PostgreSQL database
- Redis cache
- Telegram bot
- FastAPI web server

### 4. Manual Setup (Without Docker)

```bash
# 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

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

# Apply migrations
alembic upgrade head

# Rollback last migration
alembic downgrade -1
```

### Code Style

```bash
# 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