💸 SpendSense: Full-Stack Financial & IOU Ledger

SpendSense is a comprehensive financial management platform designed to make tracking personal budgets and shared expenses completely frictionless. It bridges a modern React web dashboard with a real-time Telegram bot, all powered by a robust Node.js/MongoDB backend featuring automated background jobs.

🌍 Live Links

• Web Dashboard: spendsense.vercel.app
• Telegram Bot: @ExpanseManager

---

✨ Feature Deep-Dive & Technical Architecture

1. 🤖 Frictionless Telegram Bot UX

Instead of forcing users to log into a website for every small purchase, SpendSense meets them where they already are: their messaging app.

• Persistent UI: Uses a ReplyKeyboardMarkup to keep primary actions (Add Expense, Check Balance) permanently accessible at the bottom of the chat.
• Natural Language Processing: Users can log complex IOUs simply by typing take 500 john or give 200 alex, bypassing complex command syntax.
• Smart Context: Before confirming an expense, the bot queries the MongoDB database and returns the user's remaining bucket balance in real-time, preventing overspending.
• Fail-Safes: Global event listeners immediately catch keywords like "cancel" or "back" to cleanly reset any broken or abandoned conversation states.

2. 📅 Automated IOU Tracking & Cron Jobs

Managing shared expenses usually involves awkward follow-ups. SpendSense automates the confrontation.

• Deadline Management: Users can assign specific due dates to any IOU logged in the system.
• 24/7 Background Service: A custom node-cron service (iouReminders.js) runs continuously on the backend, checking the database against the current timestamp.
• Proactive Alerts: The moment a deadline is breached, the backend automatically dispatches a payload to the Telegram API, pinging the user's phone with the exact debt amount, person, and notes.

3. 🔐 Enterprise-Grade Authentication Flow

A finance app requires serious security, so the authentication goes beyond simple local storage.

• JWT & Secure Sessions: Utilizing JSON Web Tokens for secure, persistent logins that survive page reloads and browser closures.
• Full Password Recovery: Integrated Nodemailer to handle a complete "Forgot Password" lifecycle. The backend generates secure, time-sensitive numeric tokens and emails them to users via responsive HTML templates.
• Centralized Transactions: All ledger updates and settlement logic are strictly handled within isolated backend API routes, ensuring the database remains completely consistent even if the frontend disconnects.

---

💻 Tech Stack

Frontend (Client)

• React.js (Vite)
• Tailwind CSS (Styling & UI)
• React Router DOM
• Vercel Web Analytics

Backend (Server)

• Node.js & Express.js
• MongoDB Atlas (Mongoose ODM)
• node-telegram-bot-api (Bot Webhooks & Polling)
• nodemailer (SMTP Email Services)
• node-cron (Background task scheduling)

Infrastructure

• Frontend Hosting: Vercel
• Backend Hosting: Render
• Database: MongoDB Atlas (Cloud)

---

🚀 Local Setup & Installation

Want to run SpendSense on your local machine? Follow these steps:

1. Clone the repository

git clone [https://github.com/YOUR_GITHUB_USERNAME/spendsense.git](https://github.com/YOUR_GITHUB_USERNAME/spendsense.git)
cd spendsense

2. Setup the Backend Environment Navigate to the backend folder and install dependencies:

cd backend
npm install

Create a .env file in the backend root and configure your keys:

PORT=5000
MONGO_URI=your_mongodb_cluster_string
JWT_SECRET=your_super_secret_key
TELEGRAM_BOT_TOKEN=your_token_from_botfather
EMAIL_USER=your_email@gmail.com
EMAIL_PASS=your_app_password

Start the backend server:

npm run dev

3. Setup the Frontend Environment Navigate to the frontend folder and install dependencies:

cd frontend
npm install

Start the frontend server:

npm run dev

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

🤝 The Team

SpendSense was built with ❤️ and coffee.

Shourya Sinha - Full Stack Developer | GitHub