How abdtirtayasa24/ai-expense-telegram works
1. This repository is a two-client expense platform: a Telegram Bot for conversational transaction capture and a React Telegram Mini App for dashboards, budgets, transaction management, settings, and AI budgeting advice. The backend is the central orchestration layer connecting both clients to Supabase and Gemini.
2. The backend is a Python FastAPI service in backend/app. Its API surface is split into route modules for auth, transactions, budgets, dashboard, advisor, settings, health, and internal jobs. main.py wires the app together, while core/config.py and core/telegram_auth.py hold runtime config and Telegram signature validation.
3. Persistence is in Supabase PostgreSQL, accessed through repository classes under backend/app/repositories. The repositories map to distinct domains: users, transactions, budgets, advisor insights, advisor chat messages, conversation states, registration tokens, and pending token claims. SQL migrations in supabase/migrations define the schema, indexes, RLS hardening, and scheduled-state/token tables.
4. The main business logic sits in backend/app/services. Key services include transaction parsing, rule parsing, cashflow period computation, category normalization, JWT/token handling, advisor chat, advisor mode timeout, and registration token cleanup. These services sit between API/bot entry points and the repositories.
5. Telegram bot behavior is isolated under backend/app/bot. It handles webhook entry, onboarding, command processing, transaction ingestion, advisor-mode chat flow, token claiming, and response formatting. This is the conversational ingestion path for Indonesian natural-language expense/income messages.
6. AI is used in two places. services/gemini_parser.py provides a fallback structured parser for ambiguous transaction text, and the advisor subsystem uses Gemini-backed prompts in backend/app/prompts for budgeting guidance and insights. The repo also contains tests for parser behavior and advisor guardrails, indicating the AI layer is constrained rather than free-form.
7. Authentication is split by channel. Telegram users authenticate to the backend with Telegram initData HMAC verification plus a JWT issued by the backend. There is also a registration-token flow for linking bot users, including pending claims and cleanup of expired claims.
8. The frontend is a React + Vite Telegram Mini App in frontend/src. It is organized around API clients for auth, transactions, budgets, dashboard, advisor, and settings, with UI components for dashboard summary, budget panel, insights, transactions, edit modal, and settings. It is a consumer of the backend API only; no direct database access.
9. Data flow is centered on four domain workflows: transaction creation and editing; budget management and progress tracking; dashboard summary generation from transactions/budgets; and advisor insight generation/chat history. All of these persist through the backend repositories and surface in both the Mini App and bot where relevant.
10. There is an internal-ops boundary in the backend for scheduled or protected jobs. The internal route and tests reference timeout handling for advisor mode and cleanup of stale registration tokens, protected by a CRON_SECRET.
11. External dependencies that materially shape the architecture are Telegram Bot API, Supabase Postgres, Google Gemini, and JWT-based session issuance. Deployment is split between Dockerized backend and a static frontend deployment target such as Vercel or Netlify, with environment variables separating server-only secrets from frontend config.
12. The repo also contains high-value supporting material: docs/ARCHITECTURE.md for detailed flow descriptions, docs/DEPLOYMENT.md for runtime topology, and scripts/seed_demo_data.py / scripts/smoke_test.py for non-production data and verification. Tests cover the major domain boundaries, which reinforces that the architecture is organized around explicit service/repository seams rather than a monolith of handlers.
Main entry points: services Services · routes API routes · main.py App entry · App.tsx Mini App
Components 18
Backend
FastAPI service, bot handlers, core services, repositories, and integrations.
- App entry · Wires the backend application together.
backend/app/main.py - Config · Loads environment and runtime settings.
backend/app/core/config.py - Telegram auth · Validates Telegram initData and request authenticity.
backend/app/core/telegram_auth.py - API routes · Auth, transactions, budgets, dashboard, advisor, settings, health, and internal routes.
backend/app/api/routes - Bot webhook · Receives Telegram updates and starts conversational flows.
backend/app/bot/webhook.py - Bot flows · Onboarding, commands, transaction capture, advisor chat, token claim, and responses.
backend/app/bot - Services · Transaction parsing, advisor logic, token handling, and cashflow computation.
backend/app/services - Gemini parser · Structured fallback parser for ambiguous transaction text.
backend/app/services/gemini_parser.py - Advisor prompts · Prompt templates for chat guidance and insight generation.
backend/app/prompts - Repositories · Domain repositories for users, transactions, budgets, insights, chat, states, and token claims.
backend/app/repositories - Supabase client · Backend integration for Supabase/Postgres access.
backend/app/integrations/supabase_client.py
Frontend
React Telegram Mini App and its API/UI layer.
- Mini App · Telegram Mini App entry point and page composition.
frontend/src/App.tsx - API clients · Typed clients for auth, transactions, budgets, dashboard, advisor, and settings.
frontend/src/api - UI panels · Dashboard, budgets, transactions, insights, edit modal, and settings panels.
frontend/src/components
Persistence
Supabase schema and repository-backed domain storage.
- Schema migrations · Defines tables, indexes, RLS hardening, cashflow settings, and token tables.
supabase/migrations
External services
Third-party APIs the system depends on.
- Telegram API · Bot platform used for conversational transaction capture.
- Gemini API · Generates fallback parsing and budgeting guidance.
- Supabase Postgres · Primary persistence layer for users, transactions, budgets, advisor data, and tokens.
Connections 19
- Mini App → API clients: calls · UI requests backend data through typed API clients.
- Mini App → UI panels: renders · Main app composes the dashboard, budget, transaction, insight, and settings panels.
- API clients → API routes: HTTP · Mini App consumes the backend API surface.
- App entry → API routes: mounts · App entry registers the route modules.
- App entry → Bot webhook: hooks · App entry exposes the bot ingress path.
- App entry → Config: loads · Runtime settings are read during startup.
- API routes → Services: orchestrates · Routes delegate domain work to services.
- Bot webhook → Bot flows: dispatches · Incoming Telegram updates are routed into bot flows.
- Bot flows → Services: uses · Bot conversations rely on the same core business logic as the API.
- Services → Repositories: persists · Services read and write through repositories.
- Repositories → Supabase client: adapts · Repositories use the Supabase client as their storage adapter.
- Supabase client → Supabase Postgres: queries · All persistent state is stored in Supabase Postgres.
- Services → Gemini parser: fallback parse · Ambiguous transaction text can be parsed with Gemini-assisted extraction.
- Services → Advisor prompts: formats prompts · Advisor services build prompts from repository state and templates.
- Gemini parser → Gemini API: calls · Structured parsing uses the Gemini model when needed.
- Services → Telegram API: sends replies · Bot responses are delivered back through Telegram.
- API routes → Telegram API: authenticates · Telegram initData verification supports authenticated sessions.
- Schema migrations → Supabase Postgres: defines · Migration files shape the live database schema and constraints.
- API routes → Config: reads config · Endpoints depend on shared runtime settings and secrets.