Features • Screenshots • Technologies • Installation • Project Structure • Database Schema • API Endpoints • Contributors • License
RoomiePay is a modern expense management and settlement application designed specifically for roommates, friends, and groups who share expenses. Stop worrying about who owes whom and how much - let RoomiePay handle the math!
"Living together is already complicated enough. Splitting the bills shouldn't be."
— RoomiePay Team
|
|
|
|
|
|
|
|
|
|
 Login Screen |
 Registration Screen |
 User 1 Dashboard |
 User 2 Dashboard |
 Creating a New Group |
 Joining an Existing Group |
 Settlement Summary |
 Successful Payment |
| Frontend | Backend | Database |
|---|---|---|
|
|
|
# Navigate to backend directory
cd backend
# Install required packages
pip install -r requirements.txt
# Set up environment variables for database connection
# Edit .env file with your database credentials
# Run the FastAPI server
uvicorn backend:app --reload# Navigate to frontend directory
cd frontend
# Install dependencies
npm install
# Start development server
npm startRoomiePay/
├── backend/
│ ├── backend.py # Main FastAPI server implementation
│ ├── database.py # Database connection configuration
│ ├── models.py # SQLAlchemy ORM models
│ ├── schemas.py # Pydantic validation schemas
│ └── security.py # Auth and security functions
│
├── frontend/
│ ├── public/ # Static assets
│ │ └── index.html # HTML entry point
│ │
│ └── src/ # React application source
│ ├── App.js # Main React application component
│ ├── index.js # JavaScript entry point
│ ├── index.css # Global styles
│ │
│ ├── components/ # React UI components
│ │ ├── Dashboard.js # Dashboard view
│ │ ├── Group.js # Group management
│ │ ├── Login.js # Authentication
│ │ ├── Notifications.js # User notifications
│ │ ├── PaymentPortal.js # Payment processing
│ │ ├── Settlements.js # Settlements management
│ │ └── SettlementConfig.js # Settlement settings
│ │
│ └── services/
│ └── api.js # API client for backend communication
Entity Relationship Diagram
Users Table |
Group Members Table |
Settlements Table |
Notifications Table |
| Endpoint | Method | Description |
|---|---|---|
/register |
POST | Register a new user |
/token |
POST | Get authentication token |
/groups |
POST | Create a new group |
/groups |
GET | Get user's groups |
/groups/{group_id}/expenses |
GET | Get group expenses |
/expenses |
POST | Create an expense |
/groups/{group_id}/balances |
GET | Get group member balances |
/groups/{group_id}/finalize-splits |
POST | Calculate and create settlements |
/settlements/{settlement_id}/process-payment |
POST | Process settlement payment |
/notifications |
GET | Get user notifications |
RoomiePay uses an optimized debt-simplification algorithm to minimize the number of transactions needed to settle all debts within a group.
- Registration: Users create accounts with email and password
- Login: Users receive JWT token for authentication
- Protected Resources: All API endpoints (except registration and login) require valid JWT token
- Token Expiry: Tokens expire after a set period for security
- Responsive Design: Works on mobile, tablet, and desktop
- Intuitive Interface: Easy-to-understand expense tracking
- Real-time Feedback: Instant notification of actions
- Gradient Animations: Smooth color transitions for visual appeal
- Modern Components: Clean, intuitive form elements and cards
This project is licensed under the MIT License - see the LICENSE file for details.
MIT License
Copyright (c) 2025 RoomiePay Team
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
RoomiePay — Making shared living expenses simpler since 2025
© 2025 • RoomiePay Team