How danciingqueen/autoreceipt works
Project Type and Purpose
• The project is a full-stack application designed to process image-based receipts. It extracts text through OCR, uses OpenAI GPT for structured text analysis, and then fills an Excel template automatically using Python (openpyxl). The overall aim is to automate the creation of personalized expense claim forms.
• Key technologies include FastAPI for backend services and Next.js (with Tailwind CSS) for the frontend.
File Structure
• Two main directories: “fastapi” (backend) and “next” (frontend).
• The FastAPI section holds the server-side logic (e.g., main.py) to receive file uploads and generate Excel files using a pre-stored Excel template located in assets.
• The Next.js directory contains folders like “src/app”, “src/components”, “src/hooks”, and “src/utils” which support the UI, custom hooks for functionalities (like image upload and receipt processing), and utility functions (e.g., analyze text with GPT, validate image size).
Main Components
a. Frontend (Next.js):
• UI Page (main interface) where users upload receipt images.
• Components (e.g., ReceiptCard) for displaying results.
• Custom hooks (e.g., useImageUpload, useProcessReceipts, useTemplateUpload) managing frontend business logic.
• Utility modules (e.g., for text analysis with GPT, image validation, exporting to Excel).
• Style frameworks (Tailwind CSS for UI and dark mode responsiveness).
b. Backend (FastAPI):
• The FastAPI server with at least one API endpoint (/export) that accepts metadata and images.
• Logic for handling file uploads, processing images, inserting images and data into the Excel template.
• Excel generation logic and configuration for image placements as detailed in the README.
• Handling of CORS settings to allow frontend requests from localhost:3000.
c. External/Supporting Services and Libraries:
• Tesseract.js for OCR processing on the client-side.
• OpenAI GPT for natural language processing and extracting structured fields from the receipt text.
• Python libraries: openpyxl for Excel file generation and manipulation.
Relationships and Interactions
• Data Flow: The user uploads an image via the Next.js frontend, where Tesseract.js first performs OCR. Extracted text is parsed using GPT APIs to get structured fields.
• Interaction: Once the processed data is available, the sorted receipts (with metadata and images) are packaged into a FormData payload.
• API Call: The frontend makes a POST request to the FastAPI endpoint (/export), sending image files and JSON metadata.
• Backend Processing: FastAPI receives the data, uses the pre-stored Excel template to insert images and relevant data into the correct cells based on the fixed layout, and then returns the Excel file (as a blob) for download.
Architectural Patterns & Important Design Principles
• Separation of Concerns: Frontend and backend responsibilities are clearly delineated. The frontend handles UI, user interaction, and preliminary processing (OCR and GPT calls), while the backend focuses solely on Excel generation.
• Modular Design: Both “next” and “fastapi” directories are modular with components, hooks, and utility functions, allowing for easier maintenance and future expansions such as adding new processing features.
• RESTful Communication: The communication between client and server via HTTP POST requests, following a REST-like approach.
• Template-Based Processing: The backend uses a fixed Excel template (with defined image and data cell positions) to generate output consistently.