# nutlope/receipthero architecture

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

- Interactive diagram: https://gitdiagram.com/nutlope/receipthero
- Repository: https://github.com/nutlope/receipthero

## Overview

##### Project type and purpose
- This is a full-stack, single-page Next.js application (using the Next.js App Router) that provides a receipt management UI and a minimal backend API endpoint for OCR.
- Purpose: allow users to upload receipt images, send them to an AI OCR service (Together AI + Llama 4 Scout 17B), extract structured receipt data, categorize expenses, and display/manage receipts in the browser (stored locally for privacy).

##### File structure
- Top level:
- app/ – Next.js App Router pages and API routes
- components/ – React UI components for the pages
- ui/ – low-level UI building blocks (shadcn/ui + Radix)
- lib/ – client wrappers, constants, types, hooks, utilities
- public/ – static assets (images)
- config & build files: next.config.ts, tsconfig.json, postcss.config.mjs, package.json
- app/api/ocr/route.ts implements the OCR API endpoint that calls Together AI’s OCR service.
- app/page.tsx & other app files render the pages and layout, importing components and hooks.

##### README for additional insights
- Tech stack: Next.js, Tailwind CSS, Together AI (OCR API), Llama 4 Scout 17B, shadcn/ui (Radix), Zod
- Flow: upload → OCR API call → parse structured data → categorize → display/manage → local browser storage

