# meetmendapara09/snap2sheet architecture

> Architecture diagram of the GitHub repository meetmendapara09/snap2sheet, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/meetmendapara09/snap2sheet
- Repository: https://github.com/meetmendapara09/snap2sheet

## Overview

#### Purpose and Entry Points
SnapToSheet is a single-page Next.js application that converts an uploaded invoice image into structured accounting data and a downloadable Excel workbook. The browser entry is `src/app/page.tsx`, within the shared application shell at `src/app/layout.tsx`. The primary interactive workflow is implemented by `src/components/OcrToExcel.tsx`.

#### Client Extraction and Review Workflow
`src/components/OcrToExcel.tsx` owns the user-facing state machine: image selection, local preview, extraction request status/errors, structured-result preview, and workbook download. It sends an image Data URL to the server rather than exposing model credentials in the browser. It also hosts the resilience path: client-side Tesseract OCR can produce text for extraction when direct vision extraction is unavailable.

#### Server Extraction Boundary
`src/app/api/extract-invoice/route.ts` is the principal trust and integration boundary. It receives invoice content, uses the server-only `OPENROUTER_API_KEY`, and requests strict structured invoice JSON from OpenRouter’s `amazon/nova-2-lite-v1:free` vision model. The route supports image-first input and OCR-text input, insulating the UI from provider-specific prompting, response parsing, and API failures. `src/app/api/extract-invoice/debug/route.ts` is a separate diagnostic endpoint for examining this integration flow.

#### Invoice Normalization and Parsing
`src/lib/invoice-extractor.ts` defines or centralizes invoice extraction/normalization logic used around model output, including the structured domain expected by preview and export stages. `src/lib/ocr-text-parser.ts` supports the fallback path by interpreting OCR text into invoice-oriented fields. These library modules form the boundary between untrusted model/OCR output and the application’s normalized invoice representation.

#### Excel Export and Accounting Output
After extraction, `src/components/OcrToExcel.tsx` renders reviewable invoice data and generates the workbook client-side through `xlsx`. The export produces five accounting-oriented sheets: Invoice Summary, Line Items, Audit Trail, Accounting Entries, and Raw Data. This stage applies numeric formatting, calculated totals/formulas, GST fields, and total-verification information; no workbook needs to be persisted or generated by the server.

#### End-to-End Flow and Failure Handling
The normal path is: browser image upload → Data URL POST to `src/app/api/extract-invoice/route.ts` → OpenRouter vision inference → validated/normalized structured invoice result → browser preview → local Excel download. On vision failure or unsuitable input, `src/components/OcrToExcel.tsx` invokes Tesseract.js, then submits OCR text through the same extraction API path for structured interpretation. The principal boundaries are browser/server credential isolation, server/provider inference, and unstructured-to-structured normalization.

#### Runtime, Infrastructure, and External Services
The app runs on Node.js 18.18+ (20+ recommended) using Next.js 16 App Router and React 19. It is suitable for Vercel-style Next.js deployment, with `OPENROUTER_API_KEY` configured in deployment environment variables as indicated by `.env.example`. External dependencies with architectural impact are OpenRouter (remote vision-model access), Tesseract.js (browser-side OCR fallback), and `xlsx` (client-side workbook construction). The API key remains confined to `src/app/api/extract-invoice/route.ts`; the application has no indicated authentication or persistent server-side history.

