An AI-powered full-stack budgeting application that helps you manage income, expenses, savings, and financial goals — with real-time AI advice powered by Groq.

• Overview
• Features
• Tech Stack
• Project Structure
• Getting Started
• Environment Variables
• API Reference
• Frontend Sections
• AI Integration
• Database Models
• Screenshots
• Scripts

Lura AI is a hackathon-ready, production-grade smart budgeting assistant built with Node.js, Express, MongoDB, and Groq AI. It allows users to track their financial records across five categories (income, expense, saving, investment, goal), visualize their budget through interactive charts, get a real-time budget health score, and ask an AI assistant any finance-related question — all from a sleek, responsive single-page application.

• Live budget statistics: Total Income, Total Expenses, Savings, Net Balance
• Animated stat counters on data load
• Budget Health Score (0–100) with color-coded progress bar
• Add, edit, delete budget records with full CRUD
• Search and filter records by name, email, notes, or role
• Export all records to CSV with one click
• Smart AI Tip widget — get personalized budgeting tips from Groq AI

• Bar chart: Income vs Expenses vs Savings vs Investments vs Goals
• Doughnut chart: Spending breakdown by category
• Savings Rate % and Expense Ratio % metrics
• AI Financial Analysis — sends your real budget data to Groq and returns 3 actionable insights

• Visual 5-column planning board organized by role: Income, Expenses, Savings, Investments, Goals
• Each column shows total amount and item count
• Cards display name, amount, status, notes, and date

• Full terminal UI with macOS-style window chrome
• Built-in commands: help, clear, stats, records, balance, tip
• Arrow key command history navigation (↑ / ↓)
• Quick-prompt buttons for common financial questions
• Every query is sent to Groq AI and saved to MongoDB

• Chat bubble UI with user and AI message bubbles
• Quick-chip suggestion buttons
• Persistent chat within session
• Welcome message from Lura on open

• Dark Mode / Light Mode toggle (persisted to localStorage)
• Account info display
• Monthly Savings Goal tracker with animated progress bar
• Data Management: live record count and AI interaction count from MongoDB
• Full AI Interaction History with category tags and timestamps

• Login and Register forms
• localStorage-based session persistence
• Logout from navbar or settings

lura-ai/
│
├── config/
│   └── db/
│       └── database.js          # MongoDB connection via Mongoose
│
├── controller/
│   ├── record.controller.js     # CRUD handlers for budget records
│   └── ai.controller.js         # AI question and history handlers
│
├── models/
│   ├── record.model.js          # Budget record schema
│   └── ai.model.js              # AI interaction schema
│
├── routes/
│   ├── record.routes.js         # /api/records REST routes
│   └── ai.routes.js             # /api/ai/ask and /api/ai/history
│
├── service/
│   ├── record.service.js        # DB operations + budget stats logic
│   └── ai.service.js            # Groq SDK integration + category detection
│
├── public/
│   ├── index.html               # Single-page application entry point
│   ├── style.css                # Full custom CSS with theme system
│   └── script.js                # All frontend logic (charts, CRUD, AI, terminal)
│
├── app.js                       # Express server entry point
├── package.json                 # Project config and dependencies
├── .env                         # Environment variables (not committed)
├── .gitignore                   # Ignores node_modules and .env
└── readme.md                    # This file

• Node.js v18 or higher
• MongoDB running locally on port 27017
• A Groq API key (free at console.groq.com)

# 1. Clone or extract the project
cd lura-ai

# 2. Install dependencies
npm install

# 3. Configure environment variables
# Edit the .env file and add your Groq API key (see below)

# 4. Start MongoDB locally
mongod
# or on macOS with Homebrew:
brew services start mongodb-community

# 5. Start the application
npm start

# App will be running at:
# http://localhost:3000

npm run dev

Create or edit the .env file in the project root:

PORT=3000
MONGO_URI=mongodb://localhost:27017/lura-ai
GROQ_API_KEY=your_groq_api_key_here

Get your free Groq API key at console.groq.com

{
  "name": "Monthly Salary",
  "email": "user@example.com",
  "amount": 3500,
  "role": "income",
  "status": "active",
  "notes": "Net after tax"
}

• income — Money coming in
• expense — Money going out
• saving — Saved amounts
• investment — Investment contributions
• goal — Financial targets

• active — Currently ongoing
• pending — Not yet started
• completed — Finished
• cancelled — Abandoned

{
  "question": "How do I save 20% of my income each month?"
}

{
  "success": true,
  "data": {
    "answer": "To save 20% of your income...",
    "category": "savings"
  }
}

/api/ai/history?limit=20

Lura uses the Groq SDK with model llama-3.1-8b-instant for fast, high-quality AI responses.

• Personal budget planning and management
• Income and expense tracking strategies
• Smart saving techniques
• Debt management and reduction
• Investment basics for beginners
• Financial goal setting
• Emergency fund planning
• Monthly budget breakdowns

Every AI interaction is automatically categorized before being saved to MongoDB:

{
  name:      String,   // required — label or person name
  email:     String,   // required — associated email
  role:      String,   // enum: income | expense | saving | investment | goal
  notes:     String,   // optional notes
  status:    String,   // enum: active | pending | completed | cancelled
  icon:      String,   // Bootstrap icon class
  amount:    Number,   // dollar amount
  category:  String,   // general category label
  createdAt: Date,     // auto timestamp
  updatedAt: Date,     // auto timestamp
}

{
  question:  String,   // required — user's question
  answer:    String,   // required — Groq AI response
  category:  String,   // auto-detected: budgeting | savings | expenses | ...
  createdAt: Date,     // auto timestamp
}

npm start      # Start production server with Node.js
npm run dev    # Start development server with Nodemon (auto-restart)

• The app uses ES Modules ("type": "module" in package.json) — all imports use import/export syntax
• MongoDB must be running locally before starting the server
• The frontend is a single-page application served statically from /public
• All AI interactions are automatically persisted to MongoDB — no interaction is lost
• The Budget Health Score algorithm weights expense ratio (primary) and savings rate (secondary)
• Theme preference and session are stored in localStorage and persist across browser sessions

Built with Node.js · Express · MongoDB · Groq AI · Bootstrap 5