# moneymentor-09/moneymentor-frontend architecture

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

- Interactive diagram: https://gitdiagram.com/moneymentor-09/moneymentor-frontend
- Repository: https://github.com/moneymentor-09/moneymentor-frontend

## Overview

##### Project Type and Purpose
- MoneyMentor is a full-stack, server-rendered web application built with Next.js (App Router) that provides AI-powered personal finance management.
- The frontend is React/TypeScript/Tailwind-based; the backend logic lives in Next.js API routes and Supabase (Auth, Database, RLS); external AI calls go to OpenAI GPT.

##### File Structure
- Top-level “app” directory: Next.js 14 App Router pages and serverless API routes under app/api (auth, chat, transactions, proxyLogin, etc.).
- “components” directory: UI building blocks (ShadCN/UI + Tailwind) and domain-specific components (dialogs, charts, nav, transactions list, etc.).
- “hooks” directory: custom React hooks (use-authListener, use-inactivity-timer, use-toast, use-mobile).
- “lib” directory: business logic utilities (constants, CSV parser, fraud detection, Supabase client/server wrappers, transactions CSV helpers, utils).
- “scripts” directory: SQL scripts to initialize and secure the Supabase database.
- Config files: next.config.mjs, tsconfig.json, postcss.config.mjs, middleware.ts.

##### Key Insights from README
- Frontend: Next.js + React 18, TS, Tailwind CSS, ShadCN/UI, Recharts for visualization.
- Backend/Auth/DB: Supabase for authentication, DB, RLS.
- AI Engine: OpenAI GPT API.
- Deployment: Vercel (serverless functions) or any Next.js-capable host.

