💰 Personal Finance Tracker

A modern, full-stack personal finance management application built with Next.js 15, TypeScript, and Supabase. Track your income, expenses, and financial goals with beautiful analytics and insights tailored for Sri Lankan users.

🌟 Features

🔐 Authentication System

User Registration & Login - Secure authentication with form validation using Zod schemas
Protected Routes - Automatic redirection for unauthorized access with ProtectedRoute component
Session Management - Persistent login state with localStorage and React Context
Professional UI - Clean, modern authentication forms with error handling
Demo Mode - Quick demo access for testing (email: any@email.com, password: 6+ chars)

📊 Financial Management

Transaction Tracking - Add, edit, delete income and expense transactions with full CRUD operations
Category Management - 40+ pre-defined Sri Lankan categories with emojis and color coding
Real-time Dashboard - Live financial overview with key metrics and recent transactions
Advanced Filtering - Filter transactions by type, category, date range, and description
Sri Lankan Context - LKR currency, local categories (Rice & Curry, CEB Bills, Dialog/Mobitel, etc.)
Data Validation - Form validation with Zod for data integrity and user experience

📈 Analytics & Insights

Interactive Charts - Beautiful pie charts and bar graphs using Recharts
Expense Breakdown - Visual representation of spending by category
Income Analysis - Track income sources and patterns
Monthly Trends - Historical data visualization for the last 6 months
Financial Summaries - Total income, expenses, and net balance

🎨 User Experience

Responsive Design - Optimized for desktop, tablet, and mobile devices
Modern UI Components - Custom-built components with TailwindCSS
Loading States - Smooth loading indicators and error handling
Sri Lankan Context - LKR currency and localized categories

🛠️ Tech Stack

Frontend

Next.js 15.3.3 - React framework with App Router and Turbopack
React 19.0.0 - Latest React with concurrent features
TypeScript 5.8.3 - Type-safe JavaScript with strict mode
TailwindCSS 4.1.10 - Utility-first CSS framework with custom theme
Recharts 2.15.3 - Composable charting library for data visualization
Lucide React 0.514.0 - Beautiful SVG icon library
Date-fns 4.1.0 - Modern JavaScript date utility library
Zod 3.25.63 - TypeScript-first schema validation

Backend & Database

Supabase - PostgreSQL database with real-time features and REST API
Supabase Auth - Authentication and user management with JWT
Supabase Auth Helpers - Next.js integration for seamless auth
Row Level Security (RLS) - Database-level security policies for data isolation
PostgreSQL - Robust relational database with ACID compliance

Development Tools

ESLint 9 - Code linting with Next.js and TypeScript rules
PostCSS 8.5.5 - CSS processing with Tailwind integration
Autoprefixer 10.4.21 - CSS vendor prefixing for browser compatibility

🚀 Getting Started

Prerequisites

Node.js 18+ and npm/yarn/pnpm
Supabase account and project

1. Clone the Repository

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

2. Install Dependencies

npm install
# or
yarn install
# or
pnpm install

3. Environment Setup

Create a .env.local file in the root directory:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

4. Database Setup

Run the SQL scripts in your Supabase Dashboard → SQL Editor in this order:

Initial Setup: Execute database-setup.sql
- Creates categories and transactions tables
- Sets up Row Level Security (RLS) policies
- Creates indexes for optimal performance
- Inserts 40+ Sri Lankan categories
RLS Policy Fixes (if needed): Execute fix-rls-policies.sql
- Fixes any RLS policy issues for development
- Allows demo data access
- Configures proper user permissions

5. Start Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

Open http://localhost:3000 to view the application.

📁 Project Structure

