Receipt Wrangler

Receipt Wrangler is a self‑hosted backend for receipt management, built as an API service that powers the web and mobile frontends. From a developer’s perspective it is essentially a micro‑service that exposes RESTful endpoints for uploading, processing, and querying receipts. The core logic is split into three layers: an ingestion layer that accepts files or emails, a processing pipeline that runs OCR and AI models to extract structured data, and a persistence layer that stores receipts, users, groups, and split calculations in a relational database. The API is documented via OpenAPI/Swagger, making it easy to generate SDKs in any language.

Architecture & Technical Stack

The application follows a clean architecture approach: the domain models (Receipt, User, Group) are decoupled from framework concerns, allowing unit tests to run without a running database. The async nature of FastAPI and the use of asyncpg for PostgreSQL connection pooling gives the service high throughput, suitable for dozens of concurrent users.

Core Capabilities & APIs

• Receipt Upload – POST /receipts/ accepts multipart form data (image or PDF) and returns a receipt ID.
• OCR & Extraction – Background task processes the file, stores raw OCR text and structured fields (date, total, items).
• Email Hook – POST /email/webhook/ can be configured on an IMAP server to automatically trigger receipt ingestion from incoming mail.
• User & Group Management – CRUD endpoints for users, roles, and group membership; JWT‑based authentication.
• Splitting Logic – POST /groups/{id}/split calculates equitable shares, generates receipts, and returns a share manifest.
• Webhooks – Developers can subscribe to events (receipt created, split finalized) via POST /webhook/subscriptions.
• Health & Metrics – /health, /metrics expose readiness and Prometheus metrics for observability.

All endpoints return JSON, and the API adheres to HATEOAS principles where applicable, making it straightforward for client libraries to navigate resources.

Deployment & Infrastructure

Receipt Wrangler is designed to run in a Docker container, but can also be deployed on any platform that supports Python 3.11 and PostgreSQL. The docker-compose.yml file bundles:

1. api – the FastAPI service
2. db – PostgreSQL container with volume persistence
3. maildev – optional local SMTP server for testing email ingestion

For production, the recommended stack includes:

• Kubernetes – Helm chart (not yet available) could be built from the existing Dockerfiles.
• CI/CD – GitHub Actions build image, run tests, push to GHCR; automated rollback on test failures.
• Scaling – The API is stateless, so horizontal scaling is trivial; a shared Redis cache can be added for rate limiting or background job queues if needed.

Integration & Extensibility

The project exposes a well‑defined OpenAPI spec, enabling developers to generate SDKs for JavaScript, Go, or any language that supports Swagger. Customization is possible via:

• Plugin Hooks – The ingestion pipeline accepts custom processors; implement a new class that inherits from BaseProcessor and register it in the config.
• Webhook Endpoints – External services can listen to receipt events and trigger workflows (e.g., ledger posting, accounting integration).
• Database Migration – Alembic scripts can be extended to add new tables or fields without breaking existing deployments.
• Configuration – YAML/JSON config files control OCR thresholds, email server settings, and feature toggles; environment variables override defaults for CI/CD pipelines.

Developer Experience

The codebase follows PEP‑8 conventions, and the documentation is split into a public website (receiptwrangler.io) and an internal developer portal. The API docs are auto‑generated, with example requests and responses. Community support is active on GitHub Discussions, where contributors discuss feature requests and bug reports. The AGPL license ensures that any modifications remain open source, fostering a collaborative ecosystem.

Use Cases

1. Small Business Expense Tracking – A developer can deploy the stack behind a corporate VPN, integrate with an internal email server, and expose a custom front‑end for employees to upload receipts.
2. Event Budgeting App – Using the group and split APIs, a developer can build an event planning tool that automatically splits shared costs among attendees.
3. Personal Finance Tool – For hobbyists, a single‑node Docker deployment on a Raspberry Pi can serve as a personal receipt vault with AI extraction.
4. Accounting Integration – By subscribing to webhooks, a developer can push extracted data into QuickBooks or X