feat: Receipt classifier and OCR integration (#149) #157

New Issue

egullickson · 2026-02-13T03:52:13Z

egullickson commented

2026-02-13 03:52:13 +00:00

Relates to #149

Scope

Create the receipt type classifier and integrate with existing OCR pipeline.

ReceiptClassifier

New module in domain/receipt-classifier.ts:

Classify receipt type from email subject + body text first
Fuel keywords: gas, fuel, gallons, octane, pump, diesel, unleaded, shell, chevron, exxon, bp
Maintenance keywords: oil change, brake, alignment, tire, rotation, inspection, labor, parts, service, repair, transmission, coolant
If classification confident (>= 2 keyword matches), use that type
If unclear from email text, perform general OCR and classify from rawText
If still unclear, mark as 'unclassified' for user review
Returns: { type: 'fuel' | 'maintenance' | 'unclassified', confidence: number }

OCR Integration

For fuel receipts: Call OcrService.extractReceipt(userId, {fileBuffer, contentType})
For maintenance receipts: Call OcrService.extractMaintenanceReceipt(userId, {fileBuffer, contentType})
For unclassified: Store document as pending, notify user
Reuse existing OCR pipeline - no changes to OCR service needed

Document Storage

Store each attachment as a document via DocumentsService.createDocument() + upload
Link document to created record via receipt_document_id

Files

backend/src/features/email-ingestion/domain/receipt-classifier.ts

Acceptance Criteria

Fuel receipts correctly classified from keywords
Maintenance receipts correctly classified from keywords
Unclear receipts marked as unclassified
OCR extraction called with correct endpoint per type
Attachments stored as documents

Relates to #149 ## Scope Create the receipt type classifier and integrate with existing OCR pipeline. ### ReceiptClassifier New module in `domain/receipt-classifier.ts`: - Classify receipt type from email subject + body text first - Fuel keywords: gas, fuel, gallons, octane, pump, diesel, unleaded, shell, chevron, exxon, bp - Maintenance keywords: oil change, brake, alignment, tire, rotation, inspection, labor, parts, service, repair, transmission, coolant - If classification confident (>= 2 keyword matches), use that type - If unclear from email text, perform general OCR and classify from rawText - If still unclear, mark as 'unclassified' for user review - Returns: { type: 'fuel' | 'maintenance' | 'unclassified', confidence: number } ### OCR Integration - For fuel receipts: Call `OcrService.extractReceipt(userId, {fileBuffer, contentType})` - For maintenance receipts: Call `OcrService.extractMaintenanceReceipt(userId, {fileBuffer, contentType})` - For unclassified: Store document as pending, notify user - Reuse existing OCR pipeline - no changes to OCR service needed ### Document Storage - Store each attachment as a document via `DocumentsService.createDocument()` + upload - Link document to created record via `receipt_document_id` ### Files - `backend/src/features/email-ingestion/domain/receipt-classifier.ts` ## Acceptance Criteria - [ ] Fuel receipts correctly classified from keywords - [ ] Maintenance receipts correctly classified from keywords - [ ] Unclear receipts marked as unclassified - [ ] OCR extraction called with correct endpoint per type - [ ] Attachments stored as documents

egullickson added the

labels 2026-02-13 03:52:48 +00:00

egullickson added this to the Sprint 2026-02-02 milestone 2026-02-13 03:52:58 +00:00

egullickson referenced this issue

2026-02-13 03:54:19 +00:00

feat: Email Receipt Ingestion via Resend Webhooks #149

egullickson added

and removed

labels 2026-02-13 14:39:02 +00:00

egullickson commented

2026-02-13 14:44:15 +00:00

Milestone: Receipt Classifier and OCR Integration

Phase: Execution | Agent: Feature Agent | Status: PASS

Completed

Created receipt-classifier.ts with keyword-based ReceiptClassifier class
Fuel keywords (11): gas, fuel, gallons, octane, pump, diesel, unleaded, shell, chevron, exxon, bp
Maintenance keywords (12): oil change, brake, alignment, tire, rotation, inspection, labor, parts, service, repair, transmission, coolant
Confidence threshold: >= 2 keyword matches for confident classification
Returns { type: 'fuel' | 'maintenance' | 'unclassified', confidence: number }

Integration

Integrated classifier into EmailIngestionService.processEmail() pipeline
Step 5: Classify from email subject + body text first
Step 6: If confident, call specific OCR endpoint (fuel or maintenance)
If confident endpoint fails, falls back to the other endpoint
If unclassified from email text, tries both OCR endpoints and classifies from rawText
Final fallback: domain-specific field and field-count heuristic

Files Changed

backend/src/features/email-ingestion/domain/receipt-classifier.ts (new)
backend/src/features/email-ingestion/domain/email-ingestion.service.ts (modified)
backend/src/features/email-ingestion/domain/email-ingestion.types.ts (modified)
backend/src/features/email-ingestion/index.ts (modified)

Quality

Lint: PASS (0 errors, 0 warnings)
Type-check: PASS

Verdict: PASS | Next: QR post-implementation review

## Milestone: Receipt Classifier and OCR Integration **Phase**: Execution | **Agent**: Feature Agent | **Status**: PASS ### Completed - Created `receipt-classifier.ts` with keyword-based `ReceiptClassifier` class - Fuel keywords (11): gas, fuel, gallons, octane, pump, diesel, unleaded, shell, chevron, exxon, bp - Maintenance keywords (12): oil change, brake, alignment, tire, rotation, inspection, labor, parts, service, repair, transmission, coolant - Confidence threshold: >= 2 keyword matches for confident classification - Returns `{ type: 'fuel' | 'maintenance' | 'unclassified', confidence: number }` ### Integration - Integrated classifier into `EmailIngestionService.processEmail()` pipeline - Step 5: Classify from email subject + body text first - Step 6: If confident, call specific OCR endpoint (fuel or maintenance) - If confident endpoint fails, falls back to the other endpoint - If unclassified from email text, tries both OCR endpoints and classifies from rawText - Final fallback: domain-specific field and field-count heuristic ### Files Changed - `backend/src/features/email-ingestion/domain/receipt-classifier.ts` (new) - `backend/src/features/email-ingestion/domain/email-ingestion.service.ts` (modified) - `backend/src/features/email-ingestion/domain/email-ingestion.types.ts` (modified) - `backend/src/features/email-ingestion/index.ts` (modified) ### Quality - Lint: PASS (0 errors, 0 warnings) - Type-check: PASS *Verdict*: PASS | *Next*: QR post-implementation review

egullickson referenced this issue from a commit

2026-02-13 16:34:29 +00:00

feat: add receipt classifier and OCR integration (refs #157)

egullickson referenced a pull request that will close this issue

2026-02-13 16:34:49 +00:00

feat: Maintenance Receipt Upload with OCR Auto-populate (#16) #161

egullickson closed this issue

2026-02-13 22:19:46 +00:00

Sign in to join this conversation.