Expense Tracker

A full-stack personal finance application for tracking daily spending, managing budgets, sharing group wallets, and staying on top of bills — built with TypeScript, React, Express, PostgreSQL, and Firebase Auth.

---

Table of Contents

• Features
• Tech Stack
• Architecture
• Project Structure
• Authentication & Authorization
• System Design
  • Data Flow
  • API Design
  • Storage Layer
  • Idempotency
  • Deployment Model
• Modules
  • Expenses
  • Budgets
  • Shared Wallets
  • Notifications & Alerts
  • Bill Reminders
  • Dashboard
  • AI Chatbot & MCP Server
• Environment Variables
• Getting Started
• Scripts
• Screenshots

---

Features

• Personal expenses — Create, edit, delete, filter by category, and sort by date. Idempotent submission prevents duplicates on retry.
• Budgets — Set monthly or category-specific spending caps. Track remaining budget with overspend warnings.
• Shared wallets — Create group wallets for trips, homes, or shared budgets. Invite members, split expenses (equal, fixed, percentage), track balances, and record settlements. Each wallet supports its own independent default currency preference with transaction-safe backend conversions.
• Dashboard — Unified overview with spending trends, category breakdowns, budget tracking, and auto-generated insights. Toggle between personal and wallet data sources. Automatically maps and visualizes converted currency amounts seamlessly.
• Notifications & alerts — Budget threshold warnings, overspend alerts, daily logging reminders, bill due alerts, and wallet invite notifications. Timezone-aware scheduler ensures notifications deliver relative to the user's chosen local time.
• Bill reminders — Schedule recurring bill reminders (once, weekly, monthly, yearly) with configurable advance notice.
• Social authentication — Sign in with Google, GitHub, or Facebook via Firebase Auth.
• Account management & profile editing — Profile customization menu supporting custom usernames (with strict database uniqueness validation), local profile picture uploading (with auto-compression to avoid Firebase Auth attribute limits), OAuth provider avatar restoration, regional default currency and timezone selections, and full account/data deletion.
• In-App AI Chatbot — Interactive finance assistant scoped strictly to user expenses and wallets. Features semantic query searching across your entire transaction history. Prompts are monitored by strict guardrails, tool outputs are recursively sanitized to prevent prompt injections, and conversation histories are bounded to control costs. Incorporates a human-in-the-loop approval confirmation dialog for write operations (such as expense creation) and self-healing rate limit retry handlers.
• Receipt Scanning (OCR) — Upload single or multiple receipt photos to automatically extract details (merchant, amount, category, date, item breakdown description) in real-time, pre-filling a draft transaction form (personal or wallet) for user review. Validated by file magic-byte signatures and redacted for credit card numbers.
• Model Context Protocol (MCP) Server — Connect external tools (Cursor, Claude Desktop, etc.) to your expense tracker data using the standard Streamable HTTP SSE transport. Exposes semantic search (search_expenses_semantic) and structured retrieval tools, secured via user-managed SHA-256 hashed personal access tokens.

---

Tech Stack

Layer	Technology
Frontend	React 19, TypeScript, Vite, Tailwind CSS v4
Backend	Node.js, TypeScript, Express (local dev)
Production	Vercel Serverless Functions (API routes under api/)
Database	PostgreSQL with pgvector extension via postgres npm package
Auth Client	Firebase Auth (signInWithPopup for Google, GitHub, Facebook)
Auth Server	Firebase Admin SDK (ID token verification)
Testing	Vitest (backend unit tests with in-memory store)
AI Inference	Llama 3.1 70B (NVIDIA NIM) & Gemini 2.5 Flash / Embeddings
MCP Transport	Server-Sent Events (SSE) + HTTP POST JSON-RPC 2.0
Monorepo	npm workspaces (backend/, frontend/)

---

Architecture

┌───────────────────────────────────────────────────────────────┐
│                        Client (Browser)                       │
│                                                               │
│  React SPA ── Firebase Auth ── fetch("/api/...")              │
│  Vite Dev Server (port 5173) proxies /api → localhost:4101   │
└──────────────┬────────────────────────────────────────────────┘
               │  Authorization: Bearer <Firebase ID Token>
               ▼