##### Main components & interactions
a. Components:
- Browser UI (Next.js React pages + shadcn/ui components)
- Next.js API route (app/api/ocr/route.ts)
- OCR External Service (Together AI invoking Llama 4 Scout 17B)
- Data processing layer in `lib/` (hooks, utils, data validation with Zod)
- Local storage (browser localStorage or indexedDB via `useReceiptManager`)
b. Data flow:
1. User uploads receipt images in the browser UI.
2. Frontend calls `/api/ocr` endpoint.
3. Next.js API route forwards image data to Together AI OCR service.
4. OCR service returns raw text/JSON; Next.js route returns it to frontend.
5. Frontend processes response via `lib/utils.ts`, validates with Zod, categorizes expenses.
6. Receipt data is stored locally (in browser) and rendered in tables, dialogs, and charts.
c. Architectural patterns & principles:
- Layered architecture: UI layer → API layer → external service → utilities/data layer
- Client-driven state management stored locally for privacy
- Separation of concerns: UI components (components/* & ui/*), data logic (lib/*), API route (app/api)
d. Key technologies:
- Next.js App Router (app/)
- Tailwind CSS (app/globals.css + postcss)
- shadcn/ui + Radix (ui/)
- Together AI OCR + Llama 4 Scout 17B
- Zod for schema validation
- pnpm workspace setup

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Zone A: Frontend UI
    subgraph "ReceiptHero UI" 
        direction TB
        UI_Page["app/page.tsx<br/>(Main Entry Page)"]:::ui
        UI_Layout["app/layout.tsx<br/>(Layout)"]:::ui
        UI_Styles["app/globals.css<br/>(Global Styles)"]:::ui
        UploadPage["components/UploadReceiptPage.tsx"]:::ui
        ResultsPage["components/ResultsPage.tsx"]:::ui
        DetailsDialog["components/ReceiptDetailsDialog.tsx"]:::ui
        Sidebar["components/SidebarReceipts.tsx"]:::ui
        TableView["components/TableReceipts.tsx"]:::ui
        Header["components/Header.tsx"]:::ui
        Footer["components/Footer.tsx"]:::ui
        subgraph "Low-level UI Primitives" 
            direction TB
            Button["ui/button.tsx"]:::ui
            Card["ui/card.tsx"]:::ui
            Tooltip["ui/tooltip.tsx"]:::ui
            Toast["ui/toast.tsx"]:::ui
        end
    end

    %% Zone B: API Layer
    subgraph "Backend / API" 
        direction TB
        API_OCR["/api/ocr<br/>(app/api/ocr/route.ts)"]:::api
    end

    %% Zone C: External Service
    subgraph "External Service" 
        direction TB
        OCR_Service["Together AI OCR Service<br/>(Llama 4 Scout 17B)"]:::external
    end

    %% Zone D: Lib Layer
    subgraph "Data Processing & State Management (lib/)" 
        direction TB
        ClientWrapper["lib/client.ts<br/>(OCR Client)"]:::lib
        Utils["lib/utils.ts"]:::lib
        Types["lib/types.ts"]:::lib
        Consts["lib/constant.ts"]:::lib
        CurrencyFmt["lib/currency.ts"]:::lib
        UseManager["lib/useReceiptManager.ts"]:::lib
    end

    %% Zone E: Storage
    LocalStorage["Browser LocalStorage / IndexedDB"]:::storage

    %% Data Flow
    UI_Page -->|1. upload image payload| API_OCR
    UploadPage --> API_OCR
    API_OCR -->|2. forward to| OCR_Service
    OCR_Service -->|3. return OCR data| API_OCR
    API_OCR -->|4. return structured data| ResultsPage
    ResultsPage -->|5. process & validate| Utils
    Utils -->|validate w/ Zod| Types
    Utils -->|use constants| Consts
    Utils -->|format currency| CurrencyFmt
    ResultsPage -->|store receipts| UseManager
    UseManager -->|persist| LocalStorage
    Sidebar -->|read receipts| UseManager
    TableView -->|read receipts| UseManager
    DetailsDialog -->|read receipt| UseManager

    %% Click Events
    click UI_Page "https://github.com/nutlope/receipthero/blob/main/app/page.tsx"
    click UI_Layout "https://github.com/nutlope/receipthero/blob/main/app/layout.tsx"
    click UI_Styles "https://github.com/nutlope/receipthero/blob/main/app/globals.css"
    click UploadPage "https://github.com/nutlope/receipthero/blob/main/components/UploadReceiptPage.tsx"
    click ResultsPage "https://github.com/nutlope/receipthero/blob/main/components/ResultsPage.tsx"
    click DetailsDialog "https://github.com/nutlope/receipthero/blob/main/components/ReceiptDetailsDialog.tsx"
    click Sidebar "https://github.com/nutlope/receipthero/blob/main/components/SidebarReceipts.tsx"
    click TableView "https://github.com/nutlope/receipthero/blob/main/components/TableReceipts.tsx"
    click Header "https://github.com/nutlope/receipthero/blob/main/components/Header.tsx"
    click Footer "https://github.com/nutlope/receipthero/blob/main/components/Footer.tsx"
    click Button "https://github.com/nutlope/receipthero/blob/main/ui/button.tsx"
    click Card "https://github.com/nutlope/receipthero/blob/main/ui/card.tsx"
    click Tooltip "https://github.com/nutlope/receipthero/blob/main/ui/tooltip.tsx"
    click Toast "https://github.com/nutlope/receipthero/blob/main/ui/toast.tsx"
    click API_OCR "https://github.com/nutlope/receipthero/blob/main/app/api/ocr/route.ts"
    click ClientWrapper "https://github.com/nutlope/receipthero/blob/main/lib/client.ts"
    click Utils "https://github.com/nutlope/receipthero/blob/main/lib/utils.ts"
    click Types "https://github.com/nutlope/receipthero/blob/main/lib/types.ts"
    click Consts "https://github.com/nutlope/receipthero/blob/main/lib/constant.ts"
    click CurrencyFmt "https://github.com/nutlope/receipthero/blob/main/lib/currency.ts"
    click UseManager "https://github.com/nutlope/receipthero/blob/main/lib/useReceiptManager.ts"

    %% Styles
    classDef ui fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef api fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef lib fill:#E6E6FA,stroke:#000,stroke-width:1px
    classDef storage fill:#D3D3D3,stroke:#000,stroke-width:1px
```
