A full-stack web application to track and settle expenses between friends. Split bills easily with multiple split options (equal, exact amounts, percentages, or shares) and keep track of who owes whom.
- User Management: Switch between different users to see personalized views
- Transaction Tracking: Add, edit, and delete expense transactions
- Flexible Split Options:
- Equal split
- Exact amounts
- Percentage-based
- Share-based
- Balance Tracking: See your overall balance and detailed breakdown of who owes you and whom you owe
- Settlement Management: Record payments to settle debts
- Activity Feed: View recent transaction history
- React 18
- Tailwind CSS for styling
- Lucide React for icons
- Fetch API for HTTP requests
- Node.js with Express
- PostgreSQL database
- RESTful API architecture
NudgePay/
├── backend/
│ ├── src/
│ │ ├── config/
│ │ │ ├── database.sql # Database schema
│ │ │ └── db.js # Database connection
│ │ ├── controllers/ # Request handlers
│ │ │ ├── userController.js
│ │ │ ├── transactionController.js
│ │ │ └── settlementController.js
│ │ ├── models/ # Database models
│ │ │ ├── User.js
│ │ │ ├── Transaction.js
│ │ │ └── Settlement.js
│ │ ├── routes/ # API routes
│ │ │ ├── userRoutes.js
│ │ │ ├── transactionRoutes.js
│ │ │ └── settlementRoutes.js
│ │ ├── middleware/ # Express middleware
│ │ │ └── errorHandler.js
│ │ └── server.js # Express app entry point
│ ├── package.json
│ ├── .env.example
│ └── .gitignore
├── frontend/
│ ├── public/
│ │ └── index.html
│ ├── src/
│ │ ├── components/ # React components
│ │ │ ├── Header.jsx
│ │ │ ├── BalanceCard.jsx
│ │ │ ├── Navigation.jsx
│ │ │ ├── Dashboard.jsx
│ │ │ ├── OwesSection.jsx
│ │ │ ├── ActivitySection.jsx
│ │ │ ├── AddTransaction.jsx
│ │ │ └── SettleUp.jsx
│ │ ├── services/ # API service layer
│ │ │ └── api.js
│ │ ├── App.jsx # Main app component
│ │ ├── index.jsx # React entry point
│ │ └── index.css # Global styles
│ ├── package.json
│ ├── tailwind.config.js
│ ├── postcss.config.js
│ ├── .env.example
│ └── .gitignore
└── README.md
- Node.js (v16 or higher)
- PostgreSQL (v12 or higher)
- npm or yarn
cd NudgePayFirst, create a PostgreSQL database:
# Login to PostgreSQL
psql -U postgres
# Create database
CREATE DATABASE nudgepay;
# Exit psql
\qThen, run the database schema:
cd backend
psql -U postgres -d nudgepay -f src/config/database.sqlcd backend
# Install dependencies
npm install
# Create .env file from example
cp .env.example .env
# Edit .env file with your database credentials
# nano .env or use your preferred editor
# Start the backend server
npm run devThe backend server will run on http://localhost:5000
Open a new terminal window:
cd frontend
# Install dependencies
npm install
# Create .env file from example
cp .env.example .env
# Start the frontend development server
npm startThe frontend will run on http://localhost:3000
PORT=5000
NODE_ENV=development
DB_HOST=localhost
DB_PORT=5432
DB_NAME=nudgepay
DB_USER=postgres
DB_PASSWORD=your_password
REACT_APP_API_URL=http://localhost:5000/api
GET /api/users- Get all usersGET /api/users/:id- Get user by IDGET /api/users/balances- Get balance for all usersGET /api/users/:id/owes- Get detailed breakdown of what a user owes/is owedPOST /api/users- Create new userPUT /api/users/:id- Update userDELETE /api/users/:id- Delete user
GET /api/transactions- Get all transactionsGET /api/transactions/:id- Get transaction by IDGET /api/transactions/user/:userId- Get transactions for a specific userPOST /api/transactions- Create new transactionPUT /api/transactions/:id- Update transactionDELETE /api/transactions/:id- Delete transaction
GET /api/settlements- Get all settlementsGET /api/settlements/:id- Get settlement by IDGET /api/settlements/user/:userId- Get settlements for a specific userPOST /api/settlements- Create new settlementDELETE /api/settlements/:id- Delete settlement
- Select User: Use the dropdown in the header to switch between users
- View Dashboard: See your balance, who owes you, and whom you owe
- Add Transaction:
- Click "Add Bill"
- Enter description and total amount
- Select who paid
- Choose split type (equal, exact, percentage, or shares)
- Select participants
- Configure split amounts/percentages/shares as needed
- Click "Add Transaction"
- Edit/Delete Transaction: Click the edit or delete icon on any transaction in your activity feed
- Settle Up:
- Click "Settle Up"
- Select who you're paying
- Enter the amount
- Click "Record Payment"
- Or use "Quick Settle" to pay the exact amount you owe
- users: User information (id, name, email)
- transactions: Expense records (id, paid_by_user_id, total_amount, description, split_type)
- transaction_splits: Split details for each transaction (transaction_id, user_id, amount)
- settlements: Payment records between users (from_user_id, to_user_id, amount)
cd backend
npm run dev # Uses nodemon for auto-reloadcd frontend
npm start # Hot reload enabled by defaultcd backend
npm startcd frontend
npm run build
# Serve the build folder with a static server- User authentication and authorization
- Group management for shared expenses
- Email notifications for new transactions
- Currency conversion support
- Mobile app (React Native)
- Export transaction history (CSV, PDF)
- Recurring transactions
- Transaction categories and tags
- Charts and analytics
Feel free to submit issues and enhancement requests!
MIT License