How adtimokhin/ai-receipt-parser works
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: engine.py Receipt state machine · builder.py Report assembly · routes.py Webhook validation · repository.py Session and receipt repository
Components 23
Telegram ingress
- Webhook validation
receipt_parser_backend/telegram/routes.py - Update dispatch
receipt_parser_backend/telegram/dispatch.py - Telegram client
receipt_parser_backend/telegram/client.py
Receipt workflow
- Receipt state machine
receipt_parser_backend/pipeline/engine.py - Receipt models
receipt_parser_backend/receipts/models.py - Extraction normalization
receipt_parser_backend/pipeline/normalizer.py - Draft validation
receipt_parser_backend/pipeline/validator.py - Follow-up questions
receipt_parser_backend/pipeline/questions.py - Draft and reply rendering
receipt_parser_backend/pipeline/render.py - Country profiles
receipt_parser_backend/countries/registry.py
AI and file services
- Receipt extraction
receipt_parser_backend/ai/llamaextract_extractor.py - Reply interpretation
receipt_parser_backend/ai/openai_interpreter.py - Receipt Q&A
receipt_parser_backend/ai/openai_answer_agent.py - Receipt file storage
receipt_parser_backend/blob_storage/client.py
Persistence and reports
- Session and receipt repository
receipt_parser_backend/sessions/repository.py - MongoDB
receipt_parser_backend/db/mongodb/client.py - Report assembly
receipt_parser_backend/reports/builder.py - Excel report output
receipt_parser_backend/reports/xlsx_builder.py
Service runtime
- FastAPI application
receipt_parser_backend/main.py - API router
receipt_parser_backend/api/router.py - Health endpoints
receipt_parser_backend/health.py
Other components
- Telegram user
- Telegram API
Connections 23
- 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