🌟 Sync-Spend

AI-Powered Family Expense Tracker That Actually Works

Built for families who are tired of spreadsheets, lost receipts, and "Wait, what did we spend on groceries again?" conversations.

---

📖 Why We Built This

Ever planned a family vacation, set a budget, and then watched it spiral out of control because someone forgot to log expenses? Yeah, us too.

We were planning a trip to Goa, carefully budgeted ₹50,000 for the week. By day three, we'd somehow spent ₹35,000, and nobody could figure out where it all went. Someone lost receipts, someone forgot to write down cash expenses, and someone conveniently "forgot" about that expensive restaurant bill.

That's when we decided enough was enough.

Sync-Spend was born from real frustration with real problems:

• 📱 Scattered tracking: Everyone using different apps, notebooks, or just... their memory
• 🧾 Receipt chaos: Crumpled papers in wallets, photos lost in camera rolls
• 💸 Budget blindness: No idea where your money actually goes until it's gone
• 👨‍👩‍👧‍👦 Family friction: "I thought YOU were tracking expenses!"
• 🎯 Goal failure: Saving for that car/house/vacation feels impossible without visibility

We wanted something simple, smart, and actually designed for families. Not enterprise software. Not another budgeting lecture. Just a tool that makes tracking money as easy as spending it.

---

🏗️ System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT SIDE                              │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  React Frontend (Vite + TailwindCSS)                      │   │
│  │  ┌────────────┐  ┌────────────┐  ┌─────────────────┐     │   │
│  │  │ Dashboard  │  │  Expense   │  │  Family Mgmt    │     │   │
│  │  │  & Charts  │  │   Pages    │  │   & Settings    │     │   │
│  │  └────────────┘  └────────────┘  └─────────────────┘     │   │
│  └──────────────────────────────────────────────────────────┘   │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTPS/REST API
┌───────────────────────────▼─────────────────────────────────────┐
│                        SERVER SIDE                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │  Express.js Backend                                       │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌─────────┐  │   │
│  │  │   Auth   │  │ Expense  │  │  Family  │  │  Goals  │  │   │
│  │  │Middleware│  │  Routes  │  │  Routes  │  │ Routes  │  │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └─────────┘  │   │
│  └──────────────────────────────────────────────────────────┘   │
└───────────┬────────────────────┬────────────────────────────────┘
            │                    │
            ▼                    ▼
┌───────────────────┐  ┌─────────────────────────┐
│  Firebase Auth    │  │    MongoDB Atlas        │
│  ┌─────────────┐  │  │  ┌──────────────────┐  │
│  │ JWT Tokens  │  │  │  │ Users Collection │  │
│  │ User Mgmt   │  │  │  │Expense Collection│  │
│  └─────────────┘  │  │  │Family Collection │  │
└───────────────────┘  │  │ Goals Collection │  │
                       │  └──────────────────┘  │
                       └─────────────────────────┘
            ┌──────────────────────┐
            │  Google Gemini API   │
            │  ┌────────────────┐  │
            │  │ Gemini 2.5     │  │
            │  │ Flash Model    │  │
            │  └────────────────┘  │
            └──────────────────────┘

---

✨ Features Walkthrough

🤖 AI Receipt Scanner

The Feature That Changes Everything

Snap a photo of any receipt, and watch the magic happen:

• Instant text extraction from crumpled, blurry, or folded receipts
• Smart parsing that understands bill formats (restaurant, grocery, retail)
• Auto-categorization using AI (no more manual dropdowns!)
• Merchant detection and total amount extraction

Tech: Google Gemini 2.5 Flash API analyzes receipt images, extracts structured data, and auto-fills expense forms.

👨‍👩‍👧‍👦 Family Sync

Because Money Is A Team Sport

Create a family group and share everything:

• Real-time expense visibility across all family members
• Shared budgets and goals everyone can contribute to
• Family admin controls for managing members
• Individual + family expense views (your spending vs. household spending)

Tech: MongoDB family collections with member references, Express middleware for family-scoped queries.

📊 Smart Insights & Charts

See Where Your Money Actually Goes

Interactive dashboards powered by Chart.js:

