# adtimokhin/ai-receipt-parser architecture

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

- Interactive diagram: https://gitdiagram.com/adtimokhin/ai-receipt-parser
- Repository: https://github.com/adtimokhin/ai-receipt-parser
- Video tour (about a minute): https://gitdiagram.com/adtimokhin/ai-receipt-parser/video

## Overview

This service is a single-user Telegram receipt-processing bot. A whitelisted user submits a receipt, the backend extracts and normalizes its data, asks for missing or corrected details, then saves a confirmed receipt; users can also retrieve or undo receipts and request date-range reports. The README documents country profiles and PDF/Excel reporting, while the excerpts show webhook validation, state-machine orchestration, and persistence. Some adapter wiring and report internals are unsampled, so uncertain links are omitted.

Main entry points: [`receipt_parser_backend/pipeline/engine.py`](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/engine.py) (Receipt state machine), [`receipt_parser_backend/reports/builder.py`](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/reports/builder.py) (Report assembly), [`receipt_parser_backend/telegram/routes.py`](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/routes.py) (Webhook validation), [`receipt_parser_backend/sessions/repository.py`](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/sessions/repository.py) (Session and receipt repository)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingress["Telegram ingress"]
  node_webhook["Webhook validation<br/>[routes.py]"]
  node_dispatch["Update dispatch<br/>[dispatch.py]"]
  node_tgclient["Telegram client<br/>[client.py]"]
end

subgraph group_workflow["Receipt workflow"]
  node_pipeline["Receipt state machine<br/>[engine.py]"]
  node_models["Receipt models<br/>[models.py]"]
  node_normalizer["Extraction normalization<br/>[normalizer.py]"]
  node_validator["Draft validation<br/>[validator.py]"]
  node_questions["Follow-up questions<br/>[questions.py]"]
  node_render["Draft and reply rendering<br/>[render.py]"]
  node_profiles["Country profiles<br/>[registry.py]"]
end

subgraph group_integrations["AI and file services"]
  node_extractor["Receipt extraction"]
  node_interpreter["Reply interpretation"]
  node_answer["Receipt Q&amp;A"]
  node_blob["Receipt file storage<br/>[client.py]"]
end

subgraph group_data["Persistence and reports"]
  node_repository["Session and receipt repository<br/>[repository.py]"]
  node_mongodb[("MongoDB<br/>[client.py]")]
  node_report["Report assembly<br/>[builder.py]"]
  node_xlsx["Excel report output<br/>[xlsx_builder.py]"]
end

subgraph group_service["Service runtime"]
  node_app["FastAPI application<br/>[main.py]"]
  node_api["API router<br/>[router.py]"]
  node_health["Health endpoints<br/>[health.py]"]
end

node_user(("Telegram user"))
node_telegram(("Telegram API"))

node_user -->|"sends updates"| node_telegram
node_telegram -->|"posts webhook"| node_webhook
node_webhook -->|"validates then dispatches"| node_dispatch
node_dispatch -->|"routes user input"| node_pipeline
node_pipeline -->|"loads and saves state"| node_repository
node_repository -->|"reads and writes"| node_mongodb
node_pipeline -->|"submits and polls"| node_extractor
node_extractor -.->|"stores receipt files"| node_blob
node_pipeline -->|"normalizes extraction"| node_normalizer
node_normalizer -->|"uses country rules"| node_profiles
node_pipeline -->|"validates draft"| node_validator
node_validator -->|"builds questions"| node_questions
node_pipeline -->|"interprets replies"| node_interpreter
node_pipeline -->|"answers receipt queries"| node_answer
node_pipeline -->|"renders user replies"| node_render
node_pipeline -->|"sends replies"| node_tgclient
node_tgclient -->|"calls Bot API"| node_telegram
node_pipeline -->|"builds date-range reports"| node_report
node_report -->|"loads categorized receipts"| node_repository
node_report -->|"creates spreadsheet output"| node_xlsx
node_app -->|"mounts router"| node_api
node_app -->|"mounts health routes"| node_health
node_api -->|"mounts webhook router"| node_webhook

