# buildwithsachin02/telegram_bot architecture

> Architecture diagram of the GitHub repository buildwithsachin02/telegram_bot, 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/buildwithsachin02/telegram_bot
- Repository: https://github.com/buildwithsachin02/telegram_bot

## Overview

SR Khata is a two-bot Telegram ledger: customers record purchases immediately, while payment and undo claims await owner review before changing ledger state. The customer bot also serves totals and history; the owner bot handles request decisions, reports, and ledger cleanup. The graph preserves these documented capabilities, but ownerBot.js and several service implementations were not sampled, so their internal call wiring is shown conservatively.

Main entry points: [`src/app.js`](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/app.js) (Customer bot), [`src/ownerBot.js`](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/ownerBot.js) (Owner bot), [`src/services/dataCleanupService.js`](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/dataCleanupService.js) (Ledger cleanup), [`src/services/ownerNotificationService.js`](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ownerNotificationService.js) (Owner notifications)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_customer["Customer workflow"]
  node_customer_bot["Customer bot<br/>[app.js]"]
  node_parser["Message parser<br/>[messageParser.js]"]
end

subgraph group_owner["Owner operations"]
  node_owner_bot["Owner bot<br/>[ownerBot.js]"]
  node_cleanup_commands["Cleanup commands"]
end

subgraph group_services["Domain services"]
  node_ledger_service["Ledger service<br/>[ledgerService.js]"]
  node_payment_service["Payment requests"]
  node_undo_service["Undo requests"]
  node_report_service["Owner reports"]
  node_cleanup_service["Ledger cleanup"]
  node_notification_service["Owner notifications"]
  node_user_service["User service<br/>[userService.js]"]
end

subgraph group_data["Persistence"]
  node_db_config["DB connection<br/>[db.js]"]
  node_user_model[("User records<br/>[User.js]")]
  node_transaction_model[("Transactions<br/>[Transaction.js]")]
  node_payment_model[("Payment requests<br/>[PaymentRequest.js]")]
  node_undo_model[("Undo requests<br/>[UndoRequest.js]")]
end

node_customer_actor(("Customer"))
node_owner_actor(("Shop owner"))
node_telegram(("Telegram"))
node_mongo[("MongoDB")]

node_customer_actor -->|"sends commands"| node_customer_bot
node_customer_bot -->|"replies"| node_telegram
node_customer_bot -->|"parses messages"| node_parser
node_customer_bot -->|"finds customers"| node_user_service
node_customer_bot -->|"records and reads ledger"| node_ledger_service
node_customer_bot -->|"creates payment claims"| node_payment_service
node_customer_bot -->|"creates undo claims"| node_undo_service
node_customer_bot -->|"notifies owner"| node_notification_service
node_owner_actor -->|"reviews and manages"| node_owner_bot
node_owner_bot -->|"sends owner updates"| node_telegram
node_owner_bot -->|"reviews payments"| node_payment_service
node_owner_bot -->|"reviews undos"| node_undo_service
node_owner_bot -->|"requests reports"| node_report_service
node_owner_bot -->|"dispatches cleanup"| node_cleanup_commands
node_cleanup_commands -->|"clears ledger data"| node_cleanup_service
node_notification_service -->|"sends notifications"| node_telegram
node_ledger_service -->|"reads and writes"| node_transaction_model
node_payment_service -->|"reads and transitions"| node_payment_model
node_payment_service -->|"checks conflicts"| node_undo_model
node_undo_service -->|"reads and transitions"| node_undo_model
node_undo_service -->|"checks conflicts"| node_payment_model
node_report_service -->|"aggregates ledger"| node_transaction_model
node_report_service -->|"looks up customers"| node_user_model
node_user_service -->|"reads and writes"| node_user_model
node_notification_service -->|"loads customer"| node_user_model
node_notification_service -->|"loads transaction"| node_transaction_model
node_cleanup_service -->|"deletes records"| node_transaction_model
node_cleanup_service -->|"deletes records"| node_payment_model
node_cleanup_service -->|"deletes records"| node_undo_model
node_db_config -->|"connects"| node_mongo

