# fayrd/receipt_logging_backend architecture

> Architecture diagram of the GitHub repository fayrd/receipt_logging_backend, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fayrd/receipt_logging_backend
- Repository: https://github.com/fayrd/receipt_logging_backend

## Overview

Receipt Logger is a FastAPI backend for mobile receipt capture and financial assistance. Its main workflow authenticates a user or device, accepts receipt images, queues batch scans, extracts validated receipt data with AI, and exposes stored receipts and progress to clients. Separate API branches handle chat, accounts, devices, subscriptions, and deletion. The README documents Redis-backed processing and provider options; unsampled modules are represented at their exact tree paths, with only documented relationships shown. External providers are shown as integrations, not inspected implementations.

Main entry points: [`src/Auth/identity.py`](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Auth/identity.py) (Session identity), [`main.py`](https://github.com/fayrd/receipt_logging_backend/blob/develop/main.py) (FastAPI app), [`src/API/v1/scan.py`](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/scan.py) (Scan endpoints), [`src/API/v1/chat.py`](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/chat.py) (Chat endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API workflows"]
  node_app["FastAPI app<br/>[main.py]"]
  node_scan["Scan endpoints<br/>[scan.py]"]
  node_receipts_api["Receipt endpoints<br/>[receipts.py]"]
  node_chat_api["Chat endpoints<br/>[chat.py]"]
  node_user_api["User endpoints<br/>[user.py]"]
  node_device_api["Device endpoints<br/>[devices.py]"]
  node_subscriptions["Subscriptions API<br/>[subscriptions.py]"]
  node_deletion["Deletion workflow<br/>[deletion.py]"]
  node_health["Health diagnostics<br/>[health.py]"]
end

subgraph group_domain["Domain services"]
  node_queue["Batch worker<br/>[queue_worker.py]"]
  node_extract["AI extraction"]
  node_image["Image handling<br/>[image_service.py]"]
  node_schemas["Validated schemas<br/>[schemas.py]"]
  node_chat_service["RAG chat service<br/>[chat_service.py]"]
  node_quota["Quota service<br/>[quota_service.py]"]
end

subgraph group_storage["Persistence and security"]
  node_identity["Session identity<br/>[identity.py]"]
  node_receipt_repo["Receipt repository"]
  node_user_repo["User repository<br/>[user_repository.py]"]
  node_device_repo["Device repository"]
  node_rate["Rate limiting<br/>[rate_limiter.py]"]
  node_dbclient["Supabase client<br/>[database.py]"]
end

subgraph group_integrations["External systems"]
  node_redis[("Redis jobs and OTP")]
  node_supabase[("Supabase PostgreSQL")]
  node_ai{{"AI providers"}}
  node_email["Email delivery<br/>[email_service.py]"]
end

node_client(("Mobile client"))

node_client -->|"sends requests"| node_app
node_app -->|"mounts routes"| node_scan
node_app -->|"mounts routes"| node_receipts_api
node_app -->|"mounts routes"| node_chat_api
node_app -->|"mounts routes"| node_user_api
node_app -->|"mounts routes"| node_device_api
node_app -->|"mounts routes"| node_health
node_scan -->|"resolves caller"| node_identity
node_receipts_api -->|"resolves caller"| node_identity
node_chat_api -->|"resolves caller"| node_identity
node_user_api -->|"resolves caller"| node_identity
node_device_api -->|"resolves caller"| node_identity
node_scan -->|"enqueues batch"| node_queue
node_queue -->|"stores job state"| node_redis
node_queue -->|"processes images"| node_extract
node_scan -->|"parses image"| node_extract
node_extract -->|"requests extraction"| node_ai
node_extract -->|"validates output"| node_schemas
node_scan -->|"handles uploads"| node_image
node_scan -->|"checks limits"| node_rate
node_scan -->|"checks quota"| node_quota
node_receipts_api -->|"reads and writes"| node_receipt_repo
node_receipts_api -->|"handles images"| node_image
node_chat_api -->|"runs queries"| node_chat_service
node_chat_api -->|"loads receipts"| node_receipt_repo
node_chat_service -->|"requests responses"| node_ai
node_chat_api -->|"checks limits"| node_rate
node_chat_api -->|"checks quota"| node_quota
node_user_api -->|"manages accounts"| node_user_repo
node_user_api -->|"checks limits"| node_rate
node_user_api -->|"sends messages"| node_email
node_device_api -->|"manages devices"| node_device_repo
node_device_api -->|"loads account"| node_user_repo
node_device_api -->|"checks limits"| node_rate
node_subscriptions -->|"resolves caller"| node_identity
node_subscriptions -->|"loads account"| node_user_repo
node_deletion -->|"sends notices"| node_email
node_dbclient -->|"creates client"| node_supabase
node_identity -->|"looks up device"| node_device_repo
node_identity -->|"looks up user"| node_user_repo

click node_app "https://github.com/fayrd/receipt_logging_backend/blob/develop/main.py"
click node_identity "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Auth/identity.py"
click node_scan "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/scan.py"
click node_queue "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Queue/queue_worker.py"
click node_extract "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/extraction_service.py"
click node_image "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/image_service.py"
click node_schemas "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/schemas.py"
click node_receipts_api "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/receipts.py"
click node_receipt_repo "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Receipts/receipt_repository.py"
click node_chat_api "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/chat.py"
click node_chat_service "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/chat_service.py"
click node_user_api "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/user.py"
click node_device_api "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/devices.py"
click node_user_repo "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Users/user_repository.py"
click node_device_repo "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Devices/device_repository.py"
click node_rate "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Auth/rate_limiter.py"
click node_quota "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/quota_service.py"
click node_subscriptions "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/subscriptions.py"
click node_deletion "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/web/deletion.py"
click node_dbclient "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Infrastructure/database.py"
click node_email "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/email_service.py"
click node_health "https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/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_app,node_scan,node_receipts_api,node_chat_api,node_user_api,node_device_api,node_subscriptions,node_deletion,node_health,node_client toneBlue
class node_queue,node_extract,node_image,node_schemas,node_chat_service,node_quota toneAmber
class node_identity,node_receipt_repo,node_user_repo,node_device_repo,node_rate,node_dbclient toneMint
class node_redis,node_supabase,node_ai,node_email toneRose
```

## Components

### API workflows

- [FastAPI app](https://github.com/fayrd/receipt_logging_backend/blob/develop/main.py): `main.py`
- [Scan endpoints](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/scan.py): `src/API/v1/scan.py`
- [Receipt endpoints](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/receipts.py): `src/API/v1/receipts.py`
- [Chat endpoints](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/chat.py): `src/API/v1/chat.py`
- [User endpoints](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/user.py): `src/API/v1/user.py`
- [Device endpoints](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/devices.py): `src/API/v1/devices.py`
- [Subscriptions API](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/subscriptions.py): `src/API/v1/subscriptions.py`
- [Deletion workflow](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/web/deletion.py): `src/API/web/deletion.py`
- [Health diagnostics](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/API/v1/health.py): `src/API/v1/health.py`

### Domain services

- [Batch worker](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Queue/queue_worker.py): `src/Queue/queue_worker.py`
- [AI extraction](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/extraction_service.py): `src/Services/extraction_service.py`
- [Image handling](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/image_service.py): `src/Services/image_service.py`
- [Validated schemas](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/schemas.py): `src/Models/schemas.py`
- [RAG chat service](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/chat_service.py): `src/Services/chat_service.py`
- [Quota service](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/quota_service.py): `src/Services/quota_service.py`

### Persistence and security

- [Session identity](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Auth/identity.py): `src/Auth/identity.py`
- [Receipt repository](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Receipts/receipt_repository.py): `src/Models/Receipts/receipt_repository.py`
- [User repository](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Users/user_repository.py): `src/Models/Users/user_repository.py`
- [Device repository](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Models/Devices/device_repository.py): `src/Models/Devices/device_repository.py`
- [Rate limiting](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Auth/rate_limiter.py): `src/Auth/rate_limiter.py`
- [Supabase client](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Infrastructure/database.py): `src/Infrastructure/database.py`

### External systems

- **Redis jobs and OTP**
- **Supabase PostgreSQL**
- **AI providers**
- [Email delivery](https://github.com/fayrd/receipt_logging_backend/blob/develop/src/Services/email_service.py): `src/Services/email_service.py`

### Other components

- **Mobile client**

## Connections

- Mobile client → FastAPI app: sends requests
- FastAPI app → Scan endpoints: mounts routes (evidence: `main.py`)
- FastAPI app → Receipt endpoints: mounts routes (evidence: `main.py`)
- FastAPI app → Chat endpoints: mounts routes (evidence: `main.py`)
- FastAPI app → User endpoints: mounts routes (evidence: `main.py`)
- FastAPI app → Device endpoints: mounts routes (evidence: `main.py`)
- FastAPI app → Health diagnostics: mounts routes (evidence: `main.py`)
- Scan endpoints → Session identity: resolves caller (evidence: `src/API/v1/scan.py`)
- Receipt endpoints → Session identity: resolves caller (evidence: `src/API/v1/receipts.py`)
- Chat endpoints → Session identity: resolves caller (evidence: `src/API/v1/chat.py`)
- User endpoints → Session identity: resolves caller (evidence: `src/API/v1/user.py`)
- Device endpoints → Session identity: resolves caller (evidence: `src/API/v1/devices.py`)
- Scan endpoints → Batch worker: enqueues batch
- Batch worker → Redis jobs and OTP: stores job state
- Batch worker → AI extraction: processes images (evidence: `src/Queue/queue_worker.py`)
- Scan endpoints → AI extraction: parses image (evidence: `src/API/v1/scan.py`)
- AI extraction → AI providers: requests extraction
- AI extraction → Validated schemas: validates output (evidence: `src/Services/extraction_service.py`)
- Scan endpoints → Image handling: handles uploads (evidence: `src/API/v1/scan.py`)
- Scan endpoints → Rate limiting: checks limits (evidence: `src/API/v1/scan.py`)
- Scan endpoints → Quota service: checks quota (evidence: `src/API/v1/scan.py`)
- Receipt endpoints → Receipt repository: reads and writes (evidence: `src/API/v1/receipts.py`)
- Receipt endpoints → Image handling: handles images (evidence: `src/API/v1/receipts.py`)
- Chat endpoints → RAG chat service: runs queries (evidence: `src/API/v1/chat.py`)
- Chat endpoints → Receipt repository: loads receipts
- RAG chat service → AI providers: requests responses
- Chat endpoints → Rate limiting: checks limits (evidence: `src/API/v1/chat.py`)
- Chat endpoints → Quota service: checks quota (evidence: `src/API/v1/chat.py`)
- User endpoints → User repository: manages accounts (evidence: `src/API/v1/user.py`)
- User endpoints → Rate limiting: checks limits (evidence: `src/API/v1/user.py`)
- User endpoints → Email delivery: sends messages (evidence: `src/API/v1/user.py`)
- Device endpoints → Device repository: manages devices (evidence: `src/API/v1/devices.py`)
- Device endpoints → User repository: loads account (evidence: `src/API/v1/devices.py`)
- Device endpoints → Rate limiting: checks limits (evidence: `src/API/v1/devices.py`)
- Subscriptions API → Session identity: resolves caller (evidence: `src/API/v1/subscriptions.py`)
- Subscriptions API → User repository: loads account (evidence: `src/API/v1/subscriptions.py`)
- Deletion workflow → Email delivery: sends notices (evidence: `src/API/web/deletion.py`)
- Supabase client → Supabase PostgreSQL: creates client (evidence: `src/Infrastructure/database.py`)
- Session identity → Device repository: looks up device (evidence: `src/Auth/identity.py`)
- Session identity → User repository: looks up user (evidence: `src/Auth/identity.py`)
