How nutlope/receipthero works
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