SplitSage — Telegram Shared Expense Bot

A Telegram bot + Mini App for tracking shared expenses inside group chats. Works like a lightweight Splitwise, scoped to "tabs" per group.

Features

• Tabs — each group has one active tab at a time. Open a tab, add expenses, close it after settling. All past tabs remain visible.
• Flexible splits — equal, exact amounts, by percentage, or by share ratio
• Balances — see who owes whom with debt simplification (fewest transactions)
• Settle up — record payments; close the tab when everyone's even
• Mini App UI — full expense management via Telegram's built-in browser

Tech Stack

• Backend: .NET 9, ASP.NET Core (minimal API)
• Database: PostgreSQL with Entity Framework Core 9
• Bot: Telegram.Bot 22 (long polling)
• Frontend: ASP.NET Core Razor Pages (server-rendered, served as a Telegram Mini App)

Getting Started

Prerequisites

• .NET 9 SDK
• PostgreSQL
• A Telegram bot token (via @BotFather)
• A public HTTPS URL for the mini-app (use ngrok for local dev)

Configuration

Fill in appsettings.Development.json:

{
  "ConnectionStrings": {
    "SplitSageDb": "Host=localhost;Port=5432;Database=splitsage;Username=postgres;Password=yourpassword"
  },
  "Telegram": {
    "Token": "<your-bot-token>",
    "DropPendingUpdates": true,
    "MiniAppUrl": "https://<your-ngrok-url>/miniapp"
  }
}

Run

# Apply database migrations
dotnet ef database update --project src/Bot.Telegram

# Start (bot + API + Razor Pages mini-app all in one process)
dotnet run --project src/Bot.Telegram

Bot Commands (inside a group)

Command	Description
/start or /menu	Opens the mini-app
/newtab <name>	Creates a new tab (fails if one is already active)
/closetab	Closes the active tab (fails if balances are outstanding)

Project Structure

src/Bot.Telegram/
├── Api/               Minimal API endpoints (JSON, used by external clients)
├── Common/            Infrastructure (DB, Bot polling, Auth middleware)
├── Features/          Domain entities + EF Core configurations
│   ├── Chats/         TelegramChat
│   ├── Tabs/          Tab (IsActive, Name, ChatId)
│   ├── Users/         User
│   ├── Expenses/      Expense + ExpenseShare + SplitType enum
│   └── Settlements/   Settlement
├── Pages/MiniApp/     Razor Pages mini-app (Auth, Index, Expenses,
│                      AddExpense, Balances, Settle, History)
└── Services/          BalanceService (net balance + debt simplification)