click node_webhook "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/routes.py"
click node_dispatch "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/dispatch.py"
click node_tgclient "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/client.py"
click node_pipeline "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/engine.py"
click node_models "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/receipts/models.py"
click node_normalizer "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/normalizer.py"
click node_validator "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/validator.py"
click node_questions "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/questions.py"
click node_render "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/render.py"
click node_profiles "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/countries/registry.py"
click node_extractor "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/llamaextract_extractor.py"
click node_interpreter "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/openai_interpreter.py"
click node_answer "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/openai_answer_agent.py"
click node_blob "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/blob_storage/client.py"
click node_repository "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/sessions/repository.py"
click node_mongodb "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/db/mongodb/client.py"
click node_report "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/reports/builder.py"
click node_xlsx "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/reports/xlsx_builder.py"
click node_app "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/main.py"
click node_api "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/api/router.py"
click node_health "https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/health.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_webhook,node_dispatch,node_tgclient,node_user toneBlue
class node_pipeline,node_models,node_normalizer,node_validator,node_questions,node_render,node_profiles toneAmber
class node_extractor,node_interpreter,node_answer,node_blob,node_telegram toneMint
class node_repository,node_mongodb,node_report,node_xlsx toneRose
class node_app,node_api,node_health toneIndigo
```

## Components

### Telegram ingress

- [Webhook validation](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/routes.py): `receipt_parser_backend/telegram/routes.py`
- [Update dispatch](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/dispatch.py): `receipt_parser_backend/telegram/dispatch.py`
- [Telegram client](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/telegram/client.py): `receipt_parser_backend/telegram/client.py`

### Receipt workflow

- [Receipt state machine](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/engine.py): `receipt_parser_backend/pipeline/engine.py`
- [Receipt models](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/receipts/models.py): `receipt_parser_backend/receipts/models.py`
- [Extraction normalization](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/normalizer.py): `receipt_parser_backend/pipeline/normalizer.py`
- [Draft validation](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/validator.py): `receipt_parser_backend/pipeline/validator.py`
- [Follow-up questions](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/questions.py): `receipt_parser_backend/pipeline/questions.py`
- [Draft and reply rendering](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/pipeline/render.py): `receipt_parser_backend/pipeline/render.py`
- [Country profiles](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/countries/registry.py): `receipt_parser_backend/countries/registry.py`

### AI and file services

- [Receipt extraction](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/llamaextract_extractor.py): `receipt_parser_backend/ai/llamaextract_extractor.py`
- [Reply interpretation](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/openai_interpreter.py): `receipt_parser_backend/ai/openai_interpreter.py`
- [Receipt Q&A](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/ai/openai_answer_agent.py): `receipt_parser_backend/ai/openai_answer_agent.py`
- [Receipt file storage](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/blob_storage/client.py): `receipt_parser_backend/blob_storage/client.py`

### Persistence and reports

- [Session and receipt repository](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/sessions/repository.py): `receipt_parser_backend/sessions/repository.py`
- [MongoDB](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/db/mongodb/client.py): `receipt_parser_backend/db/mongodb/client.py`
- [Report assembly](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/reports/builder.py): `receipt_parser_backend/reports/builder.py`
- [Excel report output](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/reports/xlsx_builder.py): `receipt_parser_backend/reports/xlsx_builder.py`

### Service runtime

- [FastAPI application](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/main.py): `receipt_parser_backend/main.py`
- [API router](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/api/router.py): `receipt_parser_backend/api/router.py`
- [Health endpoints](https://github.com/adtimokhin/ai-receipt-parser/blob/main/receipt_parser_backend/health.py): `receipt_parser_backend/health.py`

### Other components

- **Telegram user**
- **Telegram API**

## Connections

- Telegram user → Telegram API: sends updates
- Telegram API → Webhook validation: posts webhook
- Webhook validation → Update dispatch: validates then dispatches
- Update dispatch → Receipt state machine: routes user input
- Receipt state machine → Session and receipt repository: loads and saves state
- Session and receipt repository → MongoDB: reads and writes
- Receipt state machine → Receipt extraction: submits and polls
- Receipt extraction → Receipt file storage: stores receipt files
- Receipt state machine → Extraction normalization: normalizes extraction
- Extraction normalization → Country profiles: uses country rules
- Receipt state machine → Draft validation: validates draft
- Draft validation → Follow-up questions: builds questions
- Receipt state machine → Reply interpretation: interprets replies
- Receipt state machine → Receipt Q&A: answers receipt queries
- Receipt state machine → Draft and reply rendering: renders user replies
- Receipt state machine → Telegram client: sends replies
- Telegram client → Telegram API: calls Bot API
- Receipt state machine → Report assembly: builds date-range reports
- Report assembly → Session and receipt repository: loads categorized receipts
- Report assembly → Excel report output: creates spreadsheet output
- FastAPI application → API router: mounts router
- FastAPI application → Health endpoints: mounts health routes
- API router → Webhook validation: mounts webhook router