# hargun-preet/budgetly architecture

> Architecture diagram of the GitHub repository hargun-preet/budgetly, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/hargun-preet/budgetly
- Repository: https://github.com/hargun-preet/budgetly

## Overview

Budgetly is a personal-finance web app for recording income and expenses, setting category budgets, and reviewing financial summaries and history. Users enter the app through Clerk authentication, then configure settings and use the dashboard or transaction views; receipt scanning offers an AI-assisted entry path. The graph highlights the documented product areas and the sampled API-to-service and API-to-database interactions. Several UI components, server actions, and routes are present in the tree but were not sampled, so their internal wiring is not asserted.

Main entry points: [`lib/prisma.ts`](https://github.com/hargun-preet/budgetly/blob/main/lib/prisma.ts) (Prisma client), [`app/api/user-settings/route.ts`](https://github.com/hargun-preet/budgetly/blob/main/app/api/user-settings/route.ts) (User settings API), [`app/api/categories/route.ts`](https://github.com/hargun-preet/budgetly/blob/main/app/api/categories/route.ts) (Category API), [`app/api/scan-receipt/route.ts`](https://github.com/hargun-preet/budgetly/blob/main/app/api/scan-receipt/route.ts) (Receipt scanning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and setup"]
  node_auth["Sign in and sign up<br/>[page.tsx]"]
  node_wizard["Settings setup<br/>[page.tsx]"]
  node_settings["User settings API<br/>[route.ts]"]
end

subgraph group_money["Transactions and categories"]
  node_transactions["Transaction manager<br/>[page.tsx]"]
  node_transactionactions["Transaction actions<br/>[transactions.ts]"]
  node_categories["Category API<br/>[route.ts]"]
  node_receipt["Receipt scanning<br/>[route.ts]"]
end

subgraph group_insights["Budgets and insights"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_overview["Overview panels<br/>[Overview.tsx]"]
  node_budgetstats["Budget statistics<br/>[route.ts]"]
  node_balancestats["Balance statistics<br/>[route.ts]"]
  node_categorystats["Category statistics<br/>[route.ts]"]
  node_historyui["History view<br/>[History.tsx]"]
  node_historydata["History data API<br/>[route.ts]"]
  node_periods["History periods API<br/>[route.ts]"]
end

subgraph group_services["Backend services"]
  node_cron["Budget reset endpoint<br/>[route.ts]"]
  node_budgetlib["Budget reset logic<br/>[budget.ts]"]
  node_clerk{{"Clerk authentication"}}
  node_gemini{{"Gemini AI"}}
  node_prisma["Prisma client<br/>[prisma.ts]"]
  node_database[("Application database")]
end

node_user(("User"))

node_user -->|"signs in"| node_auth
node_user -->|"uses"| node_dashboard
node_user -->|"manages"| node_transactions
node_auth -->|"authenticates with"| node_clerk
node_wizard -->|"configures"| node_settings
node_settings -->|"identifies user"| node_clerk
node_settings -->|"reads and creates"| node_prisma
node_prisma -->|"queries"| node_database
node_budgetstats -->|"identifies user"| node_clerk
node_budgetstats -->|"queries"| node_prisma
node_balancestats -->|"identifies user"| node_clerk
node_balancestats -->|"queries"| node_prisma
node_categorystats -->|"identifies user"| node_clerk
node_categorystats -->|"queries"| node_prisma
node_historydata -->|"identifies user"| node_clerk
node_historydata -->|"queries"| node_prisma
node_periods -->|"identifies user"| node_clerk
node_periods -->|"queries"| node_prisma
node_categories -->|"identifies user"| node_clerk
node_categories -->|"queries"| node_prisma
node_receipt -->|"identifies user"| node_clerk
node_receipt -->|"submits receipt image"| node_gemini
node_cron -->|"calls reset"| node_budgetlib

click node_auth "https://github.com/hargun-preet/budgetly/blob/main/app/(auth)/sign-in/%5B%5B...sign-in%5D%5D/page.tsx"
click node_wizard "https://github.com/hargun-preet/budgetly/blob/main/app/wizard/page.tsx"
click node_settings "https://github.com/hargun-preet/budgetly/blob/main/app/api/user-settings/route.ts"
click node_dashboard "https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/page.tsx"
click node_overview "https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_components/Overview.tsx"
click node_budgetstats "https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/budget/route.ts"
click node_balancestats "https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/balance/route.ts"
click node_categorystats "https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/categories/route.ts"
click node_historyui "https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_components/History.tsx"
click node_historydata "https://github.com/hargun-preet/budgetly/blob/main/app/api/history-data/route.ts"
click node_periods "https://github.com/hargun-preet/budgetly/blob/main/app/api/history-periods/route.ts"
click node_transactions "https://github.com/hargun-preet/budgetly/blob/main/app/transactions/page.tsx"
click node_transactionactions "https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_actions/transactions.ts"
click node_categories "https://github.com/hargun-preet/budgetly/blob/main/app/api/categories/route.ts"
click node_receipt "https://github.com/hargun-preet/budgetly/blob/main/app/api/scan-receipt/route.ts"
click node_cron "https://github.com/hargun-preet/budgetly/blob/main/app/api/cron/reset-budgets/route.ts"
click node_budgetlib "https://github.com/hargun-preet/budgetly/blob/main/lib/budget.ts"
click node_prisma "https://github.com/hargun-preet/budgetly/blob/main/lib/prisma.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_auth,node_wizard,node_settings,node_user toneBlue
class node_transactions,node_transactionactions,node_categories,node_receipt toneAmber
class node_dashboard,node_overview,node_budgetstats,node_balancestats,node_categorystats,node_historyui,node_historydata,node_periods toneMint
class node_cron,node_budgetlib,node_clerk,node_gemini,node_prisma,node_database toneRose
```

## Components

### Entry and setup

- [Sign in and sign up](https://github.com/hargun-preet/budgetly/blob/main/app/(auth)/sign-in/%5B%5B...sign-in%5D%5D/page.tsx): `app/(auth)/sign-in/[[...sign-in]]/page.tsx`
- [Settings setup](https://github.com/hargun-preet/budgetly/blob/main/app/wizard/page.tsx): `app/wizard/page.tsx`
- [User settings API](https://github.com/hargun-preet/budgetly/blob/main/app/api/user-settings/route.ts): `app/api/user-settings/route.ts`

### Transactions and categories

- [Transaction manager](https://github.com/hargun-preet/budgetly/blob/main/app/transactions/page.tsx): `app/transactions/page.tsx`
- [Transaction actions](https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_actions/transactions.ts): `app/dashboard/_actions/transactions.ts`
- [Category API](https://github.com/hargun-preet/budgetly/blob/main/app/api/categories/route.ts): `app/api/categories/route.ts`
- [Receipt scanning](https://github.com/hargun-preet/budgetly/blob/main/app/api/scan-receipt/route.ts): `app/api/scan-receipt/route.ts`

### Budgets and insights

- [Dashboard](https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/page.tsx): `app/dashboard/page.tsx`
- [Overview panels](https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_components/Overview.tsx): `app/dashboard/_components/Overview.tsx`
- [Budget statistics](https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/budget/route.ts): `app/api/stats/budget/route.ts`
- [Balance statistics](https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/balance/route.ts): `app/api/stats/balance/route.ts`
- [Category statistics](https://github.com/hargun-preet/budgetly/blob/main/app/api/stats/categories/route.ts): `app/api/stats/categories/route.ts`
- [History view](https://github.com/hargun-preet/budgetly/blob/main/app/dashboard/_components/History.tsx): `app/dashboard/_components/History.tsx`
- [History data API](https://github.com/hargun-preet/budgetly/blob/main/app/api/history-data/route.ts): `app/api/history-data/route.ts`
- [History periods API](https://github.com/hargun-preet/budgetly/blob/main/app/api/history-periods/route.ts): `app/api/history-periods/route.ts`

### Backend services

- [Budget reset endpoint](https://github.com/hargun-preet/budgetly/blob/main/app/api/cron/reset-budgets/route.ts): `app/api/cron/reset-budgets/route.ts`
- [Budget reset logic](https://github.com/hargun-preet/budgetly/blob/main/lib/budget.ts): `lib/budget.ts`
- **Clerk authentication**
- **Gemini AI**
- [Prisma client](https://github.com/hargun-preet/budgetly/blob/main/lib/prisma.ts): `lib/prisma.ts`
- **Application database**

### Other components

- **User**

## Connections

- User → Sign in and sign up: signs in
- User → Dashboard: uses
- User → Transaction manager: manages
- Sign in and sign up → Clerk authentication: authenticates with
- Settings setup → User settings API: configures
- User settings API → Clerk authentication: identifies user
- User settings API → Prisma client: reads and creates
- Prisma client → Application database: queries
- Budget statistics → Clerk authentication: identifies user
- Budget statistics → Prisma client: queries
- Balance statistics → Clerk authentication: identifies user
- Balance statistics → Prisma client: queries
- Category statistics → Clerk authentication: identifies user
- Category statistics → Prisma client: queries
- History data API → Clerk authentication: identifies user
- History data API → Prisma client: queries
- History periods API → Clerk authentication: identifies user
- History periods API → Prisma client: queries
- Category API → Clerk authentication: identifies user
- Category API → Prisma client: queries
- Receipt scanning → Clerk authentication: identifies user
- Receipt scanning → Gemini AI: submits receipt image
- Budget reset endpoint → Budget reset logic: calls reset