personal-finance-tracker/
├── src/
│   ├── app/                    # Next.js 15 App Router pages
│   │   ├── analytics/         # Analytics dashboard with charts
│   │   │   └── page.tsx       # Analytics page component
│   │   ├── dashboard/         # Main financial dashboard
│   │   │   └── page.tsx       # Dashboard overview
│   │   ├── login/            # Authentication pages
│   │   │   └── page.tsx      # Login form
│   │   ├── register/         # User registration
│   │   │   └── page.tsx      # Registration form
│   │   ├── transactions/     # Transaction management
│   │   │   ├── add/          # Add new transaction
│   │   │   │   └── page.tsx  # Transaction form
│   │   │   ├── [id]/         # Dynamic transaction routes
│   │   │   │   └── edit/     # Edit transaction
│   │   │   │       └── page.tsx
│   │   │   └── page.tsx      # Transaction list
│   │   ├── globals.css       # Global styles with Tailwind
│   │   ├── layout.tsx        # Root layout with providers
│   │   └── page.tsx          # Landing page
│   ├── components/            # Reusable UI components
│   │   ├── ui/               # Base UI components
│   │   │   ├── Button.tsx    # Custom button variants
│   │   │   ├── Card.tsx      # Container component
│   │   │   └── Input.tsx     # Form input with validation
│   │   ├── Header.tsx        # Navigation header
│   │   └── ProtectedRoute.tsx # Route protection HOC
│   ├── contexts/             # React Context providers
│   │   └── AuthContext.tsx   # Authentication state management
│   ├── lib/                  # Utility libraries
│   │   ├── supabase.ts      # Supabase client & database types
│   │   ├── utils.ts         # Helper functions
│   │   ├── validations.ts   # Zod validation schemas
│   │   └── sri-lankan-data.ts # Local data and constants
│   └── types/               # TypeScript type definitions
│       └── transaction.ts   # Transaction-related interfaces
├── public/                   # Static assets
│   ├── favicon.ico          # App favicon
│   └── *.svg               # Icon assets
├── database-setup.sql       # Initial database schema
├── fix-rls-policies.sql    # RLS policy configurations
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── next.config.ts          # Next.js configuration
├── postcss.config.mjs      # PostCSS configuration
├── eslint.config.mjs       # ESLint configuration
└── README.md              # Project documentation

🗄️ Database Schema

Categories Table

