TaxSnap - Receipt Management & Tax Documentation App

Developer: Allan Ilyasov Course Submission: iOS Development Project Date: December 2024

Project Overview

TaxSnap is a comprehensive iOS receipt management application that helps users digitize, organize, and export their receipts for tax purposes. The app leverages advanced OCR technology, AI-powered categorization, and cloud synchronization to provide a seamless receipt tracking experience.

---

Features Implemented

Core Functionality

• Receipt Scanning: Multi-page receipt scanning with Vision OCR
• Smart OCR: Automatic extraction of merchant, date, amounts (subtotal, tax, tip, total)
• AI Categorization: OpenAI embeddings with k-NN classification for automatic merchant categorization
• Multi-page Support: Scan and manage receipts with multiple pages
• Line Item Extraction: Detailed itemization of purchases

Organization

• Folders: Organize receipts into custom folders
• Tags: Multi-tag support for flexible organization
• Categories: Pre-defined tax categories (Meals, Travel, Office Supplies, etc.)
• Search: Full-text search across all receipt data
• Filters: Filter by category, tags, date range, amount

Data Management

• Core Data: Local-first data persistence
• CloudKit Sync: Automatic synchronization across devices
• Export Formats: CSV, Excel (XLSX), PDF, ZIP
• Export Filters: Export by tags, categories, and date ranges
• Multi-select: Batch operations on receipts

Security & Privacy

• Secure Enclave: Biometric authentication option
• Local Storage: Receipt images stored locally
• iCloud Backup: Optional cloud backup with user control

---

Technical Stack

Frameworks & Technologies

• SwiftUI: Modern declarative UI framework
• Core Data: Local database with CloudKit integration
• Vision Framework: Apple's OCR engine for text recognition
• OpenAI API: text-embedding-3-small model for semantic categorization
• PDFKit: PDF generation for exports
• ZIPFoundation: Archive creation for complete exports

Architecture

• MVVM Pattern: Model-View-ViewModel architecture
• Service Layer: Separated business logic (OCR, Export, Categorization)
• Core Data Stack: Managed object context with CloudKit sync

---

Prerequisites

Development Environment

• macOS: 13.0 (Ventura) or later
• Xcode: 15.0 or later
• iOS Target: iOS 17.0 or later
• Swift: 5.9 or later

Required Accounts

1. Apple Developer Account (for device testing and iCloud)
2. OpenAI API Account (for AI categorization)

---

Installation & Setup Instructions

Step 1: Clone/Extract the Project

cd /path/to/TaxSnap
open TaxSnap.xcodeproj

Step 2: Install Dependencies

This project uses Swift Package Manager (SPM). Dependencies will be automatically resolved by Xcode.

Required Packages:

• None (all frameworks are native Apple frameworks)

Note: If you see package resolution errors, go to File → Packages → Reset Package Caches in Xcode.

Step 3: Configure API Keys

OpenAI API Key Setup

1. Get an API key from OpenAI Platform
2. The app will prompt you to enter the API key on first launch
3. Navigate to Settings → OpenAI API Key to configure

Alternative: For testing without OpenAI, receipts will use fallback categorization (pattern-based).

Step 4: Configure iCloud (Optional but Recommended)

1. Open the project in Xcode
2. Select the TaxSnap target
3. Go to Signing & Capabilities
4. Change the Team to your Apple Developer account
5. Update the Bundle Identifier to something unique (e.g., com.yourname.TaxSnap)
6. Ensure iCloud capability is enabled with:
   • CloudKit
   • iCloud Documents

Step 5: Build and Run

1. Select a target device/simulator (iOS 17.0+)
2. Press Cmd + R or click the Play button
3. Allow camera and photo library permissions when prompted

---

Running the Application

Initial Launch

1. Welcome Screen: The app opens to the main receipt list
2. Add API Key (optional): Go to Settings → OpenAI API Key
3. Grant Permissions: Allow camera access for scanning

Basic Usage

Scanning a Receipt

1. Tap the "+" button
2. Choose "Scan Receipt"
3. Position the receipt and tap capture
4. Review extracted data and save

Organizing Receipts

1. Long-press a receipt to enter multi-select mode
2. Select multiple receipts
3. Choose "Move to Folder" or "Add Tags"

Exporting Receipts

1. Go to Settings → Export
2. Select export format (CSV, Excel, PDF, ZIP)
3. Filter by tags, categories, or date range
4. Tap Export and share

---

Project Structure

TaxSnap/
├── Models/                          # Core Data models
│   ├── Receipt+CoreDataClass.swift
│   ├── Folder+CoreDataClass.swift
│   └── TaxSnap.xcdatamodeld
├── Views/                           # SwiftUI views
│   ├── ReceiptListView.swift       # Main list
│   ├── ReceiptDetailView.swift     # Detail view
│   ├── ReceiptEditView.swift       # Edit interface
│   ├── ScannerView.swift           # Camera interface
│   └── SettingsView.swift          # Settings
├── ViewModels/                      # View models
│   ├── ReceiptViewModel.swift
│   └── ExportViewModel.swift
├── Services/                        # Business logic
│   ├── VisionOCRService.swift      # OCR engine
│   ├── OCRLineReconstructor.swift  # Layout-aware text grouping
│   ├── CategorizationService.swift # AI categorization
│   ├── ExportService.swift         # CSV/PDF/ZIP export
│   ├── ExcelExportService.swift    # Excel export
│   └── CoreDataStack.swift         # Database management
├── Resources/                       # Static resources
│   └── PreSeededMerchants.json     # Default merchant database
└── Assets.xcassets/                # Images and icons

---

Key Components Documentation

OCR System

VisionOCRService.swift

