init commit

README.md

@@ -0,0 +1,149 @@
+# 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