# vimalsaraswat/money-forge architecture

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

- Interactive diagram: https://gitdiagram.com/vimalsaraswat/money-forge
- Repository: https://github.com/vimalsaraswat/money-forge

## Overview

##### Project type and purpose
- MoneyForge is a full-stack personal finance management web application built on Next.js (App Router).
- It combines React Server Components, Server Actions, a type-safe PostgreSQL database (via Drizzle ORM), and multiple external services (AI, email, cloud storage).

##### File structure
- **app/**: Next.js App Router pages, layouts, loading/fallback UI, RSC entry points, parallel intercept routes for AI chat.
- **actions/**: Server Action functions (business logic) invoked directly from RSC or form submissions (CRUD, AI prompts, alerts).
- **components/**: Shadcn UI–based React components (UI primitives, modals, forms, charts).
- **db/**: Drizzle ORM setup—schema definitions, query functions, DB client.
- **config/** & **templates/**: Constants, AI prompts, email templates.
- **providers/**: React Context providers (AI, Theme, Session).
- **lib/**: Utility wrappers for Cloudinary, Nodemailer, helpers.
- **auth/** & **app/api/auth/**: NextAuth.js configuration and route handlers.

##### README insights
- Emphasis on RSC + Server Actions for colocation of UI and backend logic.
- Use of Google Gemini via Vercel AI SDK for conversational financial assistance.
- NextAuth.js (Google provider) for authentication.
- Framer Motion, Recharts, Tailwind CSS, Shadcn UI for dynamic, responsive UI.
- Nodemailer for budget alert emails, Cloudinary for image uploads.

- **Client Browser (UI Layer)**
- Next.js RSC pages & React components (app/, components/)
- Charting & animations (Recharts, Framer Motion)
- **Next.js Server (App Router)**
- Server Components rendering
- Server Actions (actions/) for mutations & business rules
- API Routes (app/api/auth/[...nextauth]) for authentication
- **Business Logic & Services**
- AI service integration (Vercel AI SDK → Google Gemini)
- Email service (Nodemailer + templates/)
- Image storage (Cloudinary via lib/cloudinary)
- **Data Layer**
- Drizzle ORM client (db/drizzle.ts)
- Schema & queries (db/tables/, db/queries/)
- PostgreSQL database
- **External Integrations**
- Google OAuth (NextAuth.js)
- Google Gemini LLM (via Vercel AI SDK)
- Cloudinary (image uploads)
- SMTP server (budget alert emails)

##### Relationships & interactions
- User request → Next.js Router → RSC/Page component
- Page invokes Server Action → executes code in actions/ → calls Drizzle ORM → reads/writes PostgreSQL
- For AI chat: Server Component calls createAI/getMutableAIState → streams response from Google Gemini → UI updates
- Budget alerts: Scheduled or triggered action → lib/mail sends email using templates → user receives notification
- Authentication flows through NextAuth.js API routes → session stored and consumed by providers/session

##### Architectural patterns & principles
- **Colocated UI & backend logic** using Next.js Server Actions
- **Domain-driven structure**: actions/, db/queries/, components/ grouped by feature
- **Provider pattern** for cross-cutting concerns (AI, theme, session)
- **Type safety** across stack (TypeScript, Zod, Drizzle ORM)
- **Parallel/Intercepted routes** for modals & nested flows (AI chat in @ai folder)

- UI components (blue)
- Server logic (green)
- Data layer (orange)
- External services (purple)

##### Detailed breakdown of components
- UI Layer: app/layout.tsx, app/page.tsx, components/ui/*, providers/theme-provider
- Auth: NextAuth.js route, auth/config.ts, providers/session
- Business Actions: actions/transaction.ts, actions/budget.ts, actions/ai/chat.tsx
- DB: db/drizzle.ts, db/schema.ts, db/queries/*.ts
- AI: providers/ai-provider.tsx, config/prompts.ts
- Email: lib/mail.ts, templates/budget-alert.ts
- Storage: lib/cloudinary.ts
- Charts & visuals: components/dashboard/*

##### Detail
- Don’t omit any folder that represents a distinct capability (e.g., hooks/, config/).
- How Server Actions eliminate separate REST layers by embedding logic in the server component runtime.
- How state management flows through Vercel AI SDK hooks (useActionState, getMutableAIState).

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% UI Layer
  subgraph "UI Layer"
    direction TB
    subgraph "Next.js Pages & Layouts"
      direction TB
      Layout["app/layout.tsx"]:::ui
      HomePage["app/page.tsx"]:::ui
      Loading["app/loading.tsx"]:::ui
      NotFound["app/not-found.tsx"]:::ui
      DashLayout["app/dashboard/layout.tsx"]:::ui
      DashPage["app/dashboard/page.tsx"]:::ui
      TxPage["app/dashboard/transactions/page.tsx"]:::ui
      BudPage["app/dashboard/budgets/page.tsx"]:::ui
    end
    subgraph "UI Components"
      direction TB
      UIPrimitives["components/ui/*"]:::ui
      DashComponents["components/dashboard/*"]:::ui
      BudgetComponents["components/budget/*"]:::ui
      TxComponents["components/transaction/*"]:::ui
      SharedComponents["components/app-sidebar.tsx<br>components/auth.tsx<br>components/ai-chat.tsx"]:::ui
    end
  end

  %% Server Layer
  subgraph "Next.js Server"
    direction TB
    Router["Next.js Router"]:::server
    subgraph "Server Actions (Business Logic)"
      direction TB
      ActTx["actions/transaction.ts"]:::server
      ActBud["actions/budget.ts"]:::server
      ActCat["actions/category.ts"]:::server
      ActAlert["actions/alert.ts"]:::server
      ActExport["actions/export.ts"]:::server
      ActUser["actions/user.ts"]:::server
      ActMailAction["actions/mail.ts"]:::server
      ActAIChat["actions/ai/chat.tsx"]:::server
      ActAIRoast["actions/ai/roast.ts"]:::server
    end
    subgraph "Authentication"
      direction TB
      AuthConfig["auth/config.ts"]:::server
      AuthCreds["auth/credentials.ts"]:::server
      AuthIndex["auth/index.ts"]:::server
      NextAuthRoute["app/api/auth/[...nextauth]/route.ts"]:::server
    end
  end

  %% Data Layer
  subgraph "Data Layer"
    direction TB
    DrizzleClient["db/drizzle.ts"]:::data
    Schema["db/schema.ts"]:::data
    TableCreator["db/table-creator.ts"]:::data
    TablesAuth["db/tables/auth.ts"]:::data
    TablesFin["db/tables/finance.ts"]:::data
    QueriesIndex["db/queries/index.ts"]:::data
    QueriesUser["db/queries/user.ts"]:::data
    QueriesFin["db/queries/finance.ts"]:::data
    QueriesAI["db/queries/ai.ts"]:::data
    Postgres["PostgreSQL Database"]:::data
  end

  %% External Services
  subgraph "External Services"
    direction TB
    GoogleOAuth["Google OAuth (NextAuth)"]:::external
    GoogleGemini["Google Gemini LLM"]:::external
    CloudinaryAPI["Cloudinary"]:::external
    SMTPServer["SMTP Email Server"]:::external
  end

  %% Providers & Utilities
  subgraph "Providers & Utilities"
    direction TB
    AIProvider["providers/ai-provider.tsx"]:::server
    ThemeProvider["providers/theme-provider.tsx"]:::server
    SessionProvider["providers/session.tsx"]:::server
    PromptsConfig["config/prompts.ts"]:::server
    MailLib["lib/mail.ts"]:::server
    CloudLib["lib/cloudinary.ts"]:::server
    Helpers["lib/helpers.ts<br>lib/utils.ts"]:::server
    Hooks["hooks/use-mobile.ts<br>hooks/use-scroll-to-bottom.ts"]:::server
  end

  %% Flows
  Layout -->|renders| Router
  HomePage --> Router
  Router -->|serves| Layout
  Router -->|routes requests| DashLayout
  Router -->|routes| NextAuthRoute
  UIPrimitives --> HomePage
  DashComponents --> DashPage
  BudgetComponents --> BudPage
  TxComponents --> TxPage
  SharedComponents --> HomePage

  %% Server Actions invocation
  HomePage -->|invoke action| ActTx
  BudPage -->|invoke action| ActBud
  TxPage -->|invoke action| ActCat
  SharedComponents -->|invoke| ActAIChat
  ActAIChat --> AIProvider
  ActMailAction --> MailLib
  ActMailAction -->|send| SMTPServer
  ActTx --> DrizzleClient
  ActBud --> DrizzleClient
  ActCat --> DrizzleClient
  ActAlert --> DrizzleClient
  ActExport --> DrizzleClient
  ActUser --> DrizzleClient
  QueriesIndex --> DrizzleClient
  DrizzleClient --> Schema
  DrizzleClient --> TableCreator
  DrizzleClient --> TablesAuth
  DrizzleClient --> TablesFin
  DrizzleClient --> QueriesUser
  DrizzleClient --> QueriesFin
  DrizzleClient --> QueriesAI
  DrizzleClient --> Postgres

  %% Auth flow
  HomePage -->|login| NextAuthRoute
  NextAuthRoute --> AuthConfig
  NextAuthRoute --> AuthCreds
  AuthConfig --> GoogleOAuth
  AuthCreds --> GoogleOAuth

  %% AI flow
  ActAIChat --> PromptsConfig
  AIProvider --> GoogleGemini
  SharedComponents -->|use hooks| Hooks

  %% Image Storage
  SharedComponents -->|upload| CloudLib
  CloudLib --> CloudinaryAPI

  %% Providers
  Layout --> ThemeProvider
  Layout --> SessionProvider
  AIProvider --> PromptsConfig

  %% Styles classification
  classDef ui fill:#D0E8FF,stroke:#0366D6,stroke-width:1px
  classDef server fill:#DFF2BF,stroke:#4F8A10,stroke-width:1px
  classDef data fill:#FFE5B4,stroke:#CC8400,stroke-width:1px
  classDef external fill:#E3DFFF,stroke:#662D91,stroke-width:1px

  %% Click events - UI Layer
  click Layout "https://github.com/vimalsaraswat/money-forge/blob/main/app/layout.tsx"
  click HomePage "https://github.com/vimalsaraswat/money-forge/blob/main/app/page.tsx"
  click Loading "https://github.com/vimalsaraswat/money-forge/blob/main/app/loading.tsx"
  click NotFound "https://github.com/vimalsaraswat/money-forge/blob/main/app/not-found.tsx"
  click DashLayout "https://github.com/vimalsaraswat/money-forge/blob/main/app/dashboard/layout.tsx"
  click DashPage "https://github.com/vimalsaraswat/money-forge/blob/main/app/dashboard/page.tsx"
  click TxPage "https://github.com/vimalsaraswat/money-forge/blob/main/app/dashboard/transactions/page.tsx"
  click BudPage "https://github.com/vimalsaraswat/money-forge/blob/main/app/dashboard/budgets/page.tsx"
  click UIPrimitives "https://github.com/vimalsaraswat/money-forge/tree/main/components/ui/"
  click DashComponents "https://github.com/vimalsaraswat/money-forge/tree/main/components/dashboard/"
  click BudgetComponents "https://github.com/vimalsaraswat/money-forge/tree/main/components/budget/"
  click TxComponents "https://github.com/vimalsaraswat/money-forge/tree/main/components/transaction/"
  click SharedComponents "https://github.com/vimalsaraswat/money-forge/blob/main/components/app-sidebar.tsx"
  %% Server Actions
  click ActTx "https://github.com/vimalsaraswat/money-forge/blob/main/actions/transaction.ts"
  click ActBud "https://github.com/vimalsaraswat/money-forge/blob/main/actions/budget.ts"
  click ActCat "https://github.com/vimalsaraswat/money-forge/blob/main/actions/category.ts"
  click ActAlert "https://github.com/vimalsaraswat/money-forge/blob/main/actions/alert.ts"
  click ActExport "https://github.com/vimalsaraswat/money-forge/blob/main/actions/export.ts"
  click ActUser "https://github.com/vimalsaraswat/money-forge/blob/main/actions/user.ts"
  click ActMailAction "https://github.com/vimalsaraswat/money-forge/blob/main/actions/mail.ts"
  click ActAIChat "https://github.com/vimalsaraswat/money-forge/blob/main/actions/ai/chat.tsx"
  click ActAIRoast "https://github.com/vimalsaraswat/money-forge/blob/main/actions/ai/roast.ts"
  %% Auth
  click AuthConfig "https://github.com/vimalsaraswat/money-forge/blob/main/auth/config.ts"
  click AuthCreds "https://github.com/vimalsaraswat/money-forge/blob/main/auth/credentials.ts"
  click AuthIndex "https://github.com/vimalsaraswat/money-forge/blob/main/auth/index.ts"
  click NextAuthRoute "https://github.com/vimalsaraswat/money-forge/blob/main/app/api/auth/[...nextauth]/route.ts"
  %% Data Layer
  click DrizzleClient "https://github.com/vimalsaraswat/money-forge/blob/main/db/drizzle.ts"
  click Schema "https://github.com/vimalsaraswat/money-forge/blob/main/db/schema.ts"
  click TableCreator "https://github.com/vimalsaraswat/money-forge/blob/main/db/table-creator.ts"
  click TablesAuth "https://github.com/vimalsaraswat/money-forge/blob/main/db/tables/auth.ts"
  click TablesFin "https://github.com/vimalsaraswat/money-forge/blob/main/db/tables/finance.ts"
  click QueriesIndex "https://github.com/vimalsaraswat/money-forge/blob/main/db/queries/index.ts"
  click QueriesUser "https://github.com/vimalsaraswat/money-forge/blob/main/db/queries/user.ts"
  click QueriesFin "https://github.com/vimalsaraswat/money-forge/blob/main/db/queries/finance.ts"
  click QueriesAI "https://github.com/vimalsaraswat/money-forge/blob/main/db/queries/ai.ts"
  %% Providers & Utilities
  click AIProvider "https://github.com/vimalsaraswat/money-forge/blob/main/providers/ai-provider.tsx"
  click ThemeProvider "https://github.com/vimalsaraswat/money-forge/blob/main/providers/theme-provider.tsx"
  click SessionProvider "https://github.com/vimalsaraswat/money-forge/blob/main/providers/session.tsx"
  click PromptsConfig "https://github.com/vimalsaraswat/money-forge/blob/main/config/prompts.ts"
  click MailLib "https://github.com/vimalsaraswat/money-forge/blob/main/lib/mail.ts"
  click CloudLib "https://github.com/vimalsaraswat/money-forge/blob/main/lib/cloudinary.ts"
  click Helpers "https://github.com/vimalsaraswat/money-forge/blob/main/lib/helpers.ts"
  click Hooks "https://github.com/vimalsaraswat/money-forge/blob/main/hooks/use-mobile.ts"
```