• Uses Apple Vision framework for text recognition
• Extracts merchant name, date, amounts, payment method
• Handles multi-field line parsing (when subtotal/tax/total appear together)
• Smart amount extraction with value-based sorting

OCRLineReconstructor.swift

• Spatial grouping algorithm for reconstructing logical text lines
• Vertical alignment detection (±0.015 threshold)
• Height-based filtering (minimum 0.008) to remove OCR noise
• Preserves small but important text (subtotal, tax fields)

AI Categorization

CategorizationService.swift

• OpenAI text-embedding-3-small model (1536 dimensions)
• k-Nearest Neighbors (k=5) classification
• Local embedding cache in Application Support
• 100+ pre-seeded merchants with embeddings
• Offline-capable once embeddings are cached

Export System

ExportService.swift

• IRS-compliant CSV format with image subfolder
• Professional PDF reports with receipt images
• Multi-page receipt support (up to 5 pages per receipt)
• Line item export support

ExcelExportService.swift

• Native XLSX generation using OOXML
• Embedded images with hyperlinks
• Formatted headers and currency cells
• Conditional line item columns

---

Testing the Application

Test Scenarios

1. Receipt Scanning

• Scan a restaurant receipt
• Verify extraction of: merchant, date, subtotal, tax, tip, total
• Check automatic categorization (should be "Meals & Entertainment")

2. Multi-page Receipts

• Scan a receipt, then add another page
• Verify both pages are linked
• Test PDF export includes all pages

3. Organization

• Create a folder called "Business Travel"
• Add tags: "Client Meeting", "Reimbursable"
• Move receipts into folder
• Apply tags to multiple receipts

4. Export

• Export receipts filtered by tag "Reimbursable"
• Export as Excel with images
• Verify images are embedded and line items are present

5. Search & Filter

• Search for merchant name
• Filter by date range
• Filter by category

---

Known Limitations & Requirements

API Requirements

• OpenAI API: Required for AI categorization of new merchants
  • Fallback: Pattern-based categorization works offline
  • Cost: ~$0.0001 per receipt (very low cost)

Internet Connectivity

• First Launch: Requires internet to generate embeddings for pre-seeded merchants
• New Merchants: Requires internet to categorize unknown merchants
• CloudKit Sync: Requires internet for cross-device synchronization
• Cached Merchants: Work completely offline

Device Requirements

• Camera: Required for receipt scanning
• Storage: ~50MB for app + variable for receipt images
• iOS Version: 17.0 or later

---

Troubleshooting

Build Errors

"No such module 'Vision'"

• Ensure deployment target is iOS 17.0+
• Clean build folder: Product → Clean Build Folder

Signing Error

• Update Bundle Identifier to be unique
• Select your development team in Signing & Capabilities

Runtime Issues

OCR Not Detecting Text

• Ensure good lighting
• Receipt should be flat and in focus
• Try portrait orientation

Categorization Not Working

• Check OpenAI API key in Settings
• Verify internet connection (for new merchants)
• Check API key has sufficient credits

CloudKit Sync Not Working

• Ensure iCloud is enabled in device Settings
• Check that user is signed into iCloud
• Verify iCloud capability is properly configured

---

API Keys & Credentials

OpenAI API Setup

1. Create Account: https://platform.openai.com/signup
2. Get API Key: https://platform.openai.com/api-keys
3. Add Credits: OpenAI requires prepaid credits (~$5 minimum)
4. Expected Cost: Very low - approximately $0.0001 per receipt

Test API Key (Not Recommended for Production):

sk-proj-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

iCloud Setup

• Free Account: Apple ID with iCloud enabled
• No API Key Required: Uses device's signed-in iCloud account
• Storage: Uses user's iCloud storage quota

---

Submission Checklist

• Source code (complete Xcode project)
• Source code documentation (inline comments + this README)
• Instructions to run the code (see Installation & Setup)
• List of required libraries/APIs/tools (see Prerequisites & Technical Stack)
• API key configuration guide (see API Keys & Credentials)

---

Additional Notes for Professor

Design Decisions

1. Local-First Architecture: Receipts are stored locally first, then synced to iCloud. This ensures the app works offline and provides fast performance.

2. OCR Line Reconstruction: Implemented a custom spatial grouping algorithm because Vision OCR returns unordered text blocks. The algorithm groups text by vertical alignment to reconstruct logical receipt lines.

3. Smart Amount Extraction: When multiple financial fields (subtotal, tax, total) appear on the same line, the app uses value-based sorting (largest = total, second-largest = subtotal, smallest = tax) with ratio validation.

4. Embedding Cache: OpenAI embeddings are cached locally to enable offline categorization for known merchants and reduce API costs.

5. Export Formats: Multiple export formats (CSV, Excel, PDF, ZIP) to support different use cases (accountants, tax software, personal records).

Implementation Highlights

• 86% Requirements Coverage: 59 out of 69 functional requirements implemented
• MVVM Architecture: Clean separation of concerns
• SwiftUI: Modern, declarative UI with smooth animations
• Core Data + CloudKit: Robust data persistence with cloud sync
• Vision Framework: Native OCR without third-party dependencies
• Secure Enclave: Optional biometric authentication

Future Enhancements (Not Implemented)

• Onboarding tutorial system
• Secure shareable links for receipts
• In-app help/FAQ section
• Receipt templates for manual entry
• Expense reporting with approval workflows

---

Contact & Support

Developer: Allan Ilyasov Project: TaxSnap - iOS Receipt Management App Submission Date: December 2024

For questions about the implementation, please refer to inline code documentation or contact via course communication channels.

---

License

This project is submitted as part of coursework. All rights reserved by the author.