click node_customer_bot "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/app.js"
click node_parser "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/utils/messageParser.js"
click node_owner_bot "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/ownerBot.js"
click node_cleanup_commands "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/ownerCleanupCommands.js"
click node_ledger_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ledgerService.js"
click node_payment_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/paymentRequestService.js"
click node_undo_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/undoRequestService.js"
click node_report_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ownerReportService.js"
click node_cleanup_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/dataCleanupService.js"
click node_notification_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ownerNotificationService.js"
click node_user_service "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/userService.js"
click node_db_config "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/config/db.js"
click node_user_model "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/User.js"
click node_transaction_model "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/Transaction.js"
click node_payment_model "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/PaymentRequest.js"
click node_undo_model "https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/UndoRequest.js"

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_customer_bot,node_parser toneBlue
class node_owner_bot,node_cleanup_commands,node_mongo toneAmber
class node_ledger_service,node_payment_service,node_undo_service,node_report_service,node_cleanup_service,node_notification_service,node_user_service toneMint
class node_db_config,node_user_model,node_transaction_model,node_payment_model,node_undo_model toneRose
class node_customer_actor,node_owner_actor,node_telegram toneIndigo
```

## Components

### Customer workflow

- [Customer bot](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/app.js): `src/app.js`
- [Message parser](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/utils/messageParser.js): `src/utils/messageParser.js`

### Owner operations

- [Owner bot](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/ownerBot.js): `src/ownerBot.js`
- [Cleanup commands](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/ownerCleanupCommands.js): `src/ownerCleanupCommands.js`

### Domain services

- [Ledger service](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ledgerService.js): `src/services/ledgerService.js`
- [Payment requests](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/paymentRequestService.js): `src/services/paymentRequestService.js`
- [Undo requests](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/undoRequestService.js): `src/services/undoRequestService.js`
- [Owner reports](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ownerReportService.js): `src/services/ownerReportService.js`
- [Ledger cleanup](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/dataCleanupService.js): `src/services/dataCleanupService.js`
- [Owner notifications](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/ownerNotificationService.js): `src/services/ownerNotificationService.js`
- [User service](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/services/userService.js): `src/services/userService.js`

### Persistence

- [DB connection](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/config/db.js): `src/config/db.js`
- [User records](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/User.js): `src/models/User.js`
- [Transactions](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/Transaction.js): `src/models/Transaction.js`
- [Payment requests](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/PaymentRequest.js): `src/models/PaymentRequest.js`
- [Undo requests](https://github.com/buildwithsachin02/telegram_bot/blob/main/src/models/UndoRequest.js): `src/models/UndoRequest.js`

### Other components

- **Customer**
- **Shop owner**
- **Telegram**
- **MongoDB**

## Connections

- Customer → Customer bot: sends commands
- Customer bot → Telegram: replies
- Customer bot → Message parser: parses messages
- Customer bot → User service: finds customers
- Customer bot → Ledger service: records and reads ledger
- Customer bot → Payment requests: creates payment claims
- Customer bot → Undo requests: creates undo claims
- Customer bot → Owner notifications: notifies owner
- Shop owner → Owner bot: reviews and manages
- Owner bot → Telegram: sends owner updates
- Owner bot → Payment requests: reviews payments
- Owner bot → Undo requests: reviews undos
- Owner bot → Owner reports: requests reports
- Owner bot → Cleanup commands: dispatches cleanup
- Cleanup commands → Ledger cleanup: clears ledger data
- Owner notifications → Telegram: sends notifications
- Ledger service → Transactions: reads and writes
- Payment requests → Payment requests: reads and transitions
- Payment requests → Undo requests: checks conflicts
- Undo requests → Undo requests: reads and transitions
- Undo requests → Payment requests: checks conflicts
- Owner reports → Transactions: aggregates ledger
- Owner reports → User records: looks up customers
- User service → User records: reads and writes
- Owner notifications → User records: loads customer
- Owner notifications → Transactions: loads transaction
- Ledger cleanup → Transactions: deletes records
- Ledger cleanup → Payment requests: deletes records
- Ledger cleanup → Undo requests: deletes records
- DB connection → MongoDB: connects