🚀 SplitCore — Telegram Expense Organizer

SplitCore is a Telegram bot designed to automate shared expense tracking for groups of friends, travelers, or event organizers. No more messy Excel sheets or "who owes whom" arguments.

🔥 The Core Idea

Users create "Funds" (events), invite friends via unique deep-links, and record their expenses. The bot automatically calculates the balance: who overpaid and who needs to settle their debt using a greedy matching algorithm to minimize transactions.

🛠 Tech Stack

• Language: Go (Golang) 1.26.2
• Framework:telebot.v4 (Telegram Bot API)
• Database: PostgreSQL
• Driver: pgx/v5 (Connection Pool)
• State Management: Redis 8.6.2 via go-redis/v9 for persistent FSM.
• Infrastructure: Docker, Docker Compose, Makefile.
• Migrations: golang-migrate.

🏗 Architecture (Clean Architecture)

The project is built with a strict separation of concerns, ensuring high testability and scalability:

• cmd/bot/ — Entry point, initialization, and Dependency Injection.
• internal/domain/ — Business entities, Data models, and Core interfaces.
• internal/repository/ — Database access layer (PostgreSQL implementation).
• internal/usecase/ — Core business logic, math calculations, and data processing.
• internal/delivery/telegram/ — Bot-specific UI logic (handlers, menus, router).
• internal/pkg/ — Internal utilities (e.g., deep-link generators).

📍 Roadmap

MVP (Completed) ✅

• Clean Architecture setup and Dependency Injection.
• PostgreSQL integration with migrations.
• FSM for user input handling and seamless UX.
• Fund creation and unique Deep-Link generation.
• Expense logging and history tracking.
• Advanced debt calculation algorithm (Settle Up).
• Move FSM states from in-memory to Redis for persistence and horizontal scaling.
• Graceful shutdown implementation.
• Table-Driven Unit Tests for the settlement math module.
• CI/CD Pipeline (GitHub Actions + golangci-lint).

**V1.1.0

• Virtual Users (Add members without Telegram accounts).

Enhancements (Future) 🚀

• Deploy to VPS (DigitalOcean).
• Multi-currency support.

🚀 Getting Started (Dev)

Required Docker, docker compose.

1. Clone the repository:

   git clone https://github.com/GanFay/SplitCore.git

2. Set up environment variables in a .env file (Bot token, DB credentials).
3. Start the database and application using Makefile:

   make services-run

4. Run migrations (if executing locally):

   make migrate-up