┌───────────────────────────────────────────────────────────────┐
│                     API Layer                                 │
│                                                               │
│  Local:  Express server (port 4101)                          │
│  Prod:   Vercel Serverless Functions (api/*.js)              │
│                                                               │
│  ┌─────────────┐   ┌──────────────┐   ┌──────────────────┐  │
│  │ auth.ts     │   │ http.ts      │   │ lib/validation   │  │
│  │ Firebase    │──▶│ Handler fns  │◀──│ Zod schemas      │  │
│  │ Admin verify│   │ (pure logic) │   └──────────────────┘  │
│  └─────────────┘   └──────┬───────┘                          │
│                            │                                  │
│                    ┌───────▼────────┐                         │
│                    │  store/        │                         │
│                    │  ├ types.ts    │  ExpenseStore interface │
│                    │  ├ postgres.ts │  Production impl       │
│                    │  └ memory.ts   │  Test impl             │
│                    └───────┬────────┘                         │
└────────────────────────────┼──────────────────────────────────┘
                             │
                    ┌────────▼────────┐
                    │   PostgreSQL    │
                    │ (hosted/cloud)  │
                    └─────────────────┘

---

Project Structure

expense-tracker/
├── api/                          # Vercel serverless entry points
│   ├── expenses.js               #   /api/expenses[/:id]
│   ├── budgets.js                #   /api/budgets[/:id]
│   ├── wallets.js                #   /api/wallets[/:id/...]
│   ├── notifications.js          #   /api/notifications[/:id/...]
│   ├── bill-reminders.js         #   /api/bill-reminders[/:id]
│   ├── wallet-invites.js         #   /api/wallet-invites[/:id/respond]
│   ├── reminder-preferences.js   #   /api/reminder-preferences
│   ├── account.js                #   /api/account
│   ├── health.js                 #   /api/health
│   └── _lib/                     #   Shared serverless utilities
│
├── backend/                      # Express backend (npm workspace)
│   ├── src/
│   │   ├── server.ts             #   Dev server entry (port 4101)
│   │   ├── app.ts                #   Express app factory with all routes
│   │   ├── auth.ts               #   Firebase Admin token verification
│   │   ├── http.ts               #   Pure handler functions
│   │   ├── lib/
│   │   │   └── validation.ts     #   Zod request schemas
│   │   └── store/
│   │       ├── types.ts          #   ExpenseStore interface & record types
│   │       ├── postgres.ts       #   PostgreSQL implementation
│   │       └── memory.ts         #   In-memory implementation (tests)
│   └── test/
│       └── expenses.test.ts      #   Vitest test suite
│
├── frontend/                     # React frontend (npm workspace)
│   ├── src/
│   │   ├── main.tsx              #   App entry point
│   │   ├── App.tsx               #   Root component (routing, state, API)
│   │   ├── auth.ts               #   Firebase Auth client setup
│   │   ├── types.ts              #   Shared TypeScript types
│   │   ├── styles.css            #   Tailwind v4 + custom theme
│   │   ├── pages/
│   │   │   ├── LandingPage.tsx   #   Pre-auth landing
│   │   │   ├── AuthPage.tsx      #   Sign-in with social providers
│   │   │   ├── DashboardPage.tsx #   Stats, budgets, trends, insights
│   │   │   ├── ExpensesPage.tsx  #   CRUD expenses with filters
│   │   │   ├── WalletsPage.tsx   #   Shared wallets management
│   │   │   └── AlertsPage.tsx    #   Notifications & bill reminders
│   │   ├── components/
│   │   │   ├── ui.tsx            #   Design system primitives
│   │   │   ├── BudgetTrackerSection.tsx
│   │   │   ├── CategoryIcon.tsx
│   │   │   ├── NotificationCenter.tsx
│   │   │   ├── ProfileMenu.tsx
│   │   │   ├── ConfirmModal.tsx
│   │   │   ├── AlertsSurface.tsx
│   │   │   └── ProviderLogo.tsx
│   │   └── layouts/
│   │       └── SignedInLayout.tsx #   App shell (nav, bottom tabs, profile)
│   └── vite.config.ts            #   Vite + Tailwind + dev proxy
│
├── images/                       # Application screenshots
├── vercel.json                   # Vercel deployment config & rewrites
├── package.json                  # Root workspace config
└── .env.example                  # Environment variable template

---

Authentication & Authorization

Sign-In Flow

User clicks "Sign in" ──▶ Firebase Auth popup (Google / GitHub / Facebook)
                                    │
                                    ▼
                          Firebase returns ID token
                                    │
                  ┌─────────────────┼─────────────────┐
                  ▼                                    ▼
          Stored in browser                   Sent as Bearer token
          (browserLocalPersistence)            on every API request
                                                       │
                                                       ▼
                                              Backend verifies token
                                              via Firebase Admin SDK
                                                       │
                                                       ▼
                                              Extracts user.id (UID),
                                              email, name, picture
                                                       │
                                                       ▼
                                              All queries scoped to UID

Key Details

• Client-side: Firebase Auth with signInWithPopup and browserLocalPersistence. The onAuthStateChanged listener detects login state on page load.
• Server-side: Every API route passes through withAuthenticatedUser(), which decodes the Authorization: Bearer <token> header using firebase-admin. Unauthenticated requests receive a 401.
• Data isolation: All database queries include the authenticated userId in their WHERE clauses. Users can only access their own expenses, budgets, and notifications.
• Wallet access: Wallet data is accessible to all linked members (not just the owner). The backend checks membership via wallet_members before returning wallet details.
• Account deletion: `DELETE