💰 Finance SaaS Platform

A comprehensive expense tracker and financial management platform

📋 Table of Contents

• Overview
• Key Features
• Tech Stack
• Getting Started
• Environment Variables
• Database Setup
• Project Structure
• API Documentation
• Contributing
• License

🌟 Overview

Finance SaaS Platform is a modern, full-stack financial management application built with Next.js 14. It helps users track income and expenses, categorize transactions, connect bank accounts via Plaid, and gain insights through interactive dashboards and charts. The platform features a premium subscription model powered by Lemon Squeezy and secure authentication via Clerk.

✨ Key Features

📊 Dashboard & Visualization

• Interactive Financial Dashboard - Visualize income, expenses, and account balances with customizable charts
• Multiple Chart Types - Switch between area, bar, line, pie, radar, and radial charts
• Custom Tooltips - Detailed information on hover with category breakdowns
• Real-time Updates - Data refreshes automatically using React Query

💳 Transaction Management

• Transaction Table - Comprehensive view with sorting, filtering, and pagination
• Bulk Operations - Delete multiple transactions at once
• Advanced Search - Find transactions quickly by amount, category, or account
• CSV Import - Import transactions from spreadsheets with validation
• Manual Entry - Add transactions via intuitive forms

🏦 Account & Category Management

• Multiple Accounts - Track checking, savings, credit cards, and more
• Custom Categories - Create and manage expense/income categories
• Account Filtering - View transactions by specific accounts
• Date Range Filters - Analyze transactions across custom time periods

🔗 Banking Integration

• Plaid Integration - Securely connect real bank accounts
• Automatic Syncing - Import transactions directly from your bank
• Bank Disconnection - Manage connected institutions easily

💎 Premium Features

• Subscription Management - Monetized via Lemon Squeezy
• Premium Upgrades - Unlock advanced features and analytics
• Subscription Control - Manage billing and subscription status

🔐 Security & Authentication

• Clerk Authentication - Secure user authentication with Clerk Core 2
• Protected Routes - Dashboard and settings are auth-protected
• User Settings - Customize profile and preferences

🛠 Tech Stack

Frontend

• Next.js 14 - React framework with App Router
• TypeScript - Type-safe JavaScript
• TailwindCSS - Utility-first CSS framework
• Shadcn/ui - Beautifully designed components
• Recharts - Composable charting library
• React Hook Form - Performant form validation
• Tanstack React Query - Data synchronization & caching
• Zustand - Lightweight state management

Backend

• Hono.js - Fast, lightweight web framework
• Drizzle ORM - TypeScript ORM
• PostgreSQL - Relational database via Neon
• Zod - Schema validation

Authentication & Payments

• Clerk - User authentication & management
• Plaid - Banking data integration
• Lemon Squeezy - Payment processing & subscriptions

Deployment & DevTools

• Vercel - Hosting & deployment platform
• Bun - Fast JavaScript runtime & package manager

🚀 Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js 18+ or Bun runtime
• PostgreSQL database (or use Neon for serverless Postgres)
• Git for version control

Installation

1. Clone the repository

git clone https://github.com/SaketKothari/finance-saas-expense-tracker-platform-webapp.git
cd finance-saas-expense-tracker-platform-webapp

2. Install dependencies

npm install
# or
yarn install
# or
pnpm install
# or
bun install

3. Set up environment variables

Create a .env.local file in the root directory and add your environment variables (see Environment Variables section)

4. Set up the database

# Generate database migrations
npm run db:generate

# Run migrations
npm run db:migrate

# (Optional) Seed the database with sample data
npm run db:seed

5. Run the development server

npm run dev
# or
yarn dev
# or
pnpm dev
# or
bun dev

6. Open the application

Navigate to http://localhost:3000 in your browser

Development Commands

# Development server
npm run dev

# Build for production
npm run build

# Start production server
npm run start

# Run linter
npm run lint

# Database commands
npm run db:generate    # Generate migrations from schema
npm run db:migrate     # Run migrations
npm run db:studio      # Open Drizzle Studio
npm run db:seed        # Seed database with sample data

🔐 Environment Variables

Create a .env.local file in the root directory with the following variables:

# Database
DATABASE_URL=your_postgresql_connection_string

# Clerk Authentication
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key
NEXT_PUBLIC_CLERK_SIGN_IN_URL=/sign-in
NEXT_PUBLIC_CLERK_SIGN_UP_URL=/sign-up

# Plaid
PLAID_CLIENT_ID=your_plaid_client_id
PLAID_SECRET=your_plaid_secret
NEXT_PUBLIC_PLAID_ENV=sandbox # or development/production

# Lemon Squeezy
LEMON_SQUEEZY_API_KEY=your_lemon_squeezy_api_key
NEXT_PUBLIC_LEMON_SQUEEZY_STORE_ID=your_store_id
LEMON_SQUEEZY_WEBHOOK_SECRET=your_webhook_secret

