# wilesses/receipt-intelligence architecture

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

- Interactive diagram: https://gitdiagram.com/wilesses/receipt-intelligence
- Repository: https://github.com/wilesses/receipt-intelligence

## Overview

Receipt Intelligence is a local Flask/SQLite application for turning grocery-receipt PDFs into reviewable spending data. Its main workflow imports a receipt, parses its items, normalizes product names, derives cautious price evidence, classifies purchases, and persists the result; users then explore analytics and product histories and resolve uncertain categories or product matches. The graph preserves the documented review, comparison, and data-quality capabilities. Some route details and UI wiring are unsampled, so those connections are shown only where excerpts, indexed references, or README statements support them.

Main entry points: [`app/web/routes.py`](https://github.com/wilesses/receipt-intelligence/blob/main/app/web/routes.py) (Routes and workflows), [`app/db.py`](https://github.com/wilesses/receipt-intelligence/blob/main/app/db.py) (Receipt database), [`app/importer.py`](https://github.com/wilesses/receipt-intelligence/blob/main/app/importer.py) (Receipt importer), [`app/price_deviation.py`](https://github.com/wilesses/receipt-intelligence/blob/main/app/price_deviation.py) (Price diagnostics)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Receipt ingestion"]
  node_importer["Receipt importer<br/>[importer.py]"]
  node_parser["Receipt parser<br/>[receipt_parser.py]"]
  node_gmail_fetcher["Email fetcher<br/>[gmail_fetcher.py]"]
  node_database[("Receipt database<br/>[db.py]")]
end

subgraph group_quality["Identity and quality"]
  node_normalizer["Product normalizer"]
  node_matcher["Product matcher<br/>[product_matcher.py]"]
  node_identity["Reporting identity"]
  node_categories["Category rules<br/>[category_rules.py]"]
  node_keywords["Category taxonomy"]
  node_prices["Price evidence model<br/>[price_model.py]"]
  node_correction["Price correction"]
end

subgraph group_insights["Analysis and review"]
  node_deviation["Price diagnostics<br/>[price_deviation.py]"]
  node_presentation["Diagnostic presentation"]
  node_analytics["Analytics service"]
  node_dashboard["Dashboard service"]
  node_comparison["Store comparison"]
end

subgraph group_app["Application interface"]
  node_web["Flask interface<br/>[app.py]"]
  node_routes["Routes and workflows<br/>[routes.py]"]
end

node_shopper(("Receipt user"))
node_pdfs["Receipt PDFs"]
node_gmail(("Gmail"))

node_shopper -->|"uses"| node_web
node_pdfs -->|"imports"| node_importer
node_shopper -->|"submits receipts"| node_routes
node_web -->|"registers routes"| node_routes
node_routes -->|"invokes import"| node_importer
node_importer -->|"parses receipt"| node_parser
node_importer -->|"persists items"| node_database
node_importer -->|"normalizes names"| node_normalizer
node_importer -->|"derives prices"| node_prices
node_parser -->|"categorizes items"| node_keywords
node_database -->|"normalizes names"| node_normalizer
node_database -->|"derives price data"| node_prices
node_database -->|"looks up rules"| node_categories
node_categories -->|"normalizes categories"| node_keywords
node_categories -->|"builds product keys"| node_normalizer
node_routes -->|"checks email receipts"| node_gmail_fetcher
node_gmail_fetcher -.->|"fetches messages"| node_gmail
node_routes -->|"reads and updates"| node_database
node_routes -->|"finds suggestions"| node_matcher
node_matcher -->|"normalizes candidates"| node_normalizer
node_matcher -->|"uses identity"| node_identity
node_routes -->|"handles correction"| node_correction
node_correction -->|"uses price model"| node_prices
node_routes -->|"evaluates prices"| node_deviation
node_deviation -->|"checks evidence"| node_prices
node_deviation -->|"groups observations"| node_identity
node_routes -->|"formats diagnostics"| node_presentation
node_presentation -->|"presents results"| node_deviation
node_routes -->|"requests analytics"| node_analytics
node_analytics -->|"queries data"| node_database
node_analytics -->|"uses diagnostics"| node_deviation
node_analytics -->|"uses identity"| node_identity
node_routes -->|"requests dashboard"| node_dashboard
node_dashboard -->|"queries data"| node_database
node_dashboard -->|"uses product matching"| node_matcher
node_dashboard -->|"uses identity"| node_identity
node_routes -->|"requests comparison"| node_comparison
node_comparison -->|"uses price evidence"| node_deviation

click node_web "https://github.com/wilesses/receipt-intelligence/blob/main/app/web/app.py"
click node_routes "https://github.com/wilesses/receipt-intelligence/blob/main/app/web/routes.py"
click node_importer "https://github.com/wilesses/receipt-intelligence/blob/main/app/importer.py"
click node_parser "https://github.com/wilesses/receipt-intelligence/blob/main/app/receipt_parser.py"
click node_gmail_fetcher "https://github.com/wilesses/receipt-intelligence/blob/main/app/gmail_fetcher.py"
click node_database "https://github.com/wilesses/receipt-intelligence/blob/main/app/db.py"
click node_normalizer "https://github.com/wilesses/receipt-intelligence/blob/main/app/product_normalizer.py"
click node_matcher "https://github.com/wilesses/receipt-intelligence/blob/main/app/product_matcher.py"
click node_identity "https://github.com/wilesses/receipt-intelligence/blob/main/app/product_identity.py"
click node_categories "https://github.com/wilesses/receipt-intelligence/blob/main/app/category_rules.py"
click node_keywords "https://github.com/wilesses/receipt-intelligence/blob/main/app/category_keywords.py"
click node_prices "https://github.com/wilesses/receipt-intelligence/blob/main/app/price_model.py"
click node_correction "https://github.com/wilesses/receipt-intelligence/blob/main/app/price_correction.py"
click node_deviation "https://github.com/wilesses/receipt-intelligence/blob/main/app/price_deviation.py"
click node_presentation "https://github.com/wilesses/receipt-intelligence/blob/main/app/price_deviation_presentation.py"
click node_analytics "https://github.com/wilesses/receipt-intelligence/blob/main/app/analytics_service.py"
click node_dashboard "https://github.com/wilesses/receipt-intelligence/blob/main/app/dashboard_service.py"
click node_comparison "https://github.com/wilesses/receipt-intelligence/blob/main/app/store_price_comparison.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_importer,node_parser,node_gmail_fetcher,node_database,node_shopper toneBlue
class node_normalizer,node_matcher,node_identity,node_categories,node_keywords,node_prices,node_correction toneAmber
class node_deviation,node_presentation,node_analytics,node_dashboard,node_comparison toneMint
class node_web,node_routes toneRose
class node_pdfs,node_gmail toneIndigo
```

## Components

### Receipt ingestion

- [Receipt importer](https://github.com/wilesses/receipt-intelligence/blob/main/app/importer.py): `app/importer.py`
- [Receipt parser](https://github.com/wilesses/receipt-intelligence/blob/main/app/receipt_parser.py): `app/receipt_parser.py`
- [Email fetcher](https://github.com/wilesses/receipt-intelligence/blob/main/app/gmail_fetcher.py): `app/gmail_fetcher.py`
- [Receipt database](https://github.com/wilesses/receipt-intelligence/blob/main/app/db.py): `app/db.py`

### Identity and quality

- [Product normalizer](https://github.com/wilesses/receipt-intelligence/blob/main/app/product_normalizer.py): `app/product_normalizer.py`
- [Product matcher](https://github.com/wilesses/receipt-intelligence/blob/main/app/product_matcher.py): `app/product_matcher.py`
- [Reporting identity](https://github.com/wilesses/receipt-intelligence/blob/main/app/product_identity.py): `app/product_identity.py`
- [Category rules](https://github.com/wilesses/receipt-intelligence/blob/main/app/category_rules.py): `app/category_rules.py`
- [Category taxonomy](https://github.com/wilesses/receipt-intelligence/blob/main/app/category_keywords.py): `app/category_keywords.py`
- [Price evidence model](https://github.com/wilesses/receipt-intelligence/blob/main/app/price_model.py): `app/price_model.py`
- [Price correction](https://github.com/wilesses/receipt-intelligence/blob/main/app/price_correction.py): `app/price_correction.py`

### Analysis and review

- [Price diagnostics](https://github.com/wilesses/receipt-intelligence/blob/main/app/price_deviation.py): `app/price_deviation.py`
- [Diagnostic presentation](https://github.com/wilesses/receipt-intelligence/blob/main/app/price_deviation_presentation.py): `app/price_deviation_presentation.py`
- [Analytics service](https://github.com/wilesses/receipt-intelligence/blob/main/app/analytics_service.py): `app/analytics_service.py`
- [Dashboard service](https://github.com/wilesses/receipt-intelligence/blob/main/app/dashboard_service.py): `app/dashboard_service.py`
- [Store comparison](https://github.com/wilesses/receipt-intelligence/blob/main/app/store_price_comparison.py): `app/store_price_comparison.py`

### Application interface

- [Flask interface](https://github.com/wilesses/receipt-intelligence/blob/main/app/web/app.py): `app/web/app.py`
- [Routes and workflows](https://github.com/wilesses/receipt-intelligence/blob/main/app/web/routes.py): `app/web/routes.py`

### Other components

- **Receipt user**
- **Receipt PDFs**
- **Gmail**

## Connections

- Receipt user → Flask interface: uses
- Receipt PDFs → Receipt importer: imports
- Receipt user → Routes and workflows: submits receipts
- Flask interface → Routes and workflows: registers routes (evidence: `app/web/app.py`)
- Routes and workflows → Receipt importer: invokes import (evidence: `app/web/routes.py`)
- Receipt importer → Receipt parser: parses receipt (evidence: `app/importer.py`)
- Receipt importer → Receipt database: persists items (evidence: `app/importer.py`)
- Receipt importer → Product normalizer: normalizes names (evidence: `app/importer.py`)
- Receipt importer → Price evidence model: derives prices (evidence: `app/importer.py`)
- Receipt parser → Category taxonomy: categorizes items (evidence: `app/receipt_parser.py`)
- Receipt database → Product normalizer: normalizes names (evidence: `app/db.py`)
- Receipt database → Price evidence model: derives price data (evidence: `app/db.py`)
- Receipt database → Category rules: looks up rules (evidence: `app/db.py`)
- Category rules → Category taxonomy: normalizes categories (evidence: `app/category_rules.py`)
- Category rules → Product normalizer: builds product keys (evidence: `app/category_rules.py`)
- Routes and workflows → Email fetcher: checks email receipts (evidence: `app/web/routes.py`)
- Email fetcher → Gmail: fetches messages
- Routes and workflows → Receipt database: reads and updates (evidence: `app/web/routes.py`)
- Routes and workflows → Product matcher: finds suggestions (evidence: `app/web/routes.py`)
- Product matcher → Product normalizer: normalizes candidates (evidence: `app/product_matcher.py`)
- Product matcher → Reporting identity: uses identity (evidence: `app/product_matcher.py`)
- Routes and workflows → Price correction: handles correction (evidence: `app/web/routes.py`)
- Price correction → Price evidence model: uses price model (evidence: `app/price_correction.py`)
- Routes and workflows → Price diagnostics: evaluates prices (evidence: `app/web/routes.py`)
- Price diagnostics → Price evidence model: checks evidence (evidence: `app/price_deviation.py`)
- Price diagnostics → Reporting identity: groups observations (evidence: `app/price_deviation.py`)
- Routes and workflows → Diagnostic presentation: formats diagnostics (evidence: `app/web/routes.py`)
- Diagnostic presentation → Price diagnostics: presents results (evidence: `app/price_deviation_presentation.py`)
- Routes and workflows → Analytics service: requests analytics (evidence: `app/web/routes.py`)
- Analytics service → Receipt database: queries data (evidence: `app/analytics_service.py`)
- Analytics service → Price diagnostics: uses diagnostics (evidence: `app/analytics_service.py`)
- Analytics service → Reporting identity: uses identity (evidence: `app/analytics_service.py`)
- Routes and workflows → Dashboard service: requests dashboard (evidence: `app/web/routes.py`)
- Dashboard service → Receipt database: queries data (evidence: `app/dashboard_service.py`)
- Dashboard service → Product matcher: uses product matching (evidence: `app/dashboard_service.py`)
- Dashboard service → Reporting identity: uses identity (evidence: `app/dashboard_service.py`)
- Routes and workflows → Store comparison: requests comparison (evidence: `app/web/routes.py`)
- Store comparison → Price diagnostics: uses price evidence (evidence: `app/store_price_comparison.py`)
