Expense Management & Bill Splitting Dashboard

A comprehensive, full-stack web application designed for group expense management, automated bill parsing, and seamless balance settlement. Built with modern web technologies including Next.js, MongoDB, Recharts, and Tailwind CSS.

🚀 Features

• User Authentication: Secure signup/login with BCrypt and JWT. Supports password recovery workflows via Nodemailer.
• Group Management: Users can create discrete groups (via unique invite codes) to cleanly manage expenses per household, trip, or event.
• Automated Bill Parsing: Upload receipts via ImageKit, which are tracked from "processing" to "completed" states. Line items are automatically converted for expense tracking.
• Flexible Expense Splitting: Add transactions with different splitting algorithms (Equal, Exact Amounts, Percentages, or Shares).
• Dashboard & Analytics: Visualize expenses with recharts for an interactive, holistic view of your spending, including group-specific treemaps and overviews.
• Settlements: Easily settle balances between individuals in a specific group.
• 💬 AI Expense Assistant (Chatbot): A floating AI chatbot built into the dashboard — context-aware, persistent, and hardened against edge cases.

🛠 Tech Stack

• Frontend: Next.js (App Router), React 19, Tailwind CSS v4, Recharts, Framer Motion
• Backend API: Next.js Route Handlers, Node.js
• Database: MongoDB (Mongoose schemas)
• Authentication: JWT (JSON Web Tokens), BCrypt
• AI: Groq API (LLaMA 3.3 70B / LLaMA 3.1 8B / DeepSeek R1) with automatic model fallback
• File Upload / Image Handling: ImageKit
• Mailing: Nodemailer

💻 Getting Started

Prerequisites

• Node.js (v20+ recommended)
• MongoDB instance (local or Atlas)
• Groq API Key (for chatbot — get one at console.groq.com)
• ImageKit Account (for receipt uploads)
• SMTP Credentials (for Nodemailer/emails)

Installation

1. Clone the repository (or download the project files).
2. Install dependencies:

   npm install

3. Environment Setup: Create a .env.local file with:

   MONGODB_URI=your_mongodb_connection_string
   JWT_SECRET=your_jwt_secret
   GROQ_API_KEY=your_groq_api_key

   Plus ImageKit keys and SMTP configurations as needed.
4. Run the development server:

   npm run dev

5. Open http://localhost:3000 with your browser to see the result.

📁 Project Structure

app/
├── (auth)/                    # Login/Signup pages
├── api/
│   ├── chat/
│   │   ├── route.ts           # Chat API (auth, domain guard, AI routing)
│   │   └── history/
│   │       └── route.ts       # Chat history API (MongoDB persistence)
│   ├── getMyGroups/           # Group listing API
│   ├── getGroupDetails/       # Group details API
│   └── ...                    # Other API routes
├── dashboard/
│   ├── layout.tsx             # Shared layout (Sidebar + Topbar + ChatBot)
│   ├── page.tsx               # Main dashboard
│   ├── groups/
│   │   ├── page.tsx           # Groups listing
│   │   └── [groupId]/
│   │       └── page.tsx       # Group details
│   └── analytics/
│       └── page.tsx           # Analytics & charts
├── layout.tsx                 # Root layout (fonts, theme, ambient glows)
└── page.tsx                   # Landing page

components/
├── chat/
│   └── ChatBot.tsx            # Floating AI chat assistant
├── Sidebar.tsx                # Navigation sidebar
├── Topbar.tsx                 # Top bar with user info
├── dashboard/                 # Dashboard-specific components
├── groups/                    # Group management components
└── landing/                   # Landing page components

lib/
└── ai/
    ├── domainGuard.ts         # Filters off-topic questions
    ├── projectContext.ts      # System prompt with app documentation
    ├── liveDataContext.ts     # Fetches real user/group data for context
    ├── modelRouter.ts         # Multi-model AI routing with fallback
    ├── groq.ts                # Groq API client
    ├── fallbackResponder.ts   # Local keyword-based fallback answers
    └── contextManager.ts      # Context trimming utilities

models/
├── chatHistorySchema.ts       # Chat history MongoDB schema
├── User.ts                    # User model
├── Group.ts                   # Group model
└── ...                        # Other schemas

---

💬 AI Expense Assistant

The Expense Assistant is a floating chatbot widget rendered inside the dashboard layout. It helps users understand and navigate Splitora's features — groups, expenses, bills, balances, settlements, analytics, and more.

Key Capabilities

