CashFlow - Modern Expense Tracker

CashFlow is a premium, feature-rich expense tracking application built with modern web technologies. It helps users manage their finances with a clean, responsive interface, detailed analytics, and seamless cross-device synchronization.

Key Features

• Modern and responsive UI Built with a mobile-first approach using Tailwind CSS v4, featuring glassmorphism, smooth transitions, and a premium aesthetic.

• Secure authentication Google OAuth integration for secure access. Employs a robust JWT refresh token rotation scheme via HTTP-only cookies, paired with a secure local storage fallback to bypass Safari/iOS WebKit third-party cookie blocking (ITP) in standalone PWA installations.

• Interactive dashboard Real-time overview of spending, total incomes, wallet balance, active budget depletion, and charts using Recharts.

• Expense & Income management Full CRUD support for tracking expenses and logging incomes with designated sources.

  • Custom expense categories and income source mapping
  • Date range filters (Today, Week, Month, Custom)
  • Sorting and search capabilities

• Dynamic Budget Tracker Create Monthly Envelope budgets to set an overall spending limit for the month. Optionally allocate specific amounts to categories, with unallocated funds tracked automatically. Expenses are dynamically debited to provide real-time health status bars.

• Dedicated Financial Reports Section Deep-dive analytics dashboard with four sub-modules:

  • Overview: Stats summaries and Day-of-Week spending charts.
  • Categories: Spent breakdown list and category distribution Pie Chart.
  • Trends: Real-time daily spending trend graphs (30 days).
  • Compare: Period-over-period comparisons (e.g. Month vs Last Month) with delta values and grouped bar charts.

• Visual analytics & PDF reports Detailed spending charts and on-demand professional PDF reports. Offloads resource-heavy PDF compilation (jsPDF binary assembly) to a background ES Web Worker, bypassing main-thread UI freezing.

• System-Aware Theme Engine Supports Light, Dark, and System theme selections, dynamically responding to OS-level color scheme preferences in real time.

• PWA and Advanced Offline Sync Progressive Web App functionality with app shortcuts and a standalone PWA mode. Detects webview isolation to trigger Google OAuth redirects (rather than blocked popups), extracting tokens from URL hashes. Custom offline sync engine queues mutations locally, evicts stale entries using FIFO, and reconciles changes securely.

• Real-time data sync & Multi-Tenant Architecture Seamless synchronization across devices using a custom REST API. Implements a highly scalable, user-centric database structure in MongoDB (Mongoose) to ensure strict data isolation and robust security via Express middlewares.

Roadmap / Coming Soon 🚀

• Debt & Borrow Tracker: Keep a running ledger of who owes you and what you owe, integrated naturally with your expense dashboard.
• Group Expenses & Splitting: Share bills with friends, track group spending, and settle up easily using a shared data layer.

Technology Stack

• Frontend framework: React 19
• Build tool: Vite
• Language: TypeScript
• Styling: Tailwind CSS v4
• Backend: Node.js, Express
• Database: MongoDB (Mongoose)
• Icons: Lucide React
• Charts: Recharts
• Routing: React Router v7

Getting Started

Follow these steps to set up the project locally.

Prerequisites

• Node.js v18 or higher
• npm or yarn
• MongoDB Instance (Local or MongoDB Atlas)

Installation

1. Clone the repository

git clone https://github.com/yourusername/expense-tracker.git
cd expense-tracker

2. Setup the Server

cd server
npm install

Create a .env file in the server directory and configure:

PORT=5000
MONGODB_URI=mongodb://localhost:27017/expense-tracker
CLIENT_URL=http://localhost:5173
JWT_SECRET=your_jwt_secret
JWT_REFRESH_SECRET=your_refresh_secret
GOOGLE_CLIENT_ID=your_google_client_id

Tip

MongoDB Atlas Users: If you experience querySrv ECONNREFUSED crashes during local development, your network or ISP may be blocking DNS SRV records. To bypass this, go to your Atlas dashboard -> Connect -> Drivers, toggle off SRV Connection String, and use the provided standard connection string.

Start the server:

npm run dev

3. Setup the Client

Open a new terminal:

cd client
npm install

Create a .env file in the client directory and configure:

VITE_API_URL=http://localhost:5000/api
VITE_GOOGLE_CLIENT_ID=your_google_client_id

Start the client:

npm run dev

4. Open the app Visit http://localhost:5173 in your browser.

Production Deployment & Uptime

When deploying the backend to free-tier hosting services (like Render), the instance may sleep after 15 minutes of inactivity. To prevent cold-start delays, configure a free uptime monitor like cron-job.org to send a GET request to your .../api/health endpoint every 14 minutes (using the cron expression */14 * * * *). This keeps the backend awake and ensures the application remains instantly responsive.

Automated Testing

CashFlow includes comprehensive automated testing across both frontend and backend systems.

Backend Testing

• Jest + Supertest + MongoDB Memory Server
• 69 tests across 8 test suites
• Authentication and JWT validation
• Expense and Income CRUD operations
• Budget validation and unique constraints
• Ownership isolation and access control
• Category and Income Source protections
• Error handling and middleware validation

Frontend Testing

• Vitest + JSDOM + Fake IndexedDB
• 85 tests across 5 test suites
• Offline synchronization engine
• Cache management and eviction logic
• Queue reconciliation and temporary ID mapping
• Budget calculations and health scoring
• Utility functions, formatters, and data mappers

Results

• 154 automated tests passing
• 13 test suites passing

Bugs Discovered Through Testing

• Fixed incorrect category deletion logic (isDefault: false → type: 'custom')
• Fixed income source creation ignoring the frequency field

Scripts

You can run these scripts from within the respective client or server directories.

• npm run dev – Starts the development server
• npm run build – Type-checks and builds the app for production
• npm run lint – Runs ESLint for code quality checks
• npm run test – Runs the comprehensive automated test suites

Project Structure

expense-tracker/
├── client/           # React Frontend
│   ├── src/
│   │   ├── components/  # Dedicated UI hub containing all visual elements
│   │   ├── contexts/    # React Context providers (Auth, Theme)
│   │   ├── pages/       # Top-level route views (Dashboard, Login, Privacy)
│   │   ├── services/    # API integration and export logic
│   │   └── utils/       # Helper utilities and formatters
│   └── vite.config.ts
└── server/           # Express/Node Backend
    ├── src/
    │   ├── controllers/ # Route handlers
    │   ├── middleware/  # Auth, Error handling, Rate limiting
    │   ├── models/      # Mongoose Schemas
    │   ├── routes/      # Express API Routes
    │   └── utils/       # Server utilities
    └── app.ts           # Express App Configuration

Privacy and Terms

The application includes dedicated Privacy Policy and Terms of Service pages. User data is securely stored in MongoDB and is accessible only to the authenticated user via secure JWT tokens.

License

This project is licensed under the MIT License. See the LICENSE file for details.