Finance Tracker

A personal finance web app for Indian Rupees. Multiple users can register and independently track bank accounts, cash and cards; record income and expenses as they happen; move money between their own accounts; and see balances, savings, trends and reports. All times are shown in the user's time zone (default Asia/Kolkata).

Designed to run entirely on free tiers: Vercel Hobby + MongoDB Atlas Free.

---

1. Features

• Accounts: bank, savings, salary, cash, digital wallet, credit card, other. Opening balance, rename, archive/restore, delete (only when unused), per-account history.
• Expenses: name typed every time, configurable expense type, amount, account, auto-filled date & time (editable for past entries), comment, reference. Search, filter (account / type / date range), sort, paginate, edit, delete with confirmation, details view.
• Income: name, amount, receiving account, auto-filled date & time, comment. Same list tools as expenses.
• Refunds: recorded against an expense and reduce it (₹1,000 − ₹300 refund = ₹700 net). Refunds can be removed; totals recalculate.
• Transfers between your own accounts (written atomically as two linked ledger entries; never income/expense).
• ATM withdrawals: choose "simple" (withdrawal = expense, default) or "detailed" (withdrawal = transfer to a Cash account) in Settings.
• Balance corrections: dated, reasoned, immutable adjustments once an account has entries.
• Dashboard: total balance, period income, expenses, net savings, savings rate, comparison with the previous period, activity chart, spending by type, income by source, balance trend, account balances, recent activity, quick-add buttons.
• Savings: read-only, calculated from real activity, with clear definitions of net savings vs. current balance vs. opening balances vs. cumulative position, plus a 12-month history.
• Reports: today / week / month / quarter / year / custom range, previous-period comparison, breakdowns, account activity, largest expenses, transaction history, CSV export.
• Profile & Settings: name, password change (signs out other devices), currency (INR), time zone, ATM mode, expense-type management, CSV export, delete all financial data, delete account.
• Light/dark/system theme, responsive layout (sidebar on desktop, bottom tabs on phones), toasts, skeletons, empty and error states.

2. Technology

Area	Choice
Framework	Next.js 16 (App Router, Cache Components, Turbopack), React 19, TypeScript (strict)
UI	Tailwind CSS v4, shadcn/ui (Radix), Lucide icons, Recharts, Sonner toasts, next-themes
Forms & validation	React Hook Form + Zod 4 (the same schemas run on client and server)
Backend	Next.js Route Handlers on the Node.js runtime
Database	MongoDB Atlas Free tier via the official mongodb driver (v7)
Auth	Better Auth (email + password) with @better-auth/mongo-adapter. Free, open source, self-hosted, and passwords are hashed by the library
Tests	Vitest (unit tests + integration tests against a real MongoDB test database)

3. Architecture

src/
  app/
    (auth)/login, register          sign-in / sign-up pages
    (app)/dashboard … settings      authenticated pages (Server Components)
    api/…                           Route Handlers (all mutations, export, auth)
  components/
    app/                            shell, navigation, user menu, quick add
    finance/                        forms, dialogs, tables, charts, cards
    settings/                       settings forms
    ui/                             shadcn/ui primitives
  lib/                              client-safe code
    money.ts                        paise parsing/formatting (no floats)
    dates.ts                        time-zone aware periods & buckets
    finance/ledger.ts               THE ledger rules (+ matching Mongo expressions)
    validation/schemas.ts           Zod schemas shared by client and server
  server/                           server-only code
    db/                             Mongo client singleton, collections, indexes
    services/                       business logic (accounts, transactions, reports, export…)
    http.ts                         authenticated route wrapper, error mapping, CSRF check
    session.ts                      verified-session helpers
  proxy.ts                          optimistic redirect for signed-out visitors
tests/unit, tests/integration

• Pages are Server Components. Each page's request-time part sits in a <Suspense> boundary (required by Cache Components); no user data is cached on the server.
• Every Route Handler goes through authedRoute(), which checks the Origin on mutating requests, gets the user from the verified Better Auth session (never from the request body), and turns errors into safe JSON.
• Every query is scoped by userId. Referenced accounts and expense types are loaded with { _id, userId }, so another user's IDs read as 404 Not Found.

Data model (MongoDB)

Better Auth manages user, session, account, verification and rateLimit. The app adds:

Collection	Key fields
financialAccounts	userId, name, nameKey (unique per user), type, openingBalancePaise, currency, isArchived, version, timestamps
transactions (unified ledger)	userId, accountId, type (income · expense · transfer_out · transfer_in · adjustment), amountPaise (positive int), name, categoryId, effectiveAt, createdAt, updatedAt, comment, reference, refundedPaise + refunds[], transferGroupId + counterpartyAccountId, adjustmentDirection + adjustmentReason, isCashWithdrawal, idempotencyKey, version
expenseTypes	userId, name, nameKey (unique per user), isDefault, isArchived, timestamps
userSettings	_id = userId, currency, timezone, cashWithdrawalMode

This is the beginning of the README. Read the rest at the original. Read the full README ↗