Main entry points: [`src/app/api/extract-invoice/route.ts`](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/api/extract-invoice/route.ts) (Invoice extraction API), [`src/components/OcrToExcel.tsx`](https://github.com/meetmendapara09/snap2sheet/blob/main/src/components/OcrToExcel.tsx) (Extraction and review UI), [`src/lib/invoice-extractor.ts`](https://github.com/meetmendapara09/snap2sheet/blob/main/src/lib/invoice-extractor.ts) (Invoice normalization), [`src/app/page.tsx`](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/page.tsx) (Invoice page)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_browser["Browser app"]
  node_app_shell["App shell<br/>Next.js layout<br/>[layout.tsx]"]
  node_page["Invoice page<br/>Next.js page<br/>[page.tsx]"]
  node_ocr_ui["Extraction and review UI<br/>React workflow<br/>[OcrToExcel.tsx]"]
  node_tesseract{{"Tesseract OCR<br/>browser OCR"}}
  node_xlsx{{"xlsx<br/>workbook library"}}
  node_workbook["Excel workbook<br/>download"]
  node_invoice_result["Normalized invoice<br/>structured data"]
end

subgraph group_server["Next.js server"]
  node_extract_route["Invoice extraction API<br/>Next.js route<br/>[route.ts]"]
  node_debug_route["Extraction diagnostics API<br/>Next.js route<br/>[route.ts]"]
  node_invoice_normalizer["Invoice normalization<br/>domain library"]
  node_ocr_parser["OCR text parser<br/>parsing library<br/>[ocr-text-parser.ts]"]
  node_openrouter_key{{"OPENROUTER_API_KEY<br/>server environment secret"}}
end

subgraph group_external["External services"]
  node_openrouter{{"OpenRouter vision model<br/>remote inference"}}
end

node_app_shell -->|"wraps"| node_page
node_page -->|"renders"| node_ocr_ui
node_ocr_ui -->|"POST image Data URL or OCR text"| node_extract_route
node_ocr_ui -.->|"vision fallback"| node_tesseract
node_tesseract -->|"OCR text"| node_ocr_ui
node_extract_route -->|"uses"| node_openrouter_key
node_extract_route -->|"vision inference"| node_openrouter
node_openrouter -->|"model JSON"| node_extract_route
node_extract_route -.->|"interprets OCR-text input"| node_ocr_parser
node_extract_route -->|"validates and normalizes"| node_invoice_normalizer
node_ocr_parser -->|"parsed fields"| node_invoice_normalizer
node_invoice_normalizer -->|"structured result"| node_invoice_result
node_invoice_result -->|"preview data"| node_ocr_ui
node_ocr_ui -->|"generates workbook"| node_xlsx
node_xlsx -->|"local download"| node_workbook
node_debug_route -.->|"diagnoses integration"| node_openrouter

click node_app_shell "https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/layout.tsx"
click node_page "https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/page.tsx"
click node_ocr_ui "https://github.com/meetmendapara09/snap2sheet/blob/main/src/components/OcrToExcel.tsx"
click node_extract_route "https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/api/extract-invoice/route.ts"
click node_debug_route "https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/api/extract-invoice/debug/route.ts"
click node_invoice_normalizer "https://github.com/meetmendapara09/snap2sheet/blob/main/src/lib/invoice-extractor.ts"
click node_ocr_parser "https://github.com/meetmendapara09/snap2sheet/blob/main/src/lib/ocr-text-parser.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_app_shell,node_page,node_ocr_ui,node_tesseract,node_xlsx,node_workbook,node_invoice_result toneBlue
class node_extract_route,node_debug_route,node_invoice_normalizer,node_ocr_parser,node_openrouter_key toneAmber
class node_openrouter toneMint
```

## Components

### Browser app

- [App shell](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/layout.tsx): Next.js layout · `src/app/layout.tsx`
- [Invoice page](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/page.tsx): Next.js page · `src/app/page.tsx`
- [Extraction and review UI](https://github.com/meetmendapara09/snap2sheet/blob/main/src/components/OcrToExcel.tsx): React workflow · Owns upload, preview, fallback, review, and download state. · `src/components/OcrToExcel.tsx`
- **Tesseract OCR**: browser OCR · Fallback converts an image to text locally.
- **xlsx**: workbook library · Builds the downloadable workbook in the browser.
- **Excel workbook**: download · Contains summary, line items, audit, entries, and raw-data sheets.
- **Normalized invoice**: structured data · Review and export contract for extracted invoice data.

### Next.js server

- [Invoice extraction API](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/api/extract-invoice/route.ts): Next.js route · Server trust boundary for extraction requests and provider failures. · `src/app/api/extract-invoice/route.ts`
- [Extraction diagnostics API](https://github.com/meetmendapara09/snap2sheet/blob/main/src/app/api/extract-invoice/debug/route.ts): Next.js route · Examines the provider integration flow. · `src/app/api/extract-invoice/debug/route.ts`
- [Invoice normalization](https://github.com/meetmendapara09/snap2sheet/blob/main/src/lib/invoice-extractor.ts): domain library · Normalizes untrusted extraction output into the invoice representation. · `src/lib/invoice-extractor.ts`
- [OCR text parser](https://github.com/meetmendapara09/snap2sheet/blob/main/src/lib/ocr-text-parser.ts): parsing library · Interprets OCR text as invoice-oriented fields. · `src/lib/ocr-text-parser.ts`
- **OPENROUTER_API_KEY**: server environment secret · Confined to the server extraction route.

### External services

- **OpenRouter vision model**: remote inference · amazon/nova-2-lite-v1:free returns structured invoice JSON.

## Connections

- App shell → Invoice page: wraps
- Invoice page → Extraction and review UI: renders
- Extraction and review UI → Invoice extraction API: POST image Data URL or OCR text
- Extraction and review UI → Tesseract OCR: vision fallback
- Tesseract OCR → Extraction and review UI: OCR text
- Invoice extraction API → OPENROUTER_API_KEY: uses
- Invoice extraction API → OpenRouter vision model: vision inference
- OpenRouter vision model → Invoice extraction API: model JSON
- Invoice extraction API → OCR text parser: interprets OCR-text input
- Invoice extraction API → Invoice normalization: validates and normalizes
- OCR text parser → Invoice normalization: parsed fields
- Invoice normalization → Normalized invoice: structured result
- Normalized invoice → Extraction and review UI: preview data
- Extraction and review UI → xlsx: generates workbook
- xlsx → Excel workbook: local download
- Extraction diagnostics API → OpenRouter vision model: diagnoses integration