💰 Sarfa - Personal Expense Tracker

A modern, full-stack expense tracking web application built with React + TypeScript and Node.js + SQLite.

🌟 Features

• ✅ Secure Authentication - JWT-based login/registration system
• 📊 Interactive Dashboard - Real-time statistics and data visualization
• � Multi-Currency Support - 22 currencies matching all supported languages
• 📈 Beautiful Charts - Monthly trends and category breakdowns
• 🎨 Icon Customization - 100+ icons to choose from for each expense
• 🔍 Smart Filtering - Search and filter by date, category, and more
• 📱 Fully Responsive - Works seamlessly on desktop, tablet, and mobile
• 👨‍👩‍👧‍👦 Family Support - Multiple user accounts for family members
• ☁️ Remote Hosting Ready - Easy deployment to any cloud platform

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• npm or yarn

Installation

1. Clone the repository

git clone <your-repo-url>
cd expenses

2. Install backend dependencies

cd server
npm install

3. Install frontend dependencies

cd ..
npm install

Running the Application

1. Start the backend server (Terminal 1)

cd server
npm start

Server runs on http://localhost:3001

2. Start the frontend (Terminal 2)

npm run dev

Application runs on http://localhost:5173

3. Open your browser Navigate to http://localhost:5173

Demo Credentials

• Email: demo@expenses.com
• Password: demo123

🏗️ Tech Stack

Frontend

• ⚛️ React 18 - UI library
• 📘 TypeScript - Type safety
• ⚡ Vite - Build tool
• 🎨 Vanilla CSS - Styling
• 📊 Recharts - Data visualization
• 🎯 Lucide React - Icon library
• 🛣️ React Router - Navigation

Backend

• 🚀 Express - Web framework
• 🗄️ SQLite3 - Database
• 🔐 JWT - Authentication
• 🔒 bcryptjs - Password hashing
• 🌐 CORS - Cross-origin support

📂 Project Structure

expenses/
├── server/              # Backend API
│   ├── server.js        # Express server
│   ├── database.js      # Database setup
│   └── expenses.db      # SQLite database
├── src/                 # Frontend source
│   ├── components/      # React components
│   ├── pages/           # Page components
│   ├── context/         # React context
│   ├── services/        # API services
│   └── types/           # TypeScript types
├── public/              # Static assets
└── index.html           # HTML template

🎯 Key Features Explained

1. Dashboard

• 4 Statistics Cards: Account Balance, Monthly Expenses, Total Investment, Goal Tracker
• Monthly Expenses Chart: 6-month bar chart showing spending trends
• Category Breakdown: Donut chart with interactive legend
• Recent Expenses: Table showing last 5 transactions
• Bill & Subscription Tracker: Recurring payment monitoring

2. Expense Management

• Add expenses with amount, category, sub-category, description, icon, date, and payment mode
• Edit existing expenses
• Delete expenses
• Search and filter functionality
• 6 predefined categories with custom colors

3. Categories

1. 🥬 Food & Grocery
2. 📈 Investment
3. 🛍️ Shopping
4. ✈️ Travelling
5. 📦 Miscellaneous
6. 💳 Bill & Subscription

🔐 Security

• Passwords hashed with bcryptjs (10 rounds)
• JWT tokens for stateless authentication
• Protected API routes
• Input validation on both frontend and backend
• CORS configuration for production
• Demo Account Protection: Data deletion and password changes are disabled for the demo account (demo@expenses.com) to preserve data integrity for public testing.

Backend Deployment (Serverless)

We recommend deploying the backend to Vercel with a Supabase database (Free Tier).

1. Database (Supabase):

   • Create a free project at supabase.com.
   • Get your connection string (Transaction Pooler, port 6543).
   • Example: postgresql://postgres:[PASSWORD]@...:6543/postgres?pgbouncer=true

2. Backend (Vercel):

   • Create a new Vercel project.
   • Set Root Directory to server.
   • Add Environment Variable: DATABASE_URL = (Your Supabase connection string).
   • Add Environment Variable: JWT_SECRET = (Any random secret string).
   • Deploy! (Get your new Backend URL, e.g., https://my-backend.vercel.app).

Frontend Deployment

1. Frontend (Vercel):
   • Create a separate Vercel project (or use the main one with Root Directory .).
   • Add Environment Variable: VITE_API_BASE_URL = https://<YOUR-BACKEND-URL>/api
   • Deploy!
   • Build command: npm run build

📊 API Documentation

Authentication

Register

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123",
  "name": "John Doe"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "password123"
}

Expenses

Get All Expenses

GET /api/expenses?startDate=2025-01-01&endDate=2025-12-31&category=Shopping
Authorization: Bearer <token>

Create Expense

POST /api/expenses
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 50.50,
  "category": "Food & Grocery",
  "sub_category": "Restaurant",
  "description": "Dinner",
  "icon": "UtensilsCrossed",
  "date": "2025-06-15",
  "mode": "Card"
}

Update Expense

PUT /api/expenses/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "amount": 60.00,
  ...
}

Delete Expense

DELETE /api/expenses/:id
Authorization: Bearer <token>

Dashboard

Get Statistics

GET /api/dashboard/stats?period=month
Authorization: Bearer <token>

Periods: recent, month, year

🛠️ Development

Available Scripts

Frontend:

• npm run dev - Start development server
• npm run build - Build for production
• npm run preview - Preview production build

Backend:

• npm start - Start server
• npm run dev - Start with auto-reload (if configured)

Environment Variables

Create .env file in server/ directory:

PORT=3001
JWT_SECRET=your-super-secret-key-change-in-production
NODE_ENV=development

📝 License

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

👨‍💻 Author

Created with ❤️ for managing personal and family expenses.

🙏 Acknowledgments

• Design inspiration from modern fintech applications
• Icons by Lucide
• Charts by Recharts
• Font by Google Fonts (Inter)

---

Happy Expense Tracking! 💰📊