# jrg-one/finsage architecture

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

- Interactive diagram: https://gitdiagram.com/jrg-one/finsage
- Repository: https://github.com/jrg-one/finsage

## Overview

##### Project type and purpose
- This is a full-stack Next.js (v13 App Router) application for personal finance management: tracking income, expenses, uploading bank/receipt files (with OCR), generating insights/statistics, and user authentication.
- It’s bootstrapped with create-next-app, styled with Tailwind CSS, and integrates Firebase for auth (and likely for data persistence/storage).

##### File structure
- src/app ⇒ Next.js pages (account, login, register, dashboard, expense, income, statistics, upload-transactions, settings) and API routes under src/app/api.
- Each route (file-transaction, gemini, insight, ocr, stats/insights, stats/summary) is a serverless function (route.ts).
- src/components ⇒ reusable UI primitives (ui/), layout components, domain widgets (dashboard charts and tables, expense/income forms and lists, receipt uploader).
- src/context/AuthContext.tsx ⇒ React Context for managing user session.
- src/lib ⇒ core utilities: firebase.ts (initializes Auth & likely Firestore/Storage SDK), parseForm.ts, utils.ts.
- public ⇒ static files (404.html, index.html) and any static assets.
- Config files: next.config.ts, tailwind.config.js, ESLint/PostCSS configs.
- test/data ⇒ sample PDF and its text for tests.

##### Inspect the README for insights
- Confirms Next.js usage, development workflow, optimized fonts, and recommended Vercel deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        Browser["Browser"]:::ext
        Pages["Next.js Pages"]:::ui
        AuthContext["Authentication Context"]:::ui
        Styles["Styling & Global CSS"]:::ui
        subgraph "UI Components & Design System"
            DashboardWidgets["Dashboard Widgets"]:::ui
            ExpenseComp["Expense Domain Components"]:::ui
            IncomeComp["Income Domain Components"]:::ui
            ReceiptUploader["Receipt Uploader"]:::ui
            UIPrimitives["Atomic UI Primitives"]:::ui
            Layouts["Layouts"]:::ui
        end
    end

    %% API Layer
    subgraph "API Layer"
        FileTx["File Transaction Service"]:::api
        OCR["OCR Service Proxy"]:::api
        Gemini["Gemini API Proxy"]:::api
        Insight["Insight Engine Proxy"]:::api
        StatsInsights["Statistics - Insights"]:::api
        StatsSummary["Statistics - Summary"]:::api
    end

    %% Utilities & Library
    subgraph "Utilities & Lib"
        FirebaseInit["Firebase Initialization"]:::util
        ParseForm["Form Parsing Utility"]:::util
        Utils["General Helpers"]:::util
    end

    %% Firebase Services
    subgraph "Firebase Services"
        AuthDB["Firebase Auth"]:::db
        Firestore["Firestore & Storage"]:::db
    end

    %% External Services
    subgraph "External Services"
        ExternalOCR["OCR Service"]:::ext
        ExternalGemini["Gemini API"]:::ext
        ExternalInsight["Insight Engine"]:::ext
    end

    %% Connections: UI to Context & API
    Browser --> Pages
    Pages --> AuthContext
    Pages --> FileTx
    Pages --> OCR
    Pages --> Gemini
    Pages --> Insight
    Pages --> StatsInsights
    Pages --> StatsSummary

    %% Auth Flow
    AuthContext --> FirebaseInit
    FirebaseInit --> AuthDB
    FirebaseInit --> Firestore

    %% API to Firebase & Utilities
    FileTx --> FirebaseInit
    OCR --> FirebaseInit
    Gemini --> FirebaseInit
    Insight --> FirebaseInit
    StatsInsights --> FirebaseInit
    StatsSummary --> FirebaseInit

    FileTx --> ParseForm
    FileTx --> Utils
    OCR --> ParseForm
    OCR --> Utils
    Gemini --> Utils
    Insight --> Utils
    StatsInsights --> Utils
    StatsSummary --> Utils

    %% API to External
    OCR --> ExternalOCR
    Gemini --> ExternalGemini
    Insight --> ExternalInsight

    %% Click Events
    click Pages "https://github.com/jrg-one/finsage/tree/main/src/app"
    click AuthContext "https://github.com/jrg-one/finsage/blob/main/src/context/AuthContext.tsx"
    click FirebaseInit "https://github.com/jrg-one/finsage/blob/main/src/lib/firebase.ts"
    click ParseForm "https://github.com/jrg-one/finsage/blob/main/src/lib/parseForm.ts"
    click Utils "https://github.com/jrg-one/finsage/blob/main/src/lib/utils.ts"
    click FileTx "https://github.com/jrg-one/finsage/blob/main/src/app/api/file-transaction/route.ts"
    click OCR "https://github.com/jrg-one/finsage/blob/main/src/app/api/ocr/route.ts"
    click Gemini "https://github.com/jrg-one/finsage/blob/main/src/app/api/gemini/route.ts"
    click Insight "https://github.com/jrg-one/finsage/blob/main/src/app/api/insight/route.ts"
    click StatsInsights "https://github.com/jrg-one/finsage/blob/main/src/app/api/stats/insights/route.ts"
    click StatsSummary "https://github.com/jrg-one/finsage/blob/main/src/app/api/stats/summary/route.ts"
    click DashboardWidgets "https://github.com/jrg-one/finsage/tree/main/src/components/dashboard"
    click ExpenseComp "https://github.com/jrg-one/finsage/tree/main/src/components/expense"
    click IncomeComp "https://github.com/jrg-one/finsage/tree/main/src/components/income"
    click ReceiptUploader "https://github.com/jrg-one/finsage/blob/main/src/components/receipt/ReceiptUploader.tsx"
    click UIPrimitives "https://github.com/jrg-one/finsage/tree/main/src/components/ui"
    click Layouts "https://github.com/jrg-one/finsage/tree/main/src/components/layouts"
    click Styles "https://github.com/jrg-one/finsage/blob/main/src/app/globals.css"

    %% Styles
    classDef ui fill:#E0F2FE,stroke:#0369A1,stroke-width:1px
    classDef api fill:#DCFCE7,stroke:#15803D,stroke-width:1px
    classDef db fill:#FEF9C3,stroke:#A16207,stroke-width:1px
    classDef ext fill:#F5D0FE,stroke:#7E22CE,stroke-width:1px
    classDef util fill:#FEF3C7,stroke:#B45309,stroke-width:1px
```
