SplitWise - Expense Sharing Application

A modern expense sharing application that helps groups split bills and track shared expenses effortlessly

Overview

A full-stack expense sharing and management application built with Spring Boot and React. SplitWise helps users split bills and expenses with friends, track balances, and settle up easily.

🚀 Features

Core Functionality

• User Authentication: Secure registration and login with BCrypt password encryption
• Group Management: Create groups and add members for expense sharing
• Expense Tracking: Add and track expenses with detailed descriptions
• Automatic Split Calculation: Expenses are automatically split equally among group members
• Balance Tracking: Real-time balance calculations showing who owes whom
• Settlement System: Easy settlement of debts between group members
• Transaction History: Complete history of all expenses and settlements
• Receipt Generation: Download and print receipts for any expense

Additional Features

• Expense Calculator: Built-in calculator with tip percentage calculation
• Category Support: Categorize expenses (Food, Transport, Housing, etc.)
• Real-time Notifications: Toast notifications for user actions
• Responsive Design: Mobile-friendly interface using Tailwind CSS
• Form Validation: Comprehensive client-side validation with helpful error messages

🛠️ Tech Stack

Backend

• Java 24 (compiled with Java 16 compatibility)
• Spring Boot 3.2.2
  • Spring Boot Starter Web
  • Spring Boot Starter Data JPA
  • Spring Boot Starter Security
  • Spring Boot DevTools
• PostgreSQL - Database
• Maven - Build tool

Frontend

• React 18
• React Router DOM - Navigation
• Tailwind CSS - Styling
• Lucide React - Icons
• Fetch API - HTTP requests

📋 Prerequisites

Before running this application, ensure you have the following installed:

• Java JDK 16+
• Node.js 14+ and npm
• PostgreSQL 12+
• Maven 3.6+

🔧 Installation & Setup

1. Clone the Repository

git clone <repository-url>
cd splitwise-project

2. Database Setup

Create a PostgreSQL database:

CREATE DATABASE splitwise;

Update database credentials in splitwise-backend/src/main/resources/application.properties:

spring.datasource.url=jdbc:postgresql://localhost:5432/splitwise
spring.datasource.username=YOUR_USERNAME
spring.datasource.password=YOUR_PASSWORD
spring.jpa.hibernate.ddl-auto=update
spring.jpa.show-sql=true
spring.jpa.properties.hibernate.format_sql=true

3. Backend Setup

Navigate to the backend directory and build the project:

cd splitwise-backend
mvn clean install
mvn spring-boot:run

The backend server will start on http://localhost:8080

4. Frontend Setup

Navigate to the frontend directory and install dependencies:

cd splitwise-react-frontend
npm install
npm start

The frontend will start on http://localhost:3000

📁 Project Structure

Backend Structure

splitwise-backend/
├── src/main/java/com/splitwise/
│   ├── config/                  # Security & CORS configuration
│   │   ├── SecurityConfig.java
│   │   └── WebConfig.java
│   ├── controller/              # REST API endpoints
│   │   ├── ExpenseController.java
│   │   ├── GroupController.java
│   │   ├── SettlementController.java
│   │   └── UserController.java
│   ├── dto/                     # Data Transfer Objects
│   │   ├── ExpenseDTO.java
│   │   ├── GroupDetailsDTO.java
│   │   ├── LoginRequest.java
│   │   ├── SettlementDTO.java
│   │   └── ...
│   ├── model/                   # JPA Entities
│   │   ├── User.java
│   │   ├── Group.java
│   │   ├── GroupMember.java
│   │   ├── Expense.java
│   │   └── Settlement.java
│   ├── repository/              # JPA Repositories
│   │   ├── UserRepository.java
│   │   ├── GroupRepository.java
│   │   ├── ExpenseRepository.java
│   │   └── SettlementRepository.java
│   ├── service/                 # Business Logic
│   │   ├── UserService.java
│   │   ├── GroupService.java
│   │   ├── ExpenseService.java
│   │   └── SettlementService.java
│   └── SplitwiseApplication.java
└── src/main/resources/
    └── application.properties

