# hahahagi/artha architecture

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

- Interactive diagram: https://gitdiagram.com/hahahagi/artha
- Repository: https://github.com/hahahagi/artha

## Overview

Artha records expenses through Telegram or its authenticated web dashboard, then stores and presents transactions alongside budgets and recurring subscriptions. Telegram input supports text, voice transcription, wallet/split-bill parsing, and interactive corrections; the web path adds receipt OCR, analytics, management, and export. Scheduled endpoints send subscription reminders and weekly digests. The README documents Google Sheets sync and PWA support; their runtime links are shown where the tree supports a component path. Some action and integration wiring is unsampled, so uncertain calls are omitted.

Main entry points: [`lib/prisma.ts`](https://github.com/hahahagi/artha/blob/main/lib/prisma.ts) (Prisma Client), [`app/api/telegram/webhook/route.ts`](https://github.com/hahahagi/artha/blob/main/app/api/telegram/webhook/route.ts) (Telegram Webhook), [`lib/telegram/bot.ts`](https://github.com/hahahagi/artha/blob/main/lib/telegram/bot.ts) (Bot Messaging), [`lib/supabase/server.ts`](https://github.com/hahahagi/artha/blob/main/lib/supabase/server.ts) (Supabase Auth Client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User Entry"]
  node_auth_pages["Login &amp; Registration<br/>[page.tsx]"]
  node_auth_actions["Auth Actions<br/>[actions.ts]"]
  node_auth_callback["OAuth Callback<br/>[route.ts]"]
end

subgraph group_telegram["Telegram Capture"]
  node_webhook["Telegram Webhook<br/>[route.ts]"]
  node_expense_parser["Expense Parser<br/>[expense-parser.ts]"]
  node_wallet_detector["Wallet Detection<br/>[wallet-detector.ts]"]
  node_voice["Voice Transcription<br/>[voice.ts]"]
  node_telegram_bot["Bot Messaging<br/>[bot.ts]"]
end

subgraph group_dashboard["Web Dashboard"]
  node_dashboard_home["Overview &amp; Analytics<br/>[page.tsx]"]
  node_expense_pages["Expense Management<br/>[page.tsx]"]
  node_expense_actions["Expense Actions<br/>[actions.ts]"]
  node_receipt_scanner["Receipt Scanner"]
  node_receipt_parser["Receipt Parser<br/>[receipt-parser.ts]"]
  node_budget_pages["Budget Management<br/>[page.tsx]"]
  node_budget_actions["Budget Actions<br/>[actions.ts]"]
  node_subscription_pages["Subscription Management<br/>[page.tsx]"]
  node_subscription_actions["Subscription Actions<br/>[actions.ts]"]
  node_settings["Account Settings<br/>[actions.ts]"]
  node_pwa["Offline Service Worker<br/>[sw.js]"]
end

subgraph group_services["Automation &amp; Sync"]
  node_export["Expense CSV Export<br/>[route.ts]"]
  node_reminders["Billing Reminders<br/>[route.ts]"]
  node_digest["Weekly Digest<br/>[route.ts]"]
  node_sheets["Google Sheets Sync<br/>[google-sheets.ts]"]
end

subgraph group_data["Identity &amp; Storage"]
  node_supabase_server["Supabase Auth Client<br/>[server.ts]"]
  node_prisma["Prisma Client<br/>[prisma.ts]"]
  node_database[("PostgreSQL Database")]
end

node_user(("User"))
node_telegram_user(("Telegram User"))
node_browser(("Web Browser"))
node_telegram_api["Telegram Bot API"]
node_wit_ai["Wit.ai"]
node_cron_caller(("Scheduled Caller"))

node_user -->|"sends message"| node_telegram_user
node_telegram_user -->|"sends input"| node_telegram_api
node_telegram_api -->|"delivers updates"| node_webhook
node_webhook -->|"parses text"| node_expense_parser
node_expense_parser -->|"detects wallet"| node_wallet_detector
node_webhook -->|"transcribes voice"| node_voice
node_voice -.->|"requests transcript"| node_wit_ai
node_webhook -->|"reads and writes"| node_prisma
node_webhook -->|"sends replies"| node_telegram_bot
node_telegram_bot -->|"sends messages"| node_telegram_api
node_user -->|"uses dashboard"| node_browser
node_browser -->|"opens account"| node_auth_pages
node_auth_pages -->|"submits credentials"| node_auth_actions
node_auth_actions -->|"authenticates"| node_supabase_server
node_auth_callback -->|"exchanges code"| node_supabase_server
node_auth_callback -->|"upserts user"| node_prisma
node_browser -->|"views analytics"| node_dashboard_home
node_dashboard_home -->|"checks session"| node_supabase_server
node_dashboard_home -->|"reads dashboard data"| node_prisma
node_browser -->|"manages expenses"| node_expense_pages
node_expense_pages -->|"submits changes"| node_expense_actions
node_expense_actions -->|"reads and writes"| node_prisma
node_browser -->|"scans receipt"| node_receipt_scanner
node_receipt_scanner -->|"parses OCR text"| node_receipt_parser
node_browser -->|"manages budgets"| node_budget_pages
node_budget_pages -->|"submits changes"| node_budget_actions
node_budget_actions -->|"reads and writes"| node_prisma
node_browser -->|"manages subscriptions"| node_subscription_pages
node_subscription_pages -->|"submits changes"| node_subscription_actions
node_subscription_actions -->|"reads and writes"| node_prisma
node_browser -->|"updates settings"| node_settings
node_settings -->|"updates account data"| node_prisma
node_browser -->|"requests CSV"| node_export
node_export -->|"checks session"| node_supabase_server
node_export -->|"reads expenses"| node_prisma
node_cron_caller -->|"triggers schedule"| node_reminders
node_reminders -->|"reads and updates"| node_prisma
node_reminders -->|"sends reminders"| node_telegram_bot
node_cron_caller -->|"triggers schedule"| node_digest
node_digest -->|"reads expense data"| node_prisma
node_digest -->|"sends digest"| node_telegram_bot
node_prisma -->|"queries"| node_database
node_settings -.->|"configures sync"| node_sheets
node_expense_actions -.->|"syncs transactions"| node_sheets
node_webhook -.->|"syncs transactions"| node_sheets
node_browser -->|"caches offline"| node_pwa

click node_webhook "https://github.com/hahahagi/artha/blob/main/app/api/telegram/webhook/route.ts"
click node_expense_parser "https://github.com/hahahagi/artha/blob/main/lib/parser/expense-parser.ts"
click node_wallet_detector "https://github.com/hahahagi/artha/blob/main/lib/parser/wallet-detector.ts"
click node_voice "https://github.com/hahahagi/artha/blob/main/lib/telegram/voice.ts"
click node_telegram_bot "https://github.com/hahahagi/artha/blob/main/lib/telegram/bot.ts"
click node_auth_pages "https://github.com/hahahagi/artha/blob/main/app/(auth)/login/page.tsx"
click node_auth_actions "https://github.com/hahahagi/artha/blob/main/app/(auth)/actions.ts"
click node_auth_callback "https://github.com/hahahagi/artha/blob/main/app/(auth)/callback/route.ts"
click node_supabase_server "https://github.com/hahahagi/artha/blob/main/lib/supabase/server.ts"
click node_dashboard_home "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/page.tsx"
click node_expense_pages "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/expenses/page.tsx"
click node_expense_actions "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/expenses/actions.ts"
click node_receipt_scanner "https://github.com/hahahagi/artha/blob/main/components/dashboard/receipt-scanner.tsx"
click node_receipt_parser "https://github.com/hahahagi/artha/blob/main/lib/parser/receipt-parser.ts"
click node_budget_pages "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/budgets/page.tsx"
click node_budget_actions "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/budgets/actions.ts"
click node_subscription_pages "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/subscriptions/page.tsx"
click node_subscription_actions "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/subscriptions/actions.ts"
click node_settings "https://github.com/hahahagi/artha/blob/main/app/(dashboard)/settings/actions.ts"
click node_export "https://github.com/hahahagi/artha/blob/main/app/api/export/expenses/route.ts"
click node_reminders "https://github.com/hahahagi/artha/blob/main/app/api/cron/reminders/route.ts"
click node_digest "https://github.com/hahahagi/artha/blob/main/app/api/cron/digest/route.ts"
click node_sheets "https://github.com/hahahagi/artha/blob/main/lib/sheets/google-sheets.ts"
click node_pwa "https://github.com/hahahagi/artha/blob/main/public/sw.js"
click node_prisma "https://github.com/hahahagi/artha/blob/main/lib/prisma.ts"

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_auth_pages,node_auth_actions,node_auth_callback,node_user,node_telegram_user,node_browser toneBlue
class node_webhook,node_expense_parser,node_wallet_detector,node_voice,node_telegram_bot toneAmber
class node_dashboard_home,node_expense_pages,node_expense_actions,node_receipt_scanner,node_receipt_parser,node_budget_pages,node_budget_actions,node_subscription_pages,node_subscription_actions,node_settings,node_pwa,node_telegram_api toneMint
class node_export,node_reminders,node_digest,node_sheets toneRose
class node_supabase_server,node_prisma,node_database,node_wit_ai,node_cron_caller toneIndigo
```

## Components

### User Entry

- [Login & Registration](https://github.com/hahahagi/artha/blob/main/app/(auth)/login/page.tsx): `app/(auth)/login/page.tsx`
- [Auth Actions](https://github.com/hahahagi/artha/blob/main/app/(auth)/actions.ts): `app/(auth)/actions.ts`
- [OAuth Callback](https://github.com/hahahagi/artha/blob/main/app/(auth)/callback/route.ts): `app/(auth)/callback/route.ts`

### Telegram Capture

- [Telegram Webhook](https://github.com/hahahagi/artha/blob/main/app/api/telegram/webhook/route.ts): `app/api/telegram/webhook/route.ts`
- [Expense Parser](https://github.com/hahahagi/artha/blob/main/lib/parser/expense-parser.ts): `lib/parser/expense-parser.ts`
- [Wallet Detection](https://github.com/hahahagi/artha/blob/main/lib/parser/wallet-detector.ts): `lib/parser/wallet-detector.ts`
- [Voice Transcription](https://github.com/hahahagi/artha/blob/main/lib/telegram/voice.ts): `lib/telegram/voice.ts`
- [Bot Messaging](https://github.com/hahahagi/artha/blob/main/lib/telegram/bot.ts): `lib/telegram/bot.ts`

### Web Dashboard

- [Overview & Analytics](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/page.tsx): `app/(dashboard)/page.tsx`
- [Expense Management](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/expenses/page.tsx): `app/(dashboard)/expenses/page.tsx`
- [Expense Actions](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/expenses/actions.ts): `app/(dashboard)/expenses/actions.ts`
- [Receipt Scanner](https://github.com/hahahagi/artha/blob/main/components/dashboard/receipt-scanner.tsx): `components/dashboard/receipt-scanner.tsx`
- [Receipt Parser](https://github.com/hahahagi/artha/blob/main/lib/parser/receipt-parser.ts): `lib/parser/receipt-parser.ts`
- [Budget Management](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/budgets/page.tsx): `app/(dashboard)/budgets/page.tsx`
- [Budget Actions](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/budgets/actions.ts): `app/(dashboard)/budgets/actions.ts`
- [Subscription Management](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/subscriptions/page.tsx): `app/(dashboard)/subscriptions/page.tsx`
- [Subscription Actions](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/subscriptions/actions.ts): `app/(dashboard)/subscriptions/actions.ts`
- [Account Settings](https://github.com/hahahagi/artha/blob/main/app/(dashboard)/settings/actions.ts): `app/(dashboard)/settings/actions.ts`
- [Offline Service Worker](https://github.com/hahahagi/artha/blob/main/public/sw.js): `public/sw.js`

### Automation & Sync

- [Expense CSV Export](https://github.com/hahahagi/artha/blob/main/app/api/export/expenses/route.ts): `app/api/export/expenses/route.ts`
- [Billing Reminders](https://github.com/hahahagi/artha/blob/main/app/api/cron/reminders/route.ts): `app/api/cron/reminders/route.ts`
- [Weekly Digest](https://github.com/hahahagi/artha/blob/main/app/api/cron/digest/route.ts): `app/api/cron/digest/route.ts`
- [Google Sheets Sync](https://github.com/hahahagi/artha/blob/main/lib/sheets/google-sheets.ts): `lib/sheets/google-sheets.ts`

### Identity & Storage

- [Supabase Auth Client](https://github.com/hahahagi/artha/blob/main/lib/supabase/server.ts): `lib/supabase/server.ts`
- [Prisma Client](https://github.com/hahahagi/artha/blob/main/lib/prisma.ts): `lib/prisma.ts`
- **PostgreSQL Database**

### Other components

- **User**
- **Telegram User**
- **Web Browser**
- **Telegram Bot API**
- **Wit.ai**
- **Scheduled Caller**

## Connections

- User → Telegram User: sends message
- Telegram User → Telegram Bot API: sends input
- Telegram Bot API → Telegram Webhook: delivers updates
- Telegram Webhook → Expense Parser: parses text
- Expense Parser → Wallet Detection: detects wallet
- Telegram Webhook → Voice Transcription: transcribes voice
- Voice Transcription → Wit.ai: requests transcript
- Telegram Webhook → Prisma Client: reads and writes
- Telegram Webhook → Bot Messaging: sends replies
- Bot Messaging → Telegram Bot API: sends messages
- User → Web Browser: uses dashboard
- Web Browser → Login & Registration: opens account
- Login & Registration → Auth Actions: submits credentials
- Auth Actions → Supabase Auth Client: authenticates
- OAuth Callback → Supabase Auth Client: exchanges code
- OAuth Callback → Prisma Client: upserts user
- Web Browser → Overview & Analytics: views analytics
- Overview & Analytics → Supabase Auth Client: checks session
- Overview & Analytics → Prisma Client: reads dashboard data
- Web Browser → Expense Management: manages expenses
- Expense Management → Expense Actions: submits changes
- Expense Actions → Prisma Client: reads and writes
- Web Browser → Receipt Scanner: scans receipt
- Receipt Scanner → Receipt Parser: parses OCR text
- Web Browser → Budget Management: manages budgets
- Budget Management → Budget Actions: submits changes
- Budget Actions → Prisma Client: reads and writes
- Web Browser → Subscription Management: manages subscriptions
- Subscription Management → Subscription Actions: submits changes
- Subscription Actions → Prisma Client: reads and writes
- Web Browser → Account Settings: updates settings
- Account Settings → Prisma Client: updates account data
- Web Browser → Expense CSV Export: requests CSV
- Expense CSV Export → Supabase Auth Client: checks session
- Expense CSV Export → Prisma Client: reads expenses
- Scheduled Caller → Billing Reminders: triggers schedule
- Billing Reminders → Prisma Client: reads and updates
- Billing Reminders → Bot Messaging: sends reminders
- Scheduled Caller → Weekly Digest: triggers schedule
- Weekly Digest → Prisma Client: reads expense data
- Weekly Digest → Bot Messaging: sends digest
- Prisma Client → PostgreSQL Database: queries
- Account Settings → Google Sheets Sync: configures sync
- Expense Actions → Google Sheets Sync: syncs transactions
- Telegram Webhook → Google Sheets Sync: syncs transactions
- Web Browser → Offline Service Worker: caches offline