# App URL
NEXT_PUBLIC_APP_URL=http://localhost:3000

Getting API Keys

• Database: Sign up for Neon or use your own PostgreSQL instance
• Clerk: Create an account at clerk.com
• Plaid: Sign up at plaid.com and get sandbox credentials
• Lemon Squeezy: Register at lemonsqueezy.com

💾 Database Setup

This project uses PostgreSQL with Drizzle ORM. The schema includes:

• Users - User account information (managed by Clerk)
• Accounts - Financial accounts (checking, savings, etc.)
• Categories - Transaction categories
• Transactions - Income and expense records
• Subscriptions - Premium subscription data

Schema Management

# Generate migrations after schema changes
npm run db:generate

# Apply migrations to database
npm run db:migrate

# Open Drizzle Studio for visual database management
npm run db:studio

📁 Project Structure

finance-saas-expense-tracker-platform-webapp/
├── app/                        # Next.js App Router
│   ├── (auth)/                # Authentication routes
│   │   ├── sign-in/
│   │   └── sign-up/
│   ├── (dashboard)/           # Protected dashboard routes
│   │   ├── accounts/          # Account management
│   │   ├── categories/        # Category management
│   │   ├── settings/          # User settings
│   │   └── transactions/      # Transaction management
│   ├── api/                   # API routes (Hono.js)
│   │   └── [[...route]]/
│   ├── globals.css
│   └── layout.tsx
├── components/                 # React components
│   ├── ui/                    # Shadcn/ui components
│   ├── charts/                # Chart components
│   ├── filters/               # Filter components
│   └── ...
├── features/                   # Feature-based modules
│   ├── accounts/
│   │   ├── api/               # React Query hooks
│   │   ├── components/        # Feature components
│   │   └── hooks/             # Custom hooks
│   ├── categories/
│   ├── transactions/
│   ├── plaid/
│   └── subscriptions/
├── db/                         # Database configuration
│   ├── schema.ts              # Drizzle schema
│   └── drizzle.ts             # Database client
├── lib/                        # Utility libraries
├── hooks/                      # Shared hooks
└── providers/                  # Context providers

📡 API Documentation

The API is built with Hono.js and follows RESTful conventions.

Endpoints

Accounts

• GET /api/accounts - List all accounts
• GET /api/accounts/:id - Get single account
• POST /api/accounts - Create account
• PATCH /api/accounts/:id - Update account
• DELETE /api/accounts/:id - Delete account
• POST /api/accounts/bulk-delete - Bulk delete accounts

Categories

• GET /api/categories - List all categories
• GET /api/categories/:id - Get single category
• POST /api/categories - Create category
• PATCH /api/categories/:id - Update category
• DELETE /api/categories/:id - Delete category
• POST /api/categories/bulk-delete - Bulk delete categories

Transactions

• GET /api/transactions - List transactions (with filters)
• GET /api/transactions/:id - Get single transaction
• POST /api/transactions - Create transaction
• PATCH /api/transactions/:id - Update transaction
• DELETE /api/transactions/:id - Delete transaction
• POST /api/transactions/bulk-delete - Bulk delete transactions
• POST /api/transactions/bulk-create - Import CSV transactions

Plaid

• POST /api/plaid/create-link-token - Create Plaid Link token
• POST /api/plaid/exchange-public-token - Exchange public token
• POST /api/plaid/sync-transactions - Sync bank transactions

Summary

• GET /api/summary - Get financial summary with analytics

Subscriptions

• GET /api/subscriptions - Get current subscription
• POST /api/subscriptions/checkout - Create checkout session
• POST /api/subscriptions/webhook - Handle Lemon Squeezy webhooks

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

2. Clone your fork

git clone https://github.com/YOUR_USERNAME/finance-saas-expense-tracker-platform-webapp.git
cd finance-saas-expense-tracker-platform-webapp

3. Create a feature branch

git checkout -b feature/amazing-feature

4. Make your changes

• Write clean, maintainable code
• Follow the existing code style
• Add tests if applicable
• Update documentation as needed

5. Commit your changes

git commit -m "feat: add amazing feature"

Use conventional commits:

• feat: - New feature
• fix: - Bug fix
• docs: - Documentation changes
• style: - Code style changes (formatting, etc.)
• refactor: - Code refactoring
• test: - Adding tests
• chore: - Maintenance tasks

6. Push to your fork

git push origin feature/amazing-feature

7. Open a Pull Request

• Provide a clear description of your changes
• Reference any related issues
• Wait for review and address feedback

📄 License

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

🙏 Acknowledgments

• Next.js team for the amazing framework
• Shadcn for the beautiful UI components
• Clerk for authentication
• Plaid for banking integration
• Lemon Squeezy for payment processing

📞 Support

If you have any questions or need help, please:

• Open an issue
• Check the documentation

---

Built with ❤️ by Saket Kothari

⭐ Star this repo if you find it helpful!