Frontend Structure

splitwise-react-frontend/
├── public/
├── src/
│   ├── components/
│   │   ├── auth/               # Authentication components
│   │   │   ├── AuthProvider.js
│   │   │   ├── LoginPage.js
│   │   │   └── ProtectedRoute.js
│   │   ├── layout/             # Layout components
│   │   │   └── Navbar.js
│   │   ├── pages/              # Page components
│   │   │   ├── HomePage.js
│   │   │   ├── Dashboard.js
│   │   │   ├── CreateGroup.js
│   │   │   ├── AddExpense.js
│   │   │   ├── GroupDetails.js
│   │   │   └── MyTransactions.js
│   │   └── ui/                 # UI components
│   │       ├── NotificationSystem.js
│   │       ├── LoadingSpinner.js
│   │       ├── ExpenseCalculator.js
│   │       └── ReceiptGenerator.js
│   ├── utils/                  # Utility functions
│   │   ├── api.js
│   │   ├── constants.js
│   │   └── expenseCategories.js
│   ├── App.js
│   ├── App.css
│   ├── index.js
│   └── index.css
└── package.json

🔌 API Endpoints

User Endpoints

• POST /api/users/register - Register new user
• POST /api/users/login - Login user
• GET /api/users/email/{email} - Get user by email

Group Endpoints

• POST /api/groups/create-with-members - Create group with members
• GET /api/groups/user/email/{email} - Get user's groups
• GET /api/groups/{id}/details?userId={userId} - Get group details

Expense Endpoints

• POST /api/expenses/add - Add new expense
• GET /api/users/{userId}/transactions - Get user transactions

Settlement Endpoints

• POST /api/settle - Settle up between users
• GET /api/settlements/user/{userId} - Get user settlements

💡 Usage

1. Register/Login

• Navigate to the homepage
• Click "Sign Up" to create a new account
• Or login with existing credentials

2. Create a Group

• Go to "Create Group" from the navbar
• Enter a group name
• Add members from the available users list
• Click "Create Group"

3. Add an Expense

• Navigate to "Add Expense"
• Select a group
• Enter description and amount
• Optionally select a category
• Click "Add Expense"

4. View Group Details

• From the Dashboard, click on any group
• View members, balances, and expenses
• See who owes whom
• Generate receipts for expenses

5. Settle Up

• In the group details page
• Click "Settle Up" button
• Choose who to settle with
• Confirm the settlement

6. Use Calculator

• Click the calculator icon in the navbar
• Enter total amount
• Adjust number of people
• Add tip percentage if needed
• See automatic split calculation

🎨 Key Features Explained

Balance Calculation Algorithm

The application uses a sophisticated balance calculation system:

1. Tracks all expenses paid by each member
2. Calculates equal split among all group members
3. Applies settlement transactions to adjust balances
4. Displays personalized "you owe" or "owes you" messages

Security Features

• Passwords encrypted with BCrypt
• CSRF protection disabled for API endpoints
• CORS configured for cross-origin requests
• Spring Security integrated

Validation

• Frontend: Real-time form validation with helpful error messages
• Backend: Entity validation and business logic checks
• Prevents negative amounts, invalid dates, duplicate users

🐛 Troubleshooting

Backend Issues

Database Connection Error

• Ensure PostgreSQL is running
• Check database credentials in application.properties
• Verify database exists: psql -U postgres -l

Port Already in Use

• Change port in application.properties: server.port=8081

Frontend Issues

API Connection Error

• Verify backend is running on port 8080
• Check API_BASE constant in src/utils/constants.js

Module Not Found

• Delete node_modules and package-lock.json
• Run npm install again

🔄 Future Enhancements

• Unequal expense splitting
• Group admin controls
• Email notifications
• Export data to CSV/PDF
• Multi-currency support
• Expense attachments (receipts/images)
• Dark mode theme
• Mobile app version

👥 Contributing

Contributions are welcome! Please follow these steps:

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

---