# supthunder/snaptab architecture

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

- Interactive diagram: https://gitdiagram.com/supthunder/snaptab
- Repository: https://github.com/supthunder/snaptab

## Overview

##### Project type and purpose
- SnapTab is a full-stack, mobile-first Progressive Web App (PWA) built with Next.js 14 (App Router).
- Purpose: Enable group travel expense tracking by snapping receipt photos, AI-extracting data, auto-splitting costs, and offering live balance and settlement features.

##### File structure
- Top-level “app” folder: Next.js App Router pages and layouts.
- app/page.tsx, app/layout.tsx – Core shell and root layout.
- app/api/scan-receipt/route.ts – Serverless API endpoint for receipt scanning.
- app/(feature) – Routes for add-expense, create-trip, trips, expenses, scan, settlement.
- “components” folder: UI primitives (buttons, dialogs, tables, charts) and theme provider.
- “hooks” and “lib” – Shared React hooks (use-mobile, use-toast) and utility functions.
- Config files (next.config.mjs, tailwind.config.ts, postcss.config.mjs, tsconfig.json) – Build and deployment scripts.
- “public” – Static assets and PWA manifest.

##### README for additional insights
- Frontend: Next.js (Server & Client Components), Tailwind CSS, PWA + offline caching.
- Backend: Vercel serverless functions, Prisma ORM + Vercel Postgres, NextAuth.js for authentication.
- AI & Storage: OpenAI GPT-4 Vision for receipt parsing; Vercel Blob for image storage.
- Data models in Prisma schema define Users, Trips, Expenses, ExpenseSplits.

a. Main components
- Client (Browser/PWA) – React pages & components running in mobile or desktop.
- Next.js Server – SSR, Server Components, API routes, and Server Actions.
- Authentication Service – NextAuth.js backed by OAuth (Google/Apple/email).
- Database – Vercel Postgres accessed via Prisma.
- AI Service – OpenAI GPT-4 Vision API for receipt analysis.
- Blob Storage – Vercel Blob for receipt image storage.
- External Services – OAuth providers; Vercel Hosting.
b. Relationships & interactions
1. User interacts with the PWA → HTTP(S) requests to Next.js server.
2. NextAuth.js handles sign-in/out and session management.
3. On “Snap Receipt”:
- Client uploads image to Vercel Blob.
- Next.js API route (/api/scan-receipt) calls OpenAI Vision with image URL.
- OpenAI returns JSON → Next.js populates form.
4. Saving an expense:
- Client submits through Server Component or Action → Prisma writes to Postgres.
- ExpenseSplits table generated to record per-user owed amounts.
5. Real-time updates:
- Next.js streaming Server Components or client polling fetch latest balances & feeds.
6. Settlement:
- Backend computes optimized payment graph using splits → updates database.
c. Architectural patterns/design principles
- App Router & mixed Server/Client Components for SEO and performance.
- Serverless micro-endpoints (API routes + Server Actions) – no monolithic backend.
- Layered separation: UI layer → API/Server Actions → ORM → Database.
- Progressive enhancement: offline caching (Workbox or Next.js PWA plugin).
- Single-page experience with nested layouts.
d. Key technologies/frameworks
- Next.js 14 (App Router), React, PWA API
- Tailwind CSS for UI
- Prisma ORM → PostgreSQL
- NextAuth.js → OAuth
- OpenAI GPT-4 Vision
- Vercel Blob storage
- Vercel serverless functions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        User["User"]:::external
        PWA["PWA UI"]:::frontend
        SW["Service Worker & Cache"]:::frontend
        Layout["Root Layout"]:::frontend
        Page["Home Page"]:::frontend
        subgraph "Feature Routes"
            direction TB
            AddExpense["/add-expense"]:::frontend
            CreateTrip["/create-trip"]:::frontend
            Trips["/trips"]:::frontend
            Expenses["/expenses"]:::frontend
            ScanPage["/scan"]:::frontend
            Settlement["/settlement"]:::frontend
        end
        subgraph "UI Primitives & Theming"
            direction TB
            ThemeProvider["Theme Provider"]:::frontend
            UIPrimitives["UI Primitives"]:::frontend
        end
        subgraph "Hooks & Utils"
            direction TB
            UseMobile["use-mobile"]:::frontend
            UseToast["use-toast"]:::frontend
            Utils["utils"]:::frontend
        end
    end

    %% Server Layer
    subgraph "Next.js Server" 
        direction TB
        SSR["Server Components"]:::server
        APIRoutes["API Routes"]:::server
        ServerActions["Server Actions"]:::server
        AuthService["NextAuth.js"]:::server
    end

    %% Data & Persistence Layer
    subgraph "Data & Persistence"
        direction TB
        Prisma["Prisma ORM"]:::data
        Postgres["PostgreSQL"]:::data
        BlobStorage["Vercel Blob"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI GPT-4 Vision"]:::external
        OAuth["OAuth Providers"]:::external
        VercelHost["Vercel Hosting"]:::external
    end

    %% Connections
    User -->|"interact"| PWA
    PWA -->|"fetch pages"| Layout
    Layout --> Page
    Page --> AddExpense
    Page --> CreateTrip
    Page --> Trips
    Page --> Expenses
    Page --> ScanPage
    Page --> Settlement
    PWA --> SW
    PWA --> ThemeProvider
    PWA --> UIPrimitives
    PWA --> UseMobile
    PWA --> UseToast
    PWA --> Utils
    PWA -->|"SSR & Actions"| SSR
    PWA -->|"call API"| APIRoutes
    SSR --> Prisma
    ServerActions --> Prisma
    APIRoutes --> Prisma
    Prisma --> Postgres
    APIRoutes --> BlobStorage
    BlobStorage --> OpenAI
    APIRoutes --> OpenAI
    AuthService --> OAuth
    SSR --> AuthService
    APIRoutes --> AuthService
    VercelHost --> SSR
    VercelHost --> APIRoutes
    VercelHost --> BlobStorage
    VercelHost --> Postgres

    %% Click Events
    click Layout "https://github.com/supthunder/snaptab/blob/main/app/layout.tsx"
    click Page "https://github.com/supthunder/snaptab/blob/main/app/page.tsx"
    click AddExpense "https://github.com/supthunder/snaptab/blob/main/app/add-expense/page.tsx"
    click CreateTrip "https://github.com/supthunder/snaptab/blob/main/app/create-trip/page.tsx"
    click Trips "https://github.com/supthunder/snaptab/blob/main/app/trips/page.tsx"
    click Expenses "https://github.com/supthunder/snaptab/blob/main/app/expenses/page.tsx"
    click ScanPage "https://github.com/supthunder/snaptab/blob/main/app/scan/page.tsx"
    click Settlement "https://github.com/supthunder/snaptab/blob/main/app/settlement/page.tsx"
    click ThemeProvider "https://github.com/supthunder/snaptab/blob/main/components/theme-provider.tsx"
    click UIPrimitives "https://github.com/supthunder/snaptab/tree/main/components/ui"
    click UseMobile "https://github.com/supthunder/snaptab/blob/main/hooks/use-mobile.tsx"
    click UseToast "https://github.com/supthunder/snaptab/blob/main/hooks/use-toast.ts"
    click Utils "https://github.com/supthunder/snaptab/blob/main/lib/utils.ts"
    click APIRoutes "https://github.com/supthunder/snaptab/blob/main/app/api/scan-receipt/route.ts"
    click SW "https://github.com/supthunder/snaptab/blob/main/public/manifest.json"
    click SW "https://github.com/supthunder/snaptab/blob/main/app/globals.css"
    click SW "https://github.com/supthunder/snaptab/blob/main/styles/globals.css"
    click VercelHost "https://github.com/supthunder/snaptab/blob/main/next.config.mjs"
    click VercelHost "https://github.com/supthunder/snaptab/blob/main/tailwind.config.ts"
    click VercelHost "https://github.com/supthunder/snaptab/blob/main/postcss.config.mjs"
    click VercelHost "https://github.com/supthunder/snaptab/blob/main/tsconfig.json"

    %% Styles
    classDef frontend fill:#e0f7fa,stroke:#006064,color:#006064
    classDef server fill:#e8f5e9,stroke:#2e7d32,color:#2e7d32
    classDef data fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c
```
