# dagmawi54/pie-payment-app architecture

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

- Interactive diagram: https://gitdiagram.com/dagmawi54/pie-payment-app
- Repository: https://github.com/dagmawi54/pie-payment-app

## Overview

This repository implements Block Payments: a Telegram-based payment and receipt workflow with a web mini-app and administrative console. The sampled Node bot buffers Telegram text and receipt-photo OCR, extracts payment details, checks transaction duplicates, records payments in Google Sheets, and replies with status. The admin console manages groups, houses, spreadsheets, advertisements, and other operational areas through a web API. Source excerpts support the bot’s principal calls and selected admin UI interactions; backend route wiring and several unsampled capabilities are represented conservatively.

Main entry points: [`webapp/admin-panel/src/App.jsx`](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/App.jsx) (Admin console), [`webapp/admin-panel/src/api.js`](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/api.js) (Admin API client), [`index.js`](https://github.com/dagmawi54/pie-payment-app/blob/main/index.js) (Receipt bot), [`webapp/admin-panel/src/pages/GroupsManager.jsx`](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/GroupsManager.jsx) (Group management)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_receipt["Receipt processing"]
  node_bot["Receipt bot<br/>[index.js]"]
  node_ocr["OCR service"]
  node_payment_extract["Payment extraction"]
end

subgraph group_admin["Administration"]
  node_webapp["Admin console<br/>[App.jsx]"]
  node_groups_ui["Group management<br/>[GroupsManager.jsx]"]
  node_houses_ui["House management<br/>[HousesManager.jsx]"]
  node_sheets_ui["Sheet management<br/>[SheetsManager.jsx]"]
  node_ads_ui["Ad campaigns<br/>[AdsManager.jsx]"]
  node_verification_ui["Receipt review"]
  node_admin_api_client["Admin API client<br/>[api.js]"]
  node_admin_api["Admin backend<br/>[admin_api.py]"]
  node_web_api["Web application API<br/>[api.py]"]
  node_ads_logic["Campaign lifecycle<br/>[ads_manager.py]"]
end

subgraph group_platform["Platform services"]
  node_telegram["Telegram"]
  node_sheets[("Google Sheets")]
  node_sync_worker["House-sheet sync"]
  node_launcher["Mini-app launcher"]
end

subgraph group_quality["Receipt evaluation"]
  node_receipt_lab["Receipt evaluation tools<br/>[cli.py]"]
end

node_resident(("Telegram user"))
node_web_user(("Admin user"))

node_resident -->|"sends receipt"| node_telegram
node_telegram -->|"delivers messages"| node_bot
node_bot -->|"runs OCR"| node_ocr
node_bot -->|"extracts details"| node_payment_extract
node_bot -->|"checks and saves"| node_sheets
node_bot -->|"replies"| node_telegram
node_web_user -->|"manages payments"| node_webapp
node_webapp -->|"uses API"| node_admin_api_client
node_webapp -->|"routes to"| node_groups_ui
node_webapp -->|"routes to"| node_houses_ui
node_webapp -->|"routes to"| node_sheets_ui
node_webapp -->|"routes to"| node_ads_ui
node_webapp -->|"routes to"| node_verification_ui
node_groups_ui -->|"loads and updates"| node_admin_api_client
node_houses_ui -->|"manages houses"| node_admin_api_client
node_sheets_ui -->|"manages sheets"| node_admin_api_client
node_ads_ui -->|"saves campaigns"| node_admin_api_client
node_admin_api_client -->|"sends requests"| node_admin_api
node_launcher -->|"launches mini-app"| node_telegram
node_sync_worker -->|"loads sync function"| node_admin_api

click node_bot "https://github.com/dagmawi54/pie-payment-app/blob/main/index.js"
click node_webapp "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/App.jsx"
click node_groups_ui "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/GroupsManager.jsx"
click node_houses_ui "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/HousesManager.jsx"
click node_sheets_ui "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/SheetsManager.jsx"
click node_ads_ui "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/AdsManager.jsx"
click node_verification_ui "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/ReceiptVerificationManager.jsx"
click node_admin_api_client "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/api.js"
click node_admin_api "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin_api.py"
click node_web_api "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/api.py"
click node_ads_logic "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/ads_manager.py"
click node_sync_worker "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/house_sheet_sync_worker.py"
click node_launcher "https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/launcher_bot_service.py"
click node_receipt_lab "https://github.com/dagmawi54/pie-payment-app/blob/main/receipt_lab/cli.py"

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_bot,node_ocr,node_payment_extract,node_resident,node_web_user toneBlue
class node_webapp,node_groups_ui,node_houses_ui,node_sheets_ui,node_ads_ui,node_verification_ui,node_admin_api_client,node_admin_api,node_web_api,node_ads_logic toneAmber
class node_telegram,node_sheets,node_sync_worker,node_launcher toneMint
class node_receipt_lab toneRose
```

## Components

### Receipt processing

- [Receipt bot](https://github.com/dagmawi54/pie-payment-app/blob/main/index.js): `index.js`
- **OCR service**
- **Payment extraction**

### Administration

- [Admin console](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/App.jsx): `webapp/admin-panel/src/App.jsx`
- [Group management](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/GroupsManager.jsx): `webapp/admin-panel/src/pages/GroupsManager.jsx`
- [House management](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/HousesManager.jsx): `webapp/admin-panel/src/pages/HousesManager.jsx`
- [Sheet management](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/SheetsManager.jsx): `webapp/admin-panel/src/pages/SheetsManager.jsx`
- [Ad campaigns](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/AdsManager.jsx): `webapp/admin-panel/src/pages/AdsManager.jsx`
- [Receipt review](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/pages/ReceiptVerificationManager.jsx): `webapp/admin-panel/src/pages/ReceiptVerificationManager.jsx`
- [Admin API client](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin-panel/src/api.js): `webapp/admin-panel/src/api.js`
- [Admin backend](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/admin_api.py): `webapp/admin_api.py`
- [Web application API](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/api.py): `webapp/api.py`
- [Campaign lifecycle](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/ads_manager.py): `webapp/ads_manager.py`

### Platform services

- **Telegram**
- **Google Sheets**
- [House-sheet sync](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/house_sheet_sync_worker.py): `webapp/house_sheet_sync_worker.py`
- [Mini-app launcher](https://github.com/dagmawi54/pie-payment-app/blob/main/webapp/launcher_bot_service.py): `webapp/launcher_bot_service.py`

### Receipt evaluation

- [Receipt evaluation tools](https://github.com/dagmawi54/pie-payment-app/blob/main/receipt_lab/cli.py): `receipt_lab/cli.py`

### Other components

- **Telegram user**
- **Admin user**

## Connections

- Telegram user → Telegram: sends receipt
- Telegram → Receipt bot: delivers messages
- Receipt bot → OCR service: runs OCR
- Receipt bot → Payment extraction: extracts details
- Receipt bot → Google Sheets: checks and saves
- Receipt bot → Telegram: replies
- Admin user → Admin console: manages payments
- Admin console → Admin API client: uses API
- Admin console → Group management: routes to
- Admin console → House management: routes to
- Admin console → Sheet management: routes to
- Admin console → Ad campaigns: routes to
- Admin console → Receipt review: routes to
- Group management → Admin API client: loads and updates
- House management → Admin API client: manages houses
- Sheet management → Admin API client: manages sheets
- Ad campaigns → Admin API client: saves campaigns
- Admin API client → Admin backend: sends requests
- Mini-app launcher → Telegram: launches mini-app
- House-sheet sync → Admin backend: loads sync function