Feature	Description
Context-aware	Detects current page (Dashboard/Groups/Analytics) and sends route context to AI
Multi-session	Create, switch, search, and delete named chat sessions
Persistent	Hybrid: localStorage for instant access + MongoDB for cross-session durability
Math & Finance	Handles expense calculations, bill splitting, and balance queries
Resizable	Drag-to-resize from left edge, top edge, or corner (desktop only)
Mobile-responsive	Compact bottom-sheet layout (~65% screen) on < 640px screens; fullsize floating panel on desktop
Theme-aware	Automatically adapts to light/dark mode via Tailwind light: variant classes
Click-outside-to-close	Backdrop overlay dismisses chatbot when clicking outside on both mobile and desktop
Offline-aware	Gracefully handles network disconnections

Architecture

User Message → JWT Auth → Domain Guard → Live Data Context → AI Model Router → Response
                                                                    ↓
                                                         Groq (LLaMA 3.3 70B)
                                                                    ↓ fallback
                                                         Groq (LLaMA 3.1 8B)
                                                                    ↓ fallback
                                                         Local Keyword Matcher

Keyboard Shortcuts

Shortcut	Action
Ctrl + Shift + K	Toggle chatbot
Escape	Close dialog / history / panel
Enter	Send message
Shift + Enter	New line

Configuration

Variable	Description
GROQ_API_KEY	Groq API key (required)
GROQ_MODEL_PRIORITY	Model priority list (default: llama-3.3-70b-versatile,llama-3.1-8b-instant,deepseek-r1-distill-llama-70b)
MONGODB_URI	MongoDB connection (required for chat history)
JWT_SECRET	JWT signing secret (required for auth)

Edge Case Handling

• XSS: Full HTML entity escaping before rendering
• Timeouts: 30s abort via AbortController
• Offline: Visual indicator + disabled input
• Corrupted storage: Validation with graceful fallback
• Storage quota: Auto-trim to 5 sessions × 20 messages
• All AI models fail: Local keyword-based fallback responses
• Light mode text selection: Custom ::selection override prevents white-on-white

Verified Test Results

Test Case	Status	Details
Login & Dashboard	✅ Pass	Chatbot FAB visible, no interference with auth flow
Desktop Open/Close	✅ Pass	Floating panel opens; click-outside-to-close works
Chat AI Response	✅ Pass	Sent "How do I add a bill?" → received relevant AI response
Mobile Bottom-Sheet	✅ Pass	Compact bottom-sheet at ~65% viewport height, not fullscreen
Theme Toggle	✅ Pass	Chatbot colors adapt to light/dark mode
Navigation Persistence	✅ Pass	Chat history persists across Dashboard → Groups → Analytics
Light Mode Contrast	✅ Pass	Text readable, selection visible, quick prompts legible
Dark Mode Readability	✅ Pass	Text/icons bright enough for comfortable reading
No Console Errors	✅ Pass	No hydration, syntax, or runtime errors

---

Files Changed for Chatbot Integration (from main branch)

File	Change Type	Purpose
components/chat/ChatBot.tsx	NEW	Floating AI chat assistant component (1325 lines)
app/api/chat/route.ts	NEW	Chat API (auth, domain guard, AI routing)
app/api/chat/history/route.ts	NEW	Chat history API (MongoDB persistence)
lib/ai/*.ts	NEW	AI infrastructure (6 files: groq, modelRouter, domainGuard, projectContext, liveDataContext, fallbackResponder, contextManager)
models/chatHistorySchema.ts	NEW	MongoDB schema for chat history
app/dashboard/layout.tsx	MODIFIED	Added Sidebar, Topbar, ChatBot to shared layout
app/dashboard/page.tsx	MODIFIED	Removed inline Sidebar/Topbar (now in layout)
app/dashboard/groups/page.tsx	MODIFIED	Removed inline Sidebar/Topbar
app/dashboard/groups/[groupId]/page.tsx	MODIFIED	Removed inline Sidebar/Topbar
app/dashboard/analytics/page.tsx	MODIFIED	Removed extra </div> tag
app/layout.tsx	MODIFIED	Added suppressHydrationWarning on <html> and <body>
app/globals.css	MODIFIED	Added chatbot markdown/animation styles with light mode overrides

Note: All modifications to existing files are additive — no existing functionality was removed or broken. The Sidebar/Topbar were moved to the shared layout to enable chatbot persistence across pages.

---

Built with Next.js 16, React 19, TypeScript, Tailwind CSS 4, Mongoose 8, Framer Motion, and Groq AI.