# viru143/spendwiseai architecture

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

- Interactive diagram: https://gitdiagram.com/viru143/spendwiseai
- Repository: https://github.com/viru143/spendwiseai

## Overview

##### Project Type and Purpose
- This is a full-stack (primarily front-end) Next.js web application named “SpendWise AI.”
- Its primary purpose is expense tracking with built-in AI features—receipt scanning and category suggestions—using Google’s Gemini models via the Genkit API.
- All persistent data (expenses) live in the browser’s local storage; no dedicated backend database or server-side data store is present.

##### High-Level Architecture Components
a. Client Browser (Next.js App)
- UI Layer: React components (src/components and src/app) built with TypeScript, Tailwind CSS, and ShadCN primitives.
- State & Persistence: React hooks (src/hooks/use-local-storage) manage in-memory state and sync to localStorage.
- AI Module: src/ai contains Genkit client logic and “flows” for receipt analysis and category suggestion.
- Utility Layer: src/lib houses constants, data types, and common helper functions.

b. Next.js Runtime
- Static/SSR Hosting: next.config.ts and apphosting.yaml configure build/deployment.
- Routing & Layout: src/app/layout.tsx orchestrates global styles and wrappers; src/app/page.tsx is the entry point.

c. External Services
- Genkit API Gateway: invoked by the AI Module (src/ai/genkit.ts)
- Google Gemini Model: underlying LLM service behind Genkit

d. Data Store
- Browser Local Storage: persistent storage for expenses via a custom hook.

##### Relationships and Data Flow
1. User interacts with the UI in the browser.
2. UI components call custom hooks (useLocalStorage) to read/write expense data.
3. When a user uploads a receipt or requests a suggestion, the AI Module packages the request and calls the Genkit REST API.
4. Genkit forwards to Google Gemini, processes the image/text, returns structured data.
5. The AI Module parses the response and updates UI state, which in turn persists to localStorage.
6. Next.js server delivers initial HTML/JS bundles, but runtime interactions occur client-side.

##### Architectural Patterns & Principles
- Component-Based UI (Atomic design via ShadCN).
- Separation of Concerns: UI vs. AI logic vs. utilities.
- Hook Abstraction: encapsulate cross-cutting concerns (persistence, toast notifications, mobile detection).
- Externalization of AI calls: isolating Genkit client from UI code.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraph: Browser (Next.js App)
    subgraph "Browser (Next.js App)" 
        direction TB
        subgraph "UI Components" 
            direction TB
            Components["Atomic & Page Components<br/>(Next.js, React, TS, Tailwind, ShadCN)"]:::client
            Routing["Routing & Layout<br/>(page.tsx, layout.tsx, globals.css)"]:::client
        end

        subgraph "State & Persistence" 
            direction TB
            LocalStorageHook["useLocalStorage Hook"]:::client
            ToastHook["useToast Hook"]:::client
            MobileHook["useMobile Hook"]:::client
        end

        subgraph "AI Module" 
            direction TB
            GenkitClient["Genkit Client (genkit.ts, dev.ts)"]:::ai
            subgraph "AI Flows"
                direction TB
                AnalyzeFlow["analyze-receipt.ts"]:::ai
                CategorizeFlow["categorize-expense.ts"]:::ai
            end
        end

        subgraph "Utilities" 
            direction TB
            Constants["constants.ts"]:::client
            Types["types.ts"]:::client
            Utils["utils.ts"]:::client
        end
    end

    %% Other Components
    NextJSHosting["Next.js Hosting Layer<br/>(next.config.ts, apphosting.yaml)"]:::hosting
    GenkitAPI["Genkit API Gateway"]:::external
    GoogleGemini["Google Gemini Model"]:::external
    BrowserStorage["Browser Local Storage"]:::storage

    %% Data Flows & Relationships
    Components -->|uses hooks| LocalStorageHook
    Components -->|uses hooks| ToastHook
    Components -->|uses hooks| MobileHook
    Routing -->|initial load| NextJSHosting
    LocalStorageHook <-->|"sync"| BrowserStorage
    GenkitClient -->|"call API"| GenkitAPI
    GenkitAPI -->|"invoke model"| GoogleGemini
    GoogleGemini -->|"response"| GenkitAPI
    GenkitAPI -->|"response"| GenkitClient
    AnalyzeFlow -->|uses| GenkitClient
    CategorizeFlow -->|uses| GenkitClient
    GenkitClient -->|update state| LocalStorageHook
    Constants & Types & Utils -->|helper| Components
    Constants & Types & Utils -->|helper| GenkitClient

    %% Click Events
    click Components "https://github.com/viru143/spendwiseai/tree/master/src/components"
    click Routing "https://github.com/viru143/spendwiseai/blob/master/src/app/page.tsx"
    click Routing "https://github.com/viru143/spendwiseai/blob/master/src/app/layout.tsx"
    click Routing "https://github.com/viru143/spendwiseai/blob/master/src/app/globals.css"
    click LocalStorageHook "https://github.com/viru143/spendwiseai/blob/master/src/hooks/use-local-storage.ts"
    click ToastHook "https://github.com/viru143/spendwiseai/blob/master/src/hooks/use-toast.ts"
    click MobileHook "https://github.com/viru143/spendwiseai/blob/master/src/hooks/use-mobile.tsx"
    click GenkitClient "https://github.com/viru143/spendwiseai/blob/master/src/ai/genkit.ts"
    click GenkitClient "https://github.com/viru143/spendwiseai/blob/master/src/ai/dev.ts"
    click AnalyzeFlow "https://github.com/viru143/spendwiseai/blob/master/src/ai/flows/analyze-receipt.ts"
    click CategorizeFlow "https://github.com/viru143/spendwiseai/blob/master/src/ai/flows/categorize-expense.ts"
    click Constants "https://github.com/viru143/spendwiseai/blob/master/src/lib/constants.ts"
    click Types "https://github.com/viru143/spendwiseai/blob/master/src/lib/types.ts"
    click Utils "https://github.com/viru143/spendwiseai/blob/master/src/lib/utils.ts"
    click NextJSHosting "https://github.com/viru143/spendwiseai/blob/master/next.config.ts"
    click NextJSHosting "https://github.com/viru143/spendwiseai/blob/master/apphosting.yaml"

    %% Styles
    classDef client fill:#E8F1FC,stroke:#3182CE,color:#1E3A8A
    classDef ai fill:#FEF3C7,stroke:#D97706,color:#92400E
    classDef storage fill:#D1FAE5,stroke:#059669,color:#065F46
    classDef external fill:#FEE2E2,stroke:#DC2626,color:#7F1D1D
    classDef hosting fill:#E0E7FF,stroke:#4338CA,color:#1E3A8A
```
