{"id":28754624,"url":"https://github.com/simpnick6703/splitwise-clone","last_synced_at":"2026-04-16T10:34:50.141Z","repository":{"id":299475810,"uuid":"1003174564","full_name":"SimpNick6703/Splitwise-Clone","owner":"SimpNick6703","description":"Implementation of a popular shared expenses tracking app Splitwise","archived":false,"fork":false,"pushed_at":"2025-06-16T18:38:36.000Z","size":36,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-16T19:45:15.483Z","etag":null,"topics":["fastapi","postgresql","splitwise","splitwise-alternative","tailwindcss"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SimpNick6703.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-16T18:33:51.000Z","updated_at":"2025-06-16T18:38:39.000Z","dependencies_parsed_at":"2025-06-16T19:45:19.598Z","dependency_job_id":"9fb4cc88-95b1-4b64-a869-d6f8914a155e","html_url":"https://github.com/SimpNick6703/Splitwise-Clone","commit_stats":null,"previous_names":["simpnick6703/splitwise-clone"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/SimpNick6703/Splitwise-Clone","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimpNick6703%2FSplitwise-Clone","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimpNick6703%2FSplitwise-Clone/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimpNick6703%2FSplitwise-Clone/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimpNick6703%2FSplitwise-Clone/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SimpNick6703","download_url":"https://codeload.github.com/SimpNick6703/Splitwise-Clone/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SimpNick6703%2FSplitwise-Clone/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260269459,"owners_count":22983649,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fastapi","postgresql","splitwise","splitwise-alternative","tailwindcss"],"created_at":"2025-06-17T01:11:11.572Z","updated_at":"2026-04-16T10:34:50.131Z","avatar_url":"https://github.com/SimpNick6703.png","language":"JavaScript","readme":"# Splitwise Clone\n\nA full-stack expense tracking application built with FastAPI (Python) backend and React frontend, similar to Splitwise. This application helps users track shared expenses and manage group finances.\n\n## Features\n\n![sys_overview](https://github.com/user-attachments/assets/ce16ae87-6e71-4685-86f2-0d07ed54ef2d)\n\n### Core Functionality\n- **User Management**: Create and manage users in the system\n- **Group Management**: Create groups with multiple users\n- **Expense Tracking**: Add expenses with different split types (equal or percentage)\n- **Balance Calculation**: Automatic calculation of who owes whom\n- **Settlement System**: Record payments between users to settle debts\n- **User/Group Management**: Full CRUD operations with safety checks for outstanding balances\n- **Responsive Design**: Beautiful UI with dark/light theme support\n\n### Technical Features\n- **Precision Currency Handling**: All monetary values are precisely rounded to 2 decimal places\n- **Mathematical Consistency**: Expense splits always add up exactly to the total amount\n- **Data Integrity**: Prevention of deletion when outstanding balances exist\n- **Dark/Light Theme**: Toggle between themes with localStorage persistence\n- **RESTful API**: Well-documented FastAPI backend\n- **Real-time Updates**: Automatic balance calculations\n- **Responsive Design**: Mobile-friendly interface using TailwindCSS\n\n## Tech Stack\n\n### Backend\n- **FastAPI**: Modern, fast web framework for building APIs\n- **PostgreSQL**: Robust relational database\n- **SQLAlchemy**: Python SQL toolkit and ORM\n- **Pydantic**: Data validation using Python type annotations\n- **Alembic**: Database migration tool\n\n### Frontend\n- **React 18**: Modern React with hooks\n- **React Router**: Client-side routing\n- **Axios**: HTTP client for API calls\n- **TailwindCSS**: Utility-first CSS framework\n- **Context API**: State management for theme\n\n### Infrastructure\n- **Docker**: Containerization\n- **Docker Compose**: Multi-container orchestration\n\n## Quick Start\n\n### Prerequisites\n- Docker and Docker Compose installed on your system\n- Git (to clone the repository)\n\n### Installation \u0026 Setup\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/SimpNick6703/Splitwise-Clone\n   cd Splitwise-Clone\n   ```\n\n2. **Start the application**\n   ```bash\n   docker-compose up --build\n   ```\n\n   This command will:\n   - Build the backend and frontend Docker images\n   - Start PostgreSQL database\n   - Start the FastAPI backend on port 8000\n   - Start the React frontend on port 3000\n\n3. **Access the application**\n   - Frontend: http://localhost:3000\n   - Backend API: http://localhost:8000\n   - API Documentation: http://localhost:8000/docs\n\n4. **Initialize with sample data (optional)**\n   ```bash\n   # Install Python dependencies for helper scripts\n   pip install -r scripts_requirements.txt\n   \n   # Run the sample data initialization script\n   python init_sample_data.py\n   ```\n\n### Quick Start Scripts\n\nFor convenience, use the provided startup scripts:\n\n**Windows:**\n```bash\nstart.bat\n```\n\n**Linux/Mac:**\n```bash\nchmod +x start.sh\n./start.sh\n```\n\n### Health Check\n\nTo verify all services are running correctly:\n```bash\npython health_check.py\n```\n\n## API Documentation\n\n### User Endpoints\n- `POST /users/` - Create a new user\n- `GET /users/` - Get all users\n- `GET /users/{user_id}` - Get specific user\n- `PUT /users/{user_id}` - Update user details\n- `DELETE /users/{user_id}` - Delete user (only if no outstanding balances)\n- `GET /users/{user_id}/balances` - Get user's balances across all groups\n\n### Group Endpoints\n- `POST /groups/` - Create a new group\n- `GET /groups/` - Get all groups\n- `GET /groups/{group_id}` - Get group details\n- `PUT /groups/{group_id}` - Update group details\n- `DELETE /groups/{group_id}` - Delete group (only if no outstanding balances)\n- `GET /groups/{group_id}/balances` - Get group balances\n- `GET /groups/{group_id}/expenses` - Get group expenses\n- `POST /groups/{group_id}/members` - Add members to group\n- `DELETE /groups/{group_id}/members/{user_id}` - Remove member from group\n\n### Expense Endpoints\n- `POST /groups/{group_id}/expenses` - Add expense to group\n\n### Settlement Endpoints\n- `POST /settlements` - Record a payment between users\n- `GET /groups/{group_id}/settlements` - Get all settlements for a group\n\n### Request/Response Examples\n\n#### Create User\n```json\nPOST /users/\n{\n  \"name\": \"John Doe\",\n  \"email\": \"john@example.com\"\n}\n```\n\n#### Create Group\n```json\nPOST /groups/\n{\n  \"name\": \"Weekend Trip\",\n  \"description\": \"Our weekend getaway expenses\",\n  \"user_ids\": [1, 2, 3]\n}\n```\n\n#### Add Expense (Equal Split)\n```json\nPOST /groups/1/expenses\n{\n  \"description\": \"Dinner at restaurant\",\n  \"amount\": 120.00,\n  \"paid_by\": 1,\n  \"split_type\": \"equal\",\n  \"splits\": []\n}\n```\n\n#### Add Expense (Percentage Split)\n```json\nPOST /groups/1/expenses\n{\n  \"description\": \"Hotel accommodation\",\n  \"amount\": 300.00,\n  \"paid_by\": 1,\n  \"split_type\": \"percentage\",\n  \"splits\": [\n    {\"user_id\": 1, \"percentage\": 50.0},\n    {\"user_id\": 2, \"percentage\": 30.0},\n    {\"user_id\": 3, \"percentage\": 20.0}\n  ]\n}\n```\n\n## Manual Setup (Without Docker)\n\n### Backend Setup\n1. **Navigate to backend directory**\n   ```bash\n   cd backend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   pip install -r requirements.txt\n   ```\n\n3. **Set up PostgreSQL database**\n   - Install PostgreSQL\n   - Create database named `splitwise`\n   - Update `DATABASE_URL` in `database.py` if needed\n\n4. **Run the backend**\n   ```bash\n   python main.py\n   ```\n\n### Frontend Setup\n1. **Navigate to frontend directory**\n   ```bash\n   cd frontend\n   ```\n\n2. **Install dependencies**\n   ```bash\n   npm install\n   ```\n\n3. **Start the development server**\n   ```bash\n   npm start\n   ```\n\n## Features Overview\n\n### User Interface\n- **Dashboard**: Overview of groups, users, and total expenses\n- **Groups Page**: Manage groups and create new ones\n- **Group Details**: View expenses, balances, and add new expenses\n- **Users Page**: Manage users in the system\n- **Theme Toggle**: Switch between dark and light themes\n\n### Split Types\n1. **Equal Split**: Divides expense equally among all group members\n2. **Percentage Split**: Allows custom percentage allocation for each member\n\n### Balance Calculation\nThe application automatically calculates:\n- Individual user balances within groups\n- Net amounts owed or to be received\n- Simplified debt relationships\n\n## Helper Scripts\n\nThe project includes several helper scripts to make development and testing easier:\n\n### Startup Scripts\n- `start.bat` (Windows) / `start.sh` (Linux/Mac): Automated startup with Docker\n- Checks for Docker availability\n- Builds and starts all services\n- Provides status updates and URLs\n\n### Sample Data\n- `init_sample_data.py`: Populates the application with sample users, groups, and expenses\n- Perfect for testing and demo purposes\n- Run after the application is started\n\n### Health Check\n- `health_check.py`: Verifies all services are running correctly\n- Checks backend, frontend, and API documentation availability\n- Useful for debugging deployment issues\n\n### Usage\n```bash\n# Start the application\n./start.sh  # or start.bat on Windows\n\n# Check if everything is running\npython health_check.py\n\n# Add sample data\npython init_sample_data.py\n```\n\n## Assumptions Made\n\n1. **No Authentication**: The application doesn't include user authentication for simplicity\n2. **No Payment Processing**: Focus is on expense tracking, not actual money transfer\n3. **Simplified Debt Calculation**: Uses basic net balance calculation instead of complex debt simplification algorithms\n4. **Single Currency**: All amounts are assumed to be in the same currency (INR ₹)\n5. **Group Membership**: Users must be added to groups to participate in expenses\n\n## Architecture\n\n### Backend Architecture\n```\nbackend/\n├── main.py          # FastAPI application entry point\n├── models.py        # SQLAlchemy database models\n├── schemas.py       # Pydantic models for request/response\n├── database.py      # Database configuration\n├── crud.py          # Database operations\n└── requirements.txt # Python dependencies\n```\n\n### Frontend Architecture\n```\nfrontend/src/\n├── components/      # Reusable UI components\n├── pages/          # Page components\n├── services/       # API service layer\n├── context/        # React context providers\n├── App.js          # Main application component\n└── index.js        # Application entry point\n```\n\n## Development\n\n### Adding New Features\n1. **Backend**: Add new endpoints in `main.py`, models in `models.py`, and schemas in `schemas.py`\n2. **Frontend**: Create new components in `components/` or pages in `pages/`\n3. **Database**: Use Alembic for database migrations\n\n### Styling\n- Uses TailwindCSS utility classes\n- Custom color palette defined in `tailwind.config.js`\n- Dark/light theme support with CSS variables\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly\n5. Submit a pull request\n\n## License\n\nThis project is open source and available under the MIT License.\n\n## Support\n\nFor issues and questions, please create an issue in the GitHub repository.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimpnick6703%2Fsplitwise-clone","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimpnick6703%2Fsplitwise-clone","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimpnick6703%2Fsplitwise-clone/lists"}