##### Main Components
a. Client (Browser/Mobile)
- React/Next.js pages served to the client.
- UI components (charts, dialogs, forms).
b. Next.js Application (Vercel Serverless)
- App Router handlers (server-side rendering, static props).
- API Routes:
– /api/auth/* (Email/Password, Google OAuth, OTP, forgot/reset password)
– /api/chat (proxy for OpenAI)
– /api/transactions/* (CRUD, batch, manifest)
– /api/proxyLogin
- Middleware (e.g., session timeout, RLS enforcement).
- lib modules for business logic: fraud detection, CSV parsing, utils.
c. Supabase
- Auth (JWT, sessions, RLS).
- Database (profiles, transactions, budgets, alerts, functions/triggers).
d. OpenAI GPT API
- Chat-based insights, spending analysis, recommendations.
e. Deployment & CI/CD
- Vercel / GitHub integration (push → automatic deploy).
f. External Services
- Email provider (for OTP or password reset emails).
- Potential SMS/OTP provider (if phone OTP is external).

##### Relationships & Interactions
- User → Browser UI → Next.js pages (SSR/CSR)
- Browser UI → Next.js API routes (fetch / mutate data)
- API routes → Supabase client/server (read/write, RLS)
- API routes → OpenAI GPT API (chat endpoint)
- lib modules invoked within API routes and server components
- Next.js middleware enforces inactivity logout and RLS checks
- SQL scripts used offline for initial DB setup (profiles, transactions, budgets, alerts, RLS, functions)

##### Architectural Patterns & Design Principles
- Separation of concerns:
- Presentation layer (components, pages)
- Business logic layer (lib/)
- Data access layer (supabase client/server wrappers)
- Serverless micro-endpoints: each feature (auth, transactions, chat) in its own API route.
- RLS at the database layer for multi-tenant security.
- API layer as a façade to external services (OpenAI, Supabase).
- Custom hooks for cross-cutting concerns (auth listening, inactivity timer, toasts).

##### Elements
- Clear labels (e.g., “Next.js App (Serverless)”, “Supabase Database & Auth”).
- UI Components (rectangles, light blue)
- API / Business Logic (rounded rectangles, green)
- Layering: group UI pages/components together, group API routes and lib modules together, group DB and scripts together.

4. Inside “Next.js Serverless,” subdivide into:
- App Router / Page Rendering
- API Routes (auth, transactions, chat, proxyLogin)
- Middleware
- lib modules (fraudDetection, csvParser, supabase client)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Deployment Layer
    subgraph "CI/CD Pipeline"
        direction TB
        GitHub["GitHub Repository"]:::external
        Vercel["Vercel Deployment"]:::deployment
        GitHub -->|"push code"| Vercel
        Vercel -->|"deploy Next.js App"| NextApp
    end

    %% Client Layer
    subgraph "Client (Browser)" 
        direction TB
        ClientUI["Next.js Pages & React Components"]:::frontend
        Hooks["Custom React Hooks"]:::frontend
        ClientUI -->|renders UI| NextApp
        Hooks -->|used in UI| ClientUI
    end

    %% Next.js Application Layer
    subgraph "Next.js App (Serverless)" 
        direction TB
        NextApp["Next.js App (Serverless)"]:::backend

        subgraph "App Router & Rendering"
            direction TB
            SSR["Server-Side Rendering & CSR"]:::backend
        end

        subgraph "API Routes"
            direction TB
            AuthAPI["Auth API Routes"]:::api
            ChatAPI["Chat Proxy API"]:::api
            TransAPI["Transactions API Routes"]:::api
            ProxyLogin["ProxyLogin API"]:::api
        end

        Middleware["Middleware (Session Timeout & RLS)"]:::middleware
        subgraph "Business Logic (lib/)"
            direction TB
            Constants["constants.ts"]:::lib
            CsvParser["csv-parser.ts"]:::lib
            FraudDetect["fraud-detection.ts"]:::lib
            Utils["utils.ts"]:::lib
            SupabaseClient["supabase/client.ts"]:::lib
            SupabaseServer["supabase/server.ts"]:::lib
            TxCsv["transactions/csv.ts"]:::lib
        end

        NextApp --> SSR
        SSR -->|calls| AuthAPI
        SSR -->|calls| TransAPI
        SSR -->|calls| ChatAPI

        AuthAPI -->|CRUD & Auth| Supabase
        TransAPI -->|CRUD Data| Supabase
        ChatAPI -->|GPT Chat Request| OpenAI
        ProxyLogin -->|login proxy| Supabase

        AuthAPI --> Constants
        TransAPI --> CsvParser
        TransAPI --> FraudDetect
        AuthAPI --> Utils
        ChatAPI --> Utils
        AuthAPI --> SupabaseClient
        AuthAPI --> SupabaseServer
        TransAPI --> SupabaseClient
        TransAPI --> SupabaseServer
        ChatAPI --> SupabaseClient
        ChatAPI --> SupabaseServer

        Middleware --> Supabase
    end

    %% Supabase Layer
    subgraph "Supabase"
        direction TB
        Auth["Auth & RLS"]:::database
        DB["Database Tables & Functions"]:::database
        Scripts["DB Provisioning Scripts"]:::scripts
        Scripts -->|initialize DB| DB
    end

    %% External Services
    subgraph "External Services"
        direction TB
        OpenAI["OpenAI GPT API"]:::external
        Email["Email Provider"]:::external
        SMS["SMS/OTP Provider"]:::external
    end

    %% Data Flows
    ClientUI -->|SSR Page Request| SSR
    ClientUI -->|API Fetch/Mutate| AuthAPI
    ClientUI -->|API Fetch/Mutate| TransAPI
    ClientUI -->|API Fetch| ChatAPI

    AuthAPI -->|sends OTP/Reset Email| Email
    AuthAPI -->|sends SMS OTP| SMS

    %% Click Events
    click ClientUI "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/app/page.tsx"
    click Hooks "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/hooks/use-authListener.ts"
    click AuthAPI "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/app/api/auth/forgot-password/route.ts"
    click ChatAPI "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/app/api/chat/route.ts"
    click TransAPI "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/app/api/transactions/manifest/route.ts"
    click ProxyLogin "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/app/api/proxyLogin.ts"
    click Middleware "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/middleware.ts"
    click Constants "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/constants.ts"
    click CsvParser "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/csv-parser.ts"
    click FraudDetect "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/fraud-detection.ts"
    click Utils "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/utils.ts"
    click SupabaseClient "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/supabase/client.ts"
    click SupabaseServer "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/supabase/server.ts"
    click TxCsv "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/lib/transactions/csv.ts"
    click Scripts "https://github.com/moneymentor-09/moneymentor-frontend/blob/main/scripts/01-create-tables.sql"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E6FFED,stroke:#28a745,color:#28a745
    classDef api fill:#E0F7FA,stroke:#00acc1,color:#006064
    classDef middleware fill:#FFF3E0,stroke:#fb8c00,color:#e65100
    classDef lib fill:#F3E5F5,stroke:#8e24aa,color:#6a1b9a
    classDef database fill:#FFE0B2,stroke:#fb8c00,color:#e65100
    classDef external fill:#E1F5FE,stroke:#0277BD,color:#01579B
    classDef deployment fill:#F1F8E9,stroke:#689f38,color:#33691E
    classDef scripts fill:#FFEBEE,stroke:#c62828,color:#b71c1c
```