• Category breakdown pie charts (Food, Transport, Entertainment, etc.)
• Spending trends over time (daily, weekly, monthly)
• Budget vs. actual comparisons with visual warnings
• Family leaderboard (who's the biggest spender? 👀)

Tech: Chart.js with dynamic data aggregation, MongoDB aggregation pipelines for analytics.

🎯 Goal Tracking

Make Saving Feel Like Winning

Set financial goals and watch progress bars fill:

• Custom goals (vacation fund, emergency savings, new gadget)
• Visual progress tracking with percentage indicators
• Contribution history showing who added what
• Goal completion celebrations 🎉

Tech: Separate Goals collection with progress calculations, contribution tracking per family member.

🔐 Rock-Solid Security

Your Data, Locked Down

• Firebase Authentication with email/password
• JWT token verification on every request
• Password encryption with bcrypt
• CORS protection and secure headers
• Environment variable secrets (never committed to git)

---

🚀 Quick Start

Prerequisites

# Required installed software:
- Node.js (v16 or higher)
- npm or yarn
- MongoDB (local or Atlas account)
- Firebase project (for authentication)
- Google Gemini API key (for AI receipt scanning)

Installation

1. Clone the repository

git clone https://github.com/yourusername/Sync-Spend.git
cd Sync-Spend

2. Setup Backend

cd backend
npm install

# Create .env file with:
MONGODB_URI=your_mongodb_connection_string
FIREBASE_TYPE=service_account
FIREBASE_PROJECT_ID=your_project_id
FIREBASE_PRIVATE_KEY_ID=your_private_key_id
FIREBASE_PRIVATE_KEY="your_private_key"
FIREBASE_CLIENT_EMAIL=your_client_email
FIREBASE_CLIENT_ID=your_client_id
FIREBASE_AUTH_URI=https://accounts.google.com/o/oauth2/auth
FIREBASE_TOKEN_URI=https://oauth2.googleapis.com/token
FIREBASE_AUTH_PROVIDER_CERT_URL=https://www.googleapis.com/oauth2/v1/certs
FIREBASE_CLIENT_CERT_URL=your_client_cert_url
GEMINI_API_KEY=your_gemini_api_key

# Start backend server
npm start

3. Setup Frontend

cd ../frontend
npm install

# Create .env file with:
VITE_API_URL=http://localhost:5000
VITE_FIREBASE_API_KEY=your_firebase_api_key
VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your_project_id
VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
VITE_FIREBASE_APP_ID=your_app_id

# Start frontend dev server
npm run dev

4. Open in browser

Navigate to http://localhost:5173

---

🛠️ Tech Stack

Frontend

Technology	Purpose
React 18	UI framework with hooks
Vite	Lightning-fast build tool
TailwindCSS	Utility-first styling (glassy UI!)
Chart.js	Data visualization
React Router	Client-side routing
Firebase SDK	Authentication
Axios	API requests

Backend

Technology	Purpose
Node.js	JavaScript runtime
Express.js	REST API framework
MongoDB	NoSQL database
Mongoose	MongoDB ODM
Firebase Admin	Auth token verification
Google Gemini AI	Receipt text extraction & AI insights (Gemini 2.5 Flash)
bcrypt	Password hashing
JWT	Token-based auth
multer	File upload handling

---

📁 Project Structure

Sync-Spend/
│
├── frontend/                      # React frontend application
│   ├── src/
│   │   ├── components/           # Reusable UI components
│   │   │   ├── ProtectedRoute.jsx
│   │   │   └── charts/           # Chart components
│   │   ├── layouts/              # Layout wrappers
│   │   │   └── MainLayout.jsx    # Main app layout with navbar
│   │   ├── pages/                # Route pages
│   │   │   ├── Home.jsx          # Dashboard
│   │   │   ├── AddExpense.jsx    # Expense entry + AI scanner
│   │   │   ├── Goals.jsx         # Goal management
│   │   │   ├── FamilySetup.jsx   # Create/join family
│   │   │   ├── FamilyManagement.jsx
│   │   │   ├── Settings.jsx
│   │   │   └── Login.jsx
│   │   ├── utils/                # Helper functions
│   │   │   └── firebase.js       # Firebase config
│   │   ├── App.jsx               # Main app component
│   │   └── main.jsx              # Entry point
│   ├── public/                   # Static assets
│   └── package.json
│
├── backend/                       # Express backend application
│   ├── models/                   # Mongoose schemas
│   │   ├── User.js
│   │   ├── Expense.js
│   │   ├── Family.js
│   │   └── Goal.js
│   ├── routes/                   # API route handlers
│   │   ├── auth.js
│   │   ├── expenses.js
│   │   ├── families.js
│   │   └── goals.js
│   ├── middleware/
│   │   └── auth.js               # JWT verification
│   ├── uploads/                  # Temporary receipt storage
│   ├── server.js                 # Express app entry
│   └── package.json
│
└── README.md                      # You are here!

---

📖 How to Use

Getting Started

1. Sign up with email/password on the login page
2. Create or join a family (optional but recommended!)
3. Add your first expense manually or scan a receipt
4. Set financial goals to start tracking progress
5. Invite family members to collaborate

Adding Expenses

Manual Entry:

• Click "Add Expense" from dashboard
• Fill in amount, category, description, date
• Submit to log instantly

AI Receipt Scan:

• Click "Scan Receipt" button
• Take/upload photo of receipt
• AI extracts details automatically
• Review and confirm

Family Features

Creating a Family:

• Go to Family Setup
• Click "Create Family"
• Enter family name
• Share family code with members

Joining a Family:

• Get family code from admin
• Click "Join Family"
• Enter code and join instantly

Setting Goals

• Navigate to Goals page
• Click "Create New Goal"
• Set target amount and deadline
• Add funds as you save

---

🔐 Security & Privacy

• All passwords hashed with bcrypt (salt rounds: 10)
• Authentication tokens expire after 1 hour
• Firebase Admin SDK verifies all auth tokens
• Environment variables protect API keys and secrets
• CORS configured to accept only authorized origins
• MongoDB connection uses encrypted TLS connection
• No sensitive data stored in localStorage (only auth tokens)

---

🧪 Testing

# Backend tests (if configured)
cd backend
npm test

# Frontend tests
cd frontend
npm test

# Run linters
npm run lint

---

🗄️ Database Schema

Users Collection

{
  _id: ObjectId,
  name: String,
  email: String (unique),
  firebaseUid: String (unique),
  familyId: ObjectId (ref: Family),
  createdAt: Date
}

Expenses Collection

{
  _id: ObjectId,
  userId: ObjectId (ref: User),
  familyId: ObjectId (ref: Family),
  amount: Number,
  category: String,
  description: String,
  date: Date,
  receiptUrl: String,
  createdAt: Date
}

Families Collection

{
  _id: ObjectId,
  name: String,
  code: String (unique, 6-digit),
  adminId: ObjectId (ref: User),
  members: [ObjectId] (ref: User),
  createdAt: Date
}

Goals Collection

{
  _id: ObjectId,
  userId: ObjectId (ref: User),
  familyId: ObjectId (ref: Family),
  name: String,
  targetAmount: Number,
  currentAmount: Number,
  deadline: Date,
  contributions: [
    {
      amount: Number,
      userId: ObjectId,
      date: Date
    }
  ],
  createdAt: Date
}

---

🚀 Deployment

Frontend (Netlify)

Current Production: https://sync-spend.netlify.app

1. Connect GitHub Repository

   • Login to Netlify
   • Import from GitHub
   • Select Sync-Spend repository

2. Build Settings

   Base directory: frontend
   Build command: npm run build
   Publish directory: frontend/dist

3. Environment Variables

   VITE_API_URL=https://your-backend.onrender.com
   VITE_FIREBASE_API_KEY=your_firebase_api_key
   VITE_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
   VITE_FIREBASE_PROJECT_ID=your_project_id
   VITE_FIREBASE_STORAGE_BUCKET=your_project.appspot.com
   VITE_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
   VITE_FIREBASE_APP_ID=your_app_id

4. Deploy

   • Automatic deployments on main branch push

---

Backend (Render)

Current Production: Deployed on Render

1. Create Web Service

   • Login to Render
   • New → Web Service
   • Connect GitHub repository

2. Service Settings

   Name: sync-spend-backend
   Root Directory: backend
   Build Command: npm install
   Start Command: npm start

3. Environment Variables (Critical!)

   # Database
   MONGODB_URI=your_mongodb_atlas_connection_string
   
   # Authentication
   JWT_SECRET=your_production_jwt_secret
   FIREBASE_PROJECT_ID=your_project_id
   FIREBASE_CLIENT_EMAIL=your_service_account_email
   
   # AI Features
   GEMINI_API_KEY=your_gemini_api_key
   
   # Email Service (OPTIONAL - See troubleshooting below)
   SMTP_HOST=smtp.gmail.com
   SMTP_PORT=465
   SMTP_USER=your_email@gmail.com
   SMTP_PASS=your_app_password
   SMTP_TIMEOUT=15000
   EMAIL_FROM=Sync-Spend
   NODE_ENV=production
   
   # Optional: Enable email debugging
   DEBUG_EMAIL=false

4. Important Notes

   • Use port 465 with SSL instead of 587 for better compatibility with Render
   • Email service is optional - app works fine without it
   • If email timeout persists, set DEBUG_EMAIL=false to silence errors

---

Database (MongoDB Atlas)

1. Setup

   • Create free cluster at mongodb.com/cloud/atlas
   • Add database user
   • Whitelist IP: 0.0.0.0/0 (for Render)

2. Get Connection String

   mongodb+srv://username:password@cluster.mongodb.net/sync-spend
   

3. Security

   • Enable automated backups
   • Use strong passwords
   • Rotate credentials periodically

---

📧 Email Service Troubleshooting (Render)

If you see email timeout errors in Render logs:

Option 1: Use Port 465 (Recommended)

SMTP_HOST=smtp.gmail.com
SMTP_PORT=465
SMTP_TIMEOUT=15000

Update emailService.js:

port: parseInt(process.env.SMTP_PORT) || 465,
secure: process.env.SMTP_PORT === '465', // true for 465

Option 2: Disable Email Temporarily

• Remove SMTP_USER and SMTP_PASS from Render environment variables
• App will work fine without email features
• Logs will show: ℹ️ Email service not configured (optional)

Option 3: Use SendGrid/Mailgun

• Many hosting platforms block direct SMTP
• Consider using SendGrid (free tier) or Mailgun
• Update emailService.js to use their SDK

To Debug:

# Enable verbose logging in Render
DEBUG_EMAIL=true

---

🛣️ Roadmap

• Recurring expenses (subscriptions, bills)
• Budget alerts (email/SMS when overspending)
• Export reports (PDF/CSV downloads)
• Multiple currencies support
• Bank account sync (Plaid integration)
• Mobile apps (React Native)
• Split expenses (who owes whom)
• Investment tracking (stocks, mutual funds)

---

🤝 Contributing

We welcome contributions! Here's how:

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

Code Style:

• Use ESLint config provided
• Follow existing patterns
• Write meaningful commit messages
• Add comments for complex logic

---

📄 License

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

---

👥 Team

Built with ❤️ by two developers who were tired of financial chaos:

Chanikya K

🔧 Focus: Frontend UI/UX, React components, glassy design system
📧 Contact: karrichanikya@gmail.com
💡 "Making finance tracking beautiful, one glassy button at a time"

Charmi S

🔧 Focus: Backend architecture, AI integration, MongoDB optimization
📧 Contact: charmiseera07@gmail.com
💡 "Building systems that make money management actually manageable"

---

🙏 Acknowledgments

• Google for the powerful Gemini AI API
• Firebase for hassle-free authentication
• MongoDB for flexible data storage
• TailwindCSS for making CSS fun again
• Chart.js for beautiful visualizations
• Our families, for being the ultimate beta testers (and bug reporters!)

---

📞 Support

Found a bug? Have a feature request? Want to say hi?

• Issues: Open an issue on GitHub
• Email: charmiseera07@gmail.com or karrichanikya@gmail.com
• Discussions: Use GitHub Discussions for questions

---

⭐ Star this repo if Sync-Spend helped you get your finances under control! ⭐

Made with 💰 and ☕ in India