# danciingqueen/autoreceipt architecture

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

- Interactive diagram: https://gitdiagram.com/danciingqueen/autoreceipt
- Repository: https://github.com/danciingqueen/autoreceipt

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Subgraph
    subgraph "Frontend (Next.js)"
        FE_UI("Receipt Upload Interface"):::frontend
        FE_RC("Receipt Display Component"):::frontend
        FE_UIH("useImageUpload"):::frontend
        FE_PR("useProcessReceipts"):::frontend
        FE_TU("useTemplateUpload"):::frontend
        FE_UTIL1("Analyze Text with GPT"):::utils
        FE_UTIL2("Export Data to Excel with Layout"):::utils
        FE_UTIL3("Validate Image Size"):::utils
        OCR("OCR Module (Tesseract.js)"):::external
        GPT("Text Analysis (OpenAI GPT)"):::external
    end

    %% Backend Subgraph
    subgraph "Backend (FastAPI)"
        BE("FastAPI /export Endpoint"):::backend
        EXCEL("Excel Generation (openpyxl)"):::backend
        TEMPLATE("Excel Template"):::backend
    end

    %% Frontend Interactions
    FE_UI -->|"initiatesUpload"| FE_UIH
    FE_UIH -->|"validate"| FE_UTIL3
    FE_UIH -->|"performOCR"| OCR
    OCR -->|"extractedText"| GPT
    GPT -->|"parsedData"| FE_UTIL1
    FE_UTIL1 -->|"processReceipts"| FE_PR
    FE_PR -->|"prepareExport"| FE_UTIL2
    FE_UI -->|"optionalTemplateUpload"| FE_TU
    FE_UTIL2 -->|"displayResults"| FE_RC

    %% Communication Between Frontend and Backend
    FE_UTIL2 -->|"POST_FormData"| BE
    BE -->|"triggerExcelGeneration"| EXCEL
    EXCEL -->|"useTemplate"| TEMPLATE
    BE -->|"returnExcelBlob"| FE_UI

    %% Click Events for Component Mappings
    click BE "https://github.com/danciingqueen/autoreceipt/blob/main/fastapi/main.py"
    click TEMPLATE "https://github.com/danciingqueen/autoreceipt/blob/main/fastapi/assets/template.xlsx"
    click FE_UI "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/app/page.js"
    click FE_RC "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/components/ReceiptCard.js"
    click FE_UIH "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/hooks/useImageUpload.js"
    click FE_PR "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/hooks/useProcessReceipts.js"
    click FE_TU "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/hooks/useTemplateUpload.js"
    click FE_UTIL1 "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/utils/analyzeTextWithGpt.js"
    click FE_UTIL2 "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/utils/exportToExcelWithLayout.js"
    click FE_UTIL3 "https://github.com/danciingqueen/autoreceipt/blob/main/next/src/utils/validateImageSize.js"

    %% Styling Classes
    classDef frontend fill:#bbf,stroke:#333,stroke-width:2px;
    classDef backend fill:#bfb,stroke:#333,stroke-width:2px;
    classDef external fill:#ffab91,stroke:#333,stroke-width:2px;
    classDef utils fill:#ffe082,stroke:#333,stroke-width:2px;
```
