Expanse Tracker

Modern personal finance cockpit built with Next.js 15, MongoDB, and NextAuth.

Overview

Expanse Tracker helps households record daily spending, drill into patterns, and stay budget aware. The project uses server components and MongoDB for fast reads, while NextAuth keeps sessions secure and shadcn/ui delivers a polished interface.

Features

• Dashboard pulse: Monthly KPIs, daily total, quick add, and a recent activity feed so you can capture and review spending in one screen.
• Expense ledger: Search, inline edit or delete, and paginate through transactions with React Hook Form validation backing the data entry flow.
• Interactive calendar: Navigate month to month, drill into any day, and log expenses directly from the calendar while keeping category context in view.
• Analytics workspace: Monthly and yearly reports with category pie charts, daily trends, fixed versus variable comparisons, CSV export, and year over year highlights.
• Category library and preferences: Build custom categories, reuse the shared defaults, and set a workspace default currency that propagates across dashboards and forms.
• Authentication and theming: Email and password sign in via NextAuth, responsive layouts, and a dark or light theme toggle powered by shadcn/ui primitives and Tailwind CSS.

Product Flow

flowchart TD
    U[Authenticated user] --> DSH[Dashboard]
    DSH --> ADD[Quick add expense]
    ADD --> API_POST[POST /api/expenses]
    API_POST --> DB[(MongoDB)]
    DB --> KPI[Monthly KPIs]
    KPI --> DSH
    DB --> LEDGER[Expense ledger]
    LEDGER --> EDIT[Edit or delete expense]
    EDIT --> API_MUTATE[PATCH or DELETE /api/expenses/:id]
    API_MUTATE --> DB
    DB --> CAL[Calendar view]
    DB --> REPORTS[Monthly and yearly reports]
    U --> PREF[Preferences]
    PREF --> API_PREF[PATCH /api/settings/preferences]
    API_PREF --> DB

Tech Stack

| Area | Tools | | --- | --- | | Framework | Next.js 15 (App Router), React 19 | | Language | TypeScript | | Database | MongoDB with Mongoose | | Authentication | NextAuth 5 with credential flow | | UI and Styling | Tailwind CSS, shadcn/ui, Radix primitives, Framer Motion | | Forms and Validation | React Hook Form, Zod | | Charts | Recharts | | Notifications | Sonner |

Quick Start

1. Ensure you have Node.js 18 or newer and access to a MongoDB instance (Atlas or local).

2. Clone the repository and install dependencies:

   git clone <repo-url>
   cd expanse-tracker
   npm install
   

3. Create .env.local in the project root and copy the contents of .env (or define the variables yourself). Update the values:

   • MONGODB_URI should point to your database.
   • NEXTAUTH_SECRET can be generated with openssl rand -base64 32.
   • NEXTAUTH_URL defaults to http://localhost:3000 during development.
   • BLOB_READ_WRITE_TOKEN is optional and only needed if you enable receipt uploads via Vercel Blob.

4. Run the development server:

   npm run dev
   

   Visit http://localhost:3000 to view the app.

5. (Optional) Seed the database with demo data. This resets existing data and creates demo@example.com with password password123:

   npx tsx scripts/seed.ts
   

Useful Scripts

• npm run dev - start the development server.
• npm run build - create a production build.
• npm run start - run the production server.
• npm run lint - lint the codebase.
• npx tsx scripts/seed.ts - seed demo data (destroys existing records for the target database).

Project Structure

.
|-- app/
|   |-- api/               # Next.js API routes (authentication, expenses, settings)
|   |-- calendar/          # Calendar month view and drill-down pages
|   |-- categories/        # Category management UI
|   |-- dashboard/         # Authenticated landing dashboard
|   |-- expenses/          # Expense ledger with search and pagination
|   |-- reports/           # Monthly and yearly analytics pages
|   |-- settings/          # User preferences
|   `-- layout.tsx         # Root layout
|-- components/
|   |-- calendar/          # Calendar grid and day detail components
|   |-- categories/        # Category dialogs and manager
|   |-- dashboard/         # Dashboard widgets
|   |-- expenses/          # Expense list, dialogs, and table
|   |-- layout/            # App shell and navigation
|   |-- reports/           # Charting components for analytics
|   |-- settings/          # Currency preference form
|   `-- ui/                # shadcn/ui wrappers
|-- lib/
|   |-- auth/              # NextAuth configuration
|   |-- constants/         # Currency and other shared constants
|   |-- db/                # Database connection and models
|   |-- utils/             # Helpers for formatting and dates
|   `-- validations/       # Zod schemas
|-- public/                # Static assets
|-- scripts/               # Maintenance scripts (seed)
`-- package.json

Environment Variables

| Variable | Description | Required | | --- | --- | --- | | MONGODB_URI | MongoDB connection string | Yes | | NEXTAUTH_URL | Base URL for NextAuth callbacks | Yes | | NEXTAUTH_SECRET | Secret used to sign sessions | Yes | | BLOB_READ_WRITE_TOKEN | Vercel Blob token for receipt uploads | No |

License

Released under the MIT License.