# abdtirtayasa24/ai-expense-telegram architecture

> Architecture diagram of the GitHub repository abdtirtayasa24/ai-expense-telegram, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdtirtayasa24/ai-expense-telegram
- Repository: https://github.com/abdtirtayasa24/ai-expense-telegram

## Overview

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: [`backend/app/services`](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/services) (Services), [`backend/app/api/routes`](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/api/routes) (API routes), [`backend/app/main.py`](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/main.py) (App entry), [`frontend/src/App.tsx`](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/frontend/src/App.tsx) (Mini App)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend"]
  node_backend_main["App entry<br/>FastAPI bootstrap<br/>[main.py]"]
  node_backend_config["Config<br/>[config.py]"]
  node_backend_telegram_auth["Telegram auth<br/>signature verification<br/>[telegram_auth.py]"]
  node_backend_api_routes["API routes<br/>HTTP endpoints"]
  node_backend_bot_webhook["Bot webhook<br/>Telegram ingress<br/>[webhook.py]"]
  node_backend_bot_flow["Bot flows<br/>conversation logic"]
  node_backend_services["Services<br/>business logic"]
  node_backend_gemini_parser["Gemini parser<br/>LLM fallback<br/>[gemini_parser.py]"]
  node_backend_prompts["Advisor prompts<br/>prompt templates"]
  node_backend_repositories["Repositories<br/>data access"]
  node_backend_supabase_client["Supabase client<br/>db adapter<br/>[supabase_client.py]"]
end

subgraph group_frontend["Frontend"]
  node_frontend_app["Mini App<br/>React shell<br/>[App.tsx]"]
  node_frontend_api["API clients<br/>client layer"]
  node_frontend_components["UI panels<br/>views"]
end

subgraph group_data["Persistence"]
  node_supabase_migrations[("Schema migrations<br/>postgres DDL")]
end

subgraph group_external["External services"]
  node_telegram_api(("Telegram API<br/>external messaging"))
  node_gemini_api(("Gemini API<br/>external LLM"))
  node_supabase_postgres[("Supabase Postgres<br/>external database")]
end

node_frontend_app -->|"calls"| node_frontend_api
node_frontend_app -->|"renders"| node_frontend_components
node_frontend_api -->|"HTTP"| node_backend_api_routes
node_backend_main -->|"mounts"| node_backend_api_routes
node_backend_main -->|"hooks"| node_backend_bot_webhook
node_backend_main -->|"loads"| node_backend_config
node_backend_api_routes -->|"orchestrates"| node_backend_services
node_backend_bot_webhook -->|"dispatches"| node_backend_bot_flow
node_backend_bot_flow -->|"uses"| node_backend_services
node_backend_services -->|"persists"| node_backend_repositories
node_backend_repositories -->|"adapts"| node_backend_supabase_client
node_backend_supabase_client -->|"queries"| node_supabase_postgres
node_backend_services -->|"fallback parse"| node_backend_gemini_parser
node_backend_services -->|"formats prompts"| node_backend_prompts
node_backend_gemini_parser -->|"calls"| node_gemini_api
node_backend_services -->|"sends replies"| node_telegram_api
node_backend_api_routes -->|"authenticates"| node_telegram_api
node_supabase_migrations -->|"defines"| node_supabase_postgres
node_backend_api_routes -->|"reads config"| node_backend_config

click node_backend_main "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/main.py"
click node_backend_config "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/core/config.py"
click node_backend_telegram_auth "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/core/telegram_auth.py"
click node_backend_api_routes "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/api/routes"
click node_backend_bot_webhook "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/bot/webhook.py"
click node_backend_bot_flow "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/bot"
click node_backend_services "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/services"
click node_backend_gemini_parser "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/services/gemini_parser.py"
click node_backend_prompts "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/prompts"
click node_backend_repositories "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/repositories"
click node_backend_supabase_client "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/integrations/supabase_client.py"
click node_frontend_app "https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/frontend/src/api"
click node_frontend_components "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/frontend/src/components"
click node_supabase_migrations "https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/supabase/migrations"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_backend_main,node_backend_config,node_backend_telegram_auth,node_backend_api_routes,node_backend_bot_webhook,node_backend_bot_flow,node_backend_services,node_backend_gemini_parser,node_backend_prompts,node_backend_repositories,node_backend_supabase_client toneBlue
class node_frontend_app,node_frontend_api,node_frontend_components toneAmber
class node_supabase_migrations toneMint
class node_telegram_api,node_gemini_api,node_supabase_postgres toneRose
```

## Components

### Backend

FastAPI service, bot handlers, core services, repositories, and integrations.

- [App entry](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/main.py): FastAPI bootstrap · Wires the backend application together. · `backend/app/main.py`
- [Config](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/core/config.py): runtime config · Loads environment and runtime settings. · `backend/app/core/config.py`
- [Telegram auth](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/core/telegram_auth.py): signature verification · Validates Telegram initData and request authenticity. · `backend/app/core/telegram_auth.py`
- [API routes](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/api/routes): HTTP endpoints · Auth, transactions, budgets, dashboard, advisor, settings, health, and internal routes. · `backend/app/api/routes`
- [Bot webhook](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/bot/webhook.py): Telegram ingress · Receives Telegram updates and starts conversational flows. · `backend/app/bot/webhook.py`
- [Bot flows](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/bot): conversation logic · Onboarding, commands, transaction capture, advisor chat, token claim, and responses. · `backend/app/bot`
- [Services](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/services): business logic · Transaction parsing, advisor logic, token handling, and cashflow computation. · `backend/app/services`
- [Gemini parser](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/services/gemini_parser.py): LLM fallback · Structured fallback parser for ambiguous transaction text. · `backend/app/services/gemini_parser.py`
- [Advisor prompts](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/prompts): prompt templates · Prompt templates for chat guidance and insight generation. · `backend/app/prompts`
- [Repositories](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/backend/app/repositories): data access · Domain repositories for users, transactions, budgets, insights, chat, states, and token claims. · `backend/app/repositories`
- [Supabase client](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/backend/app/integrations/supabase_client.py): db adapter · Backend integration for Supabase/Postgres access. · `backend/app/integrations/supabase_client.py`

### Frontend

React Telegram Mini App and its API/UI layer.

- [Mini App](https://github.com/abdtirtayasa24/ai-expense-telegram/blob/main/frontend/src/App.tsx): React shell · Telegram Mini App entry point and page composition. · `frontend/src/App.tsx`
- [API clients](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/frontend/src/api): client layer · Typed clients for auth, transactions, budgets, dashboard, advisor, and settings. · `frontend/src/api`
- [UI panels](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/frontend/src/components): views · Dashboard, budgets, transactions, insights, edit modal, and settings panels. · `frontend/src/components`

### Persistence

Supabase schema and repository-backed domain storage.

- [Schema migrations](https://github.com/abdtirtayasa24/ai-expense-telegram/tree/main/supabase/migrations): postgres DDL · Defines tables, indexes, RLS hardening, cashflow settings, and token tables. · `supabase/migrations`

### External services

Third-party APIs the system depends on.

- **Telegram API**: external messaging · Bot platform used for conversational transaction capture.
- **Gemini API**: external LLM · Generates fallback parsing and budgeting guidance.
- **Supabase Postgres**: external database · Primary persistence layer for users, transactions, budgets, advisor data, and tokens.

## Connections

- 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.
