BalanceHub

Link to BalanceHub

Collaborative expense tracking with fair-split algorithms, real-time updates, and CS fundamentals

BalanceHub is a modern expense tracking application designed for groups, families, roommates, and small teams. It combines real-world utility with computer science fundamentals, showcasing advanced algorithms and system design patterns.

Dashboard

Features

Core Functionality

• Collaborative Expense Tracking: Share expenses transparently across group members
• Fair-Split Algorithm: Graph-based debt minimization to reduce transaction complexity
• Real-Time Updates: Event-sourced ledger with Redis Pub/Sub for live synchronization
• Smart Merchant Categorization: Trie-based autocomplete with O(L) lookup performance
• Privacy Controls: Configurable expense visibility (public, group-only, subgroup-private)

Technical Highlights

• Event Sourcing: Immutable expense ledger for data integrity and auditability
• Graph Algorithms: Debt optimization using greedy and min-cut approaches
• Data Structures: Trie implementation for fast merchant search
• Serverless Architecture: Cold start metrics and performance monitoring
• Data Visualization: Interactive charts and analytics with Recharts

Tech Stack

• Frontend: Next.js 15, React, TypeScript, TailwindCSS
• Backend: Next.js API Routes (Serverless Functions)
• Database: PostgreSQL (Neon) with Prisma ORM
• Cache/PubSub: Redis (Upstash)
• Authentication: NextAuth.js with GitHub/Google OAuth
• Deployment: Vercel (free tier)
• UI Components: Radix UI primitives

Quick Start

Prerequisites

• Node.js 18+
• PostgreSQL database (Neon recommended)
• Redis instance (Upstash recommended)
• GitHub/Google OAuth apps

Installation

1. Clone the repository

   git clone <repository-url>
   cd balance-hub

2. Install dependencies

   npm install

3. Set up environment variables

   cp env.example .env.local

   Fill in your environment variables:

   # Database
   DATABASE_URL="postgresql://username:password@localhost:5432/balance_hub"
   
   # NextAuth.js
   NEXTAUTH_URL="http://localhost:3000"
   NEXTAUTH_SECRET="your-secret-key"
   
   # OAuth Providers
   GITHUB_CLIENT_ID="your-github-client-id"
   GITHUB_CLIENT_SECRET="your-github-client-secret"
   GOOGLE_CLIENT_ID="your-google-client-id"
   GOOGLE_CLIENT_SECRET="your-google-client-secret"
   
   # Redis
   REDIS_URL="redis://localhost:6379"

4. Set up the database

   npx prisma generate
   npx prisma db push

5. Run the development server

   npm run dev

6. Open your browser Navigate to http://localhost:3000

CS Fundamentals Showcase

Data Structures & Algorithms

• Trie: Merchant autocomplete with prefix matching
• Graph Theory: Debt minimization using graph algorithms
• Event Sourcing: Immutable data structures for consistency

System Design

• Serverless Architecture: Scalable, cost-effective deployment
• Caching Strategy: Redis for performance optimization
• Real-time Systems: Pub/Sub messaging for live updates
• Database Design: Normalized schema with efficient queries

Performance Monitoring

• Cold Start Metrics: Serverless function latency tracking
• Memory Usage: Runtime performance monitoring
• Algorithm Efficiency: Transaction optimization metrics

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Next.js App   │    │  Serverless APIs │    │   PostgreSQL    │
│                 │────│                  │────│                 │
│ • UI Components │    │ • Expense CRUD   │    │ • Event Sourcing│
│ • Real-time UI  │    │ • Fair Split     │    │ • SQL Views     │
│ • Charts        │    │ • Merchant Trie  │    │ • Aggregations  │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │
         │              ┌─────────────────┐
         └──────────────│      Redis      │
                        │                 │
                        │ • Pub/Sub       │
                        │ • Merchant Trie │
                        │ • Caching       │
                        └─────────────────┘

API Endpoints

• POST /api/expenses/create - Create new expense
• GET /api/ledger/[groupId] - Get group ledger
• GET /api/fair-split/[groupId] - Calculate optimal settlements
• GET /api/merchant/autocomplete - Merchant suggestions
• GET /api/cold-start - Performance metrics
• POST /api/groups/create - Create new group
• GET /api/groups - List user groups

Key Algorithms

Fair-Split Algorithm

// Graph-based debt minimization
function calculateFairSplit(balances: UserBalance[]): Settlement[] {
  const creditors = balances.filter(b => b.balance > 0)
  const debtors = balances.filter(b => b.balance < 0)
  
  // Greedy algorithm to minimize transactions
  // Time Complexity: O(n log n)
  // Space Complexity: O(n)
}

Merchant Trie

// O(L) lookup where L = query length
class MerchantTrie {
  search(prefix: string): string[] {
    // Navigate to prefix node: O(L)
    // Return cached merchants: O(1)
  }
}

Performance Metrics

• Algorithm Efficiency: Up to 90% reduction in settlement transactions
• Search Performance: O(L) merchant autocomplete
• Real-time Updates: <100ms latency for live updates
• Cold Start: <500ms serverless function initialization

Deployment

Vercel Deployment

1. Connect your GitHub repository to Vercel
2. Set environment variables in Vercel dashboard
3. Deploy automatically on push to main branch

Database Setup (Neon)

1. Create a Neon PostgreSQL database
2. Copy connection string to DATABASE_URL
3. Run migrations: npx prisma db push

Redis Setup (Upstash)

1. Create Upstash Redis database
2. Copy connection details to environment variables

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

License

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

---