# abhishek-jose7/finance-tracker architecture

> Architecture diagram of the GitHub repository abhishek-jose7/finance-tracker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek-jose7/finance-tracker
- Repository: https://github.com/abhishek-jose7/finance-tracker

## Overview

##### Project Type and Purpose
- This is a full-stack personal finance web application (“FinAI”) built on Next.js 15 with an App Router.
- It integrates React-based frontend pages, AI workflows for budget insights (via Google Gemini/Genkit), and a Supabase-backed database.

##### High-Level Components
a. Frontend (Next.js App)
- Pages & Layouts: `src/app/` (main layout group, sign-in, sign-up, global layout/styles)
- React Components: `src/components/` organized by feature (dashboard, budget, transactions, AI assistant, onboarding, shared UI)
- Styling: Tailwind CSS (`tailwind.config.ts`, `src/app/globals.css`), Radix UI + shadcn/ui

b. Backend/API (Next.js Serverless Routes & Lib)
- API Routes: `src/app/api/` (debug, test-ai, test-sync)
- AI Flows & Orchestration: `src/ai/` (`genkit.ts`, `flows/` for budget analysis, recommendations, alerts, etc.)
- Data Layer: `src/lib/db-actions.ts`, `src/lib/file-processing.ts`, `src/lib/supabase.ts`
- Business Logic & Utilities: `src/lib/utils.ts`, `src/lib/data.ts`, type definitions

c. Database (Supabase)
- Schema & Scripts: `supabase-schema.sql`, migration scripts (`supabase-*.sql`)
- Data Access: via `src/lib/supabase.ts` and `db-actions.ts`

d. External Services
- Google Gemini AI: accessed through Genkit (`src/ai/genkit.ts`)
- Authentication/Session: Clerk (via `ClerkClientProvider.tsx`)
- Deployment: Vercel (with `vercel.json`) or Docker

##### Component Interactions & Data Flows
- User interacts with React pages/components →
Next.js serverless API or direct client-side calls for data fetch/submit →
Data layer reads/writes Supabase →
For AI features, API handlers invoke Genkit workflows →
Genkit forwards prompts to Google Gemini →
Gemini returns AI responses which are processed by the flow modules →
Results are sent back to frontend and rendered in UI components.

##### Architectural Patterns & Principles
- Feature-based module structure: Each domain (budget, dashboard, transactions, assistant) has its own folder under `components/` and `app/`.
- Separation of concerns: UI components vs. AI flows vs. data access/utilities.
- Serverless functions for API endpoints: Lightweight, per-feature routes.
- Layered approach: Presentation (React) → Application logic (AI flows, routes) → Persistence (Supabase) → External AI service.

A. Frontend Group
- App Sidebar, Header, ChatInterface, BudgetPlanner, TransactionTable, Chart Components
B. Backend/API Group
- /api/test-ai, /api/test-sync, /api/debug
- AI Flow Modules (analyze-budget, recommendations, alerts, explain-transaction)
C. Data Access Group
- Supabase Client, DB-actions module, SQL scripts
D. External Services
- Google Gemini AI (via Genkit)
- Clerk Authentication
E. Deployment & DevOps
- Dockerfile, docker-compose.yml, Vercel config

##### Final Advice
- How data and control flow between components.
- Custom patterns (e.g., Zod schema validation in AI flows).
- Keep it high-level but include enough detail so a new engineer can understand where to find code for each operation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::external

    %% Frontend Layer
    subgraph "Frontend Layer" 
        direction TB
        GL["Global Layout"]:::frontend
        MAL["Main App Layout"]:::frontend
        DP["Dashboard Page"]:::frontend
        BP["Budget Page"]:::frontend
        TP["Transactions Page"]:::frontend
        AP["Assistant Page"]:::frontend
        SP["Settings Page"]:::frontend
        SIP["Sign-In Page"]:::frontend
        SUP["Sign-Up Page"]:::frontend

        BPComp["BudgetPlanner Component"]:::frontend
        TPComp["TransactionTable Component"]:::frontend
        CIComp["ChatInterface Component"]:::frontend
        DCComp["Dashboard Composite"]:::frontend
        UIKit["Shared UI Kit"]:::frontend
        ClerkProv["ClerkClientProvider"]:::frontend
    end

    %% Backend/API Layer
    subgraph "Backend/API Layer"
        direction TB
        API_Debug["/api/debug"]:::backend
        API_TestAI["/api/test-ai"]:::backend
        API_TestSync["/api/test-sync"]:::backend

        subgraph "AI Flows & Orchestration"
            direction TB
            Genkit["Genkit Integration"]:::backend
            Flow1["AI Flow: analyze-budget-suggest-adjustments"]:::backend
            Flow2["AI Flow: generate-ai-recommendations"]:::backend
            Flow3["AI Flow: provide-overspending-alerts"]:::backend
            Flow4["AI Flow: explain-transaction-details"]:::backend
            Flow5["AI Flow: general-financial-assistant"]:::backend
        end

        subgraph "Data Layer Services"
            direction TB
            SupClient["Supabase Client"]:::backend
            DBActions["DB Actions"]:::backend
            FileProc["File Processing Utilities"]:::backend
            Utils["Business Utilities"]:::backend
            DataDefs["Data Access Definitions"]:::backend
        end
    end

    %% Database Layer
    subgraph "Database Layer"
        direction TB
        DB["Supabase DB & Migrations"]:::db
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Gemini["Google Gemini AI"]:::external
        ClerkAuth["Clerk Auth Service"]:::external
    end

    %% Deployment
    subgraph "Deployment & DevOps"
        direction TB
        Docker["Docker Config"]:::deployment
        Vercel["Vercel Config"]:::deployment
    end

    %% Relationships
    User -->|interacts with| GL
    GL --> MAL
    MAL --> DP
    MAL --> BP
    MAL --> TP
    MAL --> AP
    MAL --> SP
    GL --> SIP
    GL --> SUP

    DP --> DCComp
    BP --> BPComp
    TP --> TPComp
    AP --> CIComp
    DP --> UIKit
    BP --> UIKit
    TP --> UIKit
    AP --> UIKit

    GL --> ClerkProv
    ClerkProv --> ClerkAuth

    DP -->|fetch/submit| API_Debug
    BP -->|fetch/submit| API_TestSync
    AP -->|AI request| API_TestAI

    API_Debug --> SupClient
    API_TestSync --> DBActions
    API_TestSync --> FileProc
    API_TestAI --> Genkit

    Genkit --> Flow1
    Genkit --> Flow2
    Genkit --> Flow3
    Genkit --> Flow4
    Genkit --> Flow5

    Flow1 --> SupClient
    Flow2 --> SupClient
    Flow3 --> SupClient
    Flow4 --> SupClient
    Flow5 --> SupClient

    SupClient --> DB
    DBActions --> DB
    FileProc --> DB
    DataDefs --> SupClient
    Utils --> Flow1

    Flow1 -->|AI call| Gemini
    Flow2 -->|AI call| Gemini
    Flow3 -->|AI call| Gemini
    Flow4 -->|AI call| Gemini
    Flow5 -->|AI call| Gemini

    %% Deployment relationships
    Docker -->|deploy| GL
    Docker -->|deploy| API_Debug
    Vercel -->|deploy| MAL
    Vercel -->|deploy| API_TestAI

    %% Click Events
    click GL "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/layout.tsx"
    click MAL "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/layout.tsx"
    click DP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/dashboard/page.tsx"
    click BP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/budget/page.tsx"
    click TP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/transactions/page.tsx"
    click AP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/assistant/page.tsx"
    click SP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/(main)/settings/page.tsx"
    click SIP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/sign-in/[[...sign-in]]/page.tsx"
    click SUP "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/sign-up/[[...sign-up]]/page.tsx"
    click BPComp "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/components/budget/BudgetPlanner.tsx"
    click TPComp "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/components/transactions/TransactionTable.tsx"
    click CIComp "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/components/assistant/ChatInterface.tsx"
    click DCComp "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/components/dashboard/Dashboard.tsx"
    click UIKit "https://github.com/abhishek-jose7/finance-tracker/tree/main/src/components/ui/"
    click ClerkProv "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/components/ClerkClientProvider.tsx"
    click API_Debug "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/api/debug/route.ts"
    click API_TestAI "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/api/test-ai/route.ts"
    click API_TestSync "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/app/api/test-sync/route.ts"
    click Genkit "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/genkit.ts"
    click Flow1 "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/flows/analyze-budget-suggest-adjustments.ts"
    click Flow2 "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/flows/generate-ai-recommendations.ts"
    click Flow3 "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/flows/provide-overspending-alerts.ts"
    click Flow4 "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/flows/explain-transaction-details.ts"
    click Flow5 "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/ai/flows/general-financial-assistant.ts"
    click SupClient "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/lib/supabase.ts"
    click DBActions "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/lib/db-actions.ts"
    click FileProc "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/lib/file-processing.ts"
    click Utils "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/lib/utils.ts"
    click DataDefs "https://github.com/abhishek-jose7/finance-tracker/blob/main/src/lib/data.ts"
    click DB "https://github.com/abhishek-jose7/finance-tracker/blob/main/supabase-schema.sql"
    click Docker "https://github.com/abhishek-jose7/finance-tracker/tree/main/Dockerfile"
    click Docker "https://github.com/abhishek-jose7/finance-tracker/blob/main/docker-compose.yml"
    click Vercel "https://github.com/abhishek-jose7/finance-tracker/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6;
    classDef backend fill:#E6F4EA,stroke:#22963A,color:#22963A;
    classDef db fill:#FFF5E1,stroke:#E6A400,color:#E6A400,stroke-dasharray: 5 5;
    classDef external fill:#FFF5F5,stroke:#D73A49,color:#D73A49;
    classDef deployment fill:#F0F0F0,stroke:#6A737D,color:#6A737D;
```