CREATE TABLE categories (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  name VARCHAR(100) NOT NULL,
  icon VARCHAR(10) NOT NULL,
  color VARCHAR(7) NOT NULL,
  type VARCHAR(10) CHECK (type IN ('income', 'expense')),
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

Transactions Table

CREATE TABLE transactions (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  user_id UUID REFERENCES auth.users(id) ON DELETE CASCADE,
  amount DECIMAL(12,2) NOT NULL CHECK (amount > 0),
  type VARCHAR(10) NOT NULL CHECK (type IN ('income', 'expense')),
  category_id UUID REFERENCES categories(id),
  description TEXT NOT NULL,
  date DATE NOT NULL,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
  updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

🔧 Key Components

Authentication Context

Manages user authentication state across the application:

Login/logout functionality
User session persistence
Protected route access control

Database Layer

Abstracted database operations with TypeScript:

CRUD operations for transactions
Category management
Analytics data aggregation
Type-safe database queries

UI Components

Reusable, accessible components:

Button: Multiple variants and sizes
Card: Consistent container styling
Input: Form inputs with validation
Header: Navigation with user context

📊 Analytics Features

Dashboard Metrics

Total income and expenses
Current balance calculation
Transaction count
Recent transactions list

Visual Analytics

Pie Charts: Expense and income breakdown by category
Bar Charts: Monthly trends over time
Category Lists: Detailed breakdown with percentages
Time Filtering: View data for different time periods

🔒 Security Features

Authentication & Authorization

Form Validation - Client-side validation with Zod schemas and server-side verification
Password Security - Minimum 6 characters requirement with secure hashing
Session Management - JWT-based authentication with automatic token refresh
Protected Routes - Route-level protection with automatic redirects
User Context - Secure user state management with React Context API

Database Security

Row Level Security (RLS) - PostgreSQL RLS policies ensuring users only access their own data
User Isolation - UUID-based user identification with foreign key constraints
SQL Injection Prevention - Parameterized queries and Supabase client protection
Secure API Endpoints - Server-side validation and authentication checks
Data Encryption - Encrypted data transmission with HTTPS and secure storage

Privacy & Compliance

Data Minimization - Only collect necessary financial data
User Control - Users can delete their own transactions and data
Secure Storage - Encrypted database storage with Supabase infrastructure
No Third-party Tracking - Privacy-focused design without external analytics

🎨 Design System

Color Palette

Primary: Blue (#3B82F6)
Success: Green (#10B981)
Danger: Red (#EF4444)
Warning: Yellow (#F59E0B)
Neutral: Gray scale

Typography

Font: Geist Sans (Vercel's font family)
Headings: Bold, hierarchical sizing
Body: Regular weight, readable line height

Components

Consistent spacing using Tailwind's scale
Rounded corners and subtle shadows
Hover and focus states for interactivity
Mobile-first responsive design

🚀 Deployment

Vercel (Recommended)

Connect Repository: Link your GitHub repository to Vercel

Environment Variables: Add the following in Vercel dashboard:

NEXT_PUBLIC_SUPABASE_URL=your_supabase_project_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

Auto Deploy: Automatic deployment on push to main branch
Custom Domain: Configure custom domain in Vercel settings

Manual Deployment

# Build the application
npm run build

# Start production server
npm run start

# Or using PM2 for production
npm install -g pm2
pm2 start npm --name "finance-tracker" -- start

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

🧪 Testing

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Test Structure

Unit Tests - Component and utility function testing
Integration Tests - API endpoint and database operation testing
E2E Tests - Full user workflow testing with Playwright

📊 Performance

Optimization Features

Next.js 15 - Latest performance optimizations and Turbopack
Image Optimization - Automatic image optimization with Next.js Image component
Code Splitting - Automatic code splitting for optimal loading
Static Generation - Pre-rendered pages for better performance
Database Indexing - Optimized database queries with proper indexing

Monitoring

Core Web Vitals - Optimized for Google's Core Web Vitals
Bundle Analysis - Regular bundle size monitoring
Database Performance - Query optimization and connection pooling

🤝 Contributing

We welcome contributions! Please follow these steps:

Development Setup

Fork the repository and clone your fork
Install dependencies: npm install
Set up environment: Copy .env.example to .env.local
Database setup: Run the SQL scripts in Supabase
Start development: npm run dev

Contribution Guidelines

Create a feature branch: git checkout -b feature/amazing-feature
Follow code style: Use ESLint and Prettier configurations
Write tests: Add tests for new features
Update documentation: Update README if needed
Commit changes: Use conventional commit messages
Push to branch: git push origin feature/amazing-feature
Open Pull Request: Provide clear description of changes

Code Style

Use TypeScript for all new code
Follow ESLint and Prettier configurations
Use meaningful variable and function names
Add JSDoc comments for complex functions
Maintain consistent file structure

🐛 Troubleshooting

Common Issues

Database Connection Issues

# Check environment variables
echo $NEXT_PUBLIC_SUPABASE_URL
echo $NEXT_PUBLIC_SUPABASE_ANON_KEY

# Verify Supabase connection
npm run test:db

Build Errors

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check TypeScript errors
npm run type-check

Authentication Issues

Verify Supabase Auth is enabled
Check RLS policies are correctly configured
Ensure environment variables are set correctly

Version History

v0.1.0 - Initial release with basic transaction tracking
v0.2.0 - Added analytics and charts
v0.3.0 - Enhanced security and authentication
v1.0.0 - Production-ready release (planned)

� Acknowledgments

Next.js - For the amazing React framework with App Router
Supabase - For the powerful backend infrastructure and PostgreSQL
TailwindCSS - For the utility-first CSS framework
Recharts - For the beautiful and responsive charting library
Lucide - For the comprehensive icon library
Vercel - For the seamless deployment platform
TypeScript - For type safety and developer experience
Sri Lankan Developer Community - For inspiration and local context

Demo

Supabase

⭐ Star this repository if you found it helpful!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
public		public
src/app		src/app
.gitignore		.gitignore
README.md		README.md
eslint.config.mjs		eslint.config.mjs
next.config.ts		next.config.ts
package-lock.json		package-lock.json
package.json		package.json
postcss.config.mjs		postcss.config.mjs
tsconfig.json		tsconfig.json

Dewick75/personal-finance-tracker

Folders and files

Latest commit

History

Repository files navigation