{"id":30807314,"url":"https://github.com/web-dev-nav/splitmate","last_synced_at":"2026-02-15T00:32:12.157Z","repository":{"id":313174564,"uuid":"1050293190","full_name":"web-dev-nav/SplitMate","owner":"web-dev-nav","description":"SplitMate - A Laravel-based expense sharing app for roommates. Track grocery bills, split costs equally, upload receipts, and manage who owes whom with real-time balance calculations.","archived":false,"fork":false,"pushed_at":"2025-09-24T03:12:51.000Z","size":225,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T12:37:25.209Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/web-dev-nav.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-04T08:18:33.000Z","updated_at":"2025-09-24T03:12:55.000Z","dependencies_parsed_at":"2025-09-04T11:29:12.321Z","dependency_job_id":"bcfc52c1-e4f2-40a8-98f7-dc80f2df1ce1","html_url":"https://github.com/web-dev-nav/SplitMate","commit_stats":null,"previous_names":["web-dev-nav/splitmate"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/web-dev-nav/SplitMate","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-dev-nav%2FSplitMate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-dev-nav%2FSplitMate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-dev-nav%2FSplitMate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-dev-nav%2FSplitMate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/web-dev-nav","download_url":"https://codeload.github.com/web-dev-nav/SplitMate/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/web-dev-nav%2FSplitMate/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29461911,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T22:42:09.113Z","status":"ssl_error","status_checked_at":"2026-02-14T22:42:05.053Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2025-09-06T02:06:09.325Z","updated_at":"2026-02-15T00:32:12.140Z","avatar_url":"https://github.com/web-dev-nav.png","language":"PHP","readme":"# SplitMate 💰\n\nA sophisticated expense splitting application built with Laravel 12 and Tailwind CSS. SplitMate helps groups of people track shared expenses with **automatic debt reduction**, calculate complex balances, and manage settlements efficiently.\n\n\u003cimg width=\"1920\" height=\"1715\" alt=\"captureit_9-16-2025_at_21-09-24\" src=\"https://github.com/user-attachments/assets/5c027fcf-b265-447a-b51a-1890fce83a9c\" /\u003e\n\n## ✨ Key Features\n\n### 🧮 **Smart Expense Management**\n- **Automatic Debt Reduction**: When someone pays for an expense, their share automatically reduces any existing debts they owe to others\n- **Equal Splitting**: All expenses are split equally among active users\n- **Receipt Tracking**: Upload receipt photos (gallery or camera) for every expense\n- **Historical Accuracy**: Maintains correct calculations even when group composition changes\n\n### 👥 **Advanced User Management**\n- **Soft Delete System**: Remove users without losing transaction history\n- **User Reactivation**: Bring back former members with all their data intact\n- **Active/Inactive Status**: Support for 2-10 people with flexible group management\n- **User Count Tracking**: Preserves calculation accuracy across group changes\n\n### 💳 **Intelligent Settlement System**\n- **Payment Validation**: Prevents overpayment with real-time debt checking\n- **Payment Proof**: Screenshot upload for settlement verification\n- **Automatic Balance Updates**: Real-time wallet balance calculations\n- **Debt Priority System**: Reduces highest debts first for optimal cash flow\n\n### 📊 **Comprehensive Tracking**\n- **Wallet Snapshots**: Historical tracking of all wallet states after each transaction\n- **Step-by-Step Breakdowns**: Detailed mathematical explanations of all calculations\n- **Real-time Balances**: Live updates showing who owes what to whom\n- **Transaction History**: Complete audit trail of all expenses and settlements\n\n## 🛠️ Technology Stack\n\n- **Backend**: Laravel 12.x with PHP 8.2+\n- **Frontend**: Blade templates with Tailwind CSS 4.x\n- **Database**: SQLite (default) / MySQL / PostgreSQL\n- **Build Tool**: Vite for asset compilation\n- **File Storage**: Laravel Storage with public disk\n- **Validation**: Client-side + server-side validation\n- **Mobile Support**: Camera integration for receipt capture\n\n## 🚀 Unique Technical Features\n\n### 🧮 **Advanced Debt Calculation Engine**\n- **Net Balance Tracking**: Maintains accurate balances between all user pairs\n- **Debt Reduction Algorithm**: Automatically reduces existing debts when someone pays\n- **Historical Accuracy**: Preserves calculations even when group composition changes\n- **Priority-Based Reduction**: Reduces highest debts first for optimal cash flow\n\n### 📸 **Mobile-First Design**\n- **Camera Integration**: Direct photo capture for receipts and payments\n- **Gallery Selection**: Easy file selection from device gallery\n- **Responsive UI**: Optimized for mobile and desktop use\n- **Touch-Friendly**: Large buttons and intuitive gestures\n\n### 🔒 **Data Integrity \u0026 Validation**\n- **Overpayment Prevention**: Real-time validation prevents paying more than owed\n- **File Validation**: Image type and size validation for uploads\n- **Soft Delete System**: Preserves transaction history when users leave\n- **Audit Trail**: Complete transaction history with timestamps\n\n### 📊 **Real-Time Features**\n- **Live Calculations**: Per-person amounts update as you type\n- **Dynamic Balances**: Wallet status updates immediately\n- **Interactive Breakdowns**: Expandable detailed calculations\n- **Form Validation**: Instant feedback on form errors\n\n## 📋 Prerequisites\n\nBefore you begin, ensure you have the following installed on your system:\n\n- **PHP 8.2 or higher**\n- **Composer** (PHP dependency manager)\n- **Node.js 18+ and npm** (for frontend assets)\n- **Git** (for version control)\n\n### Optional but Recommended:\n- **Laravel Sail** (Docker-based development environment)\n- **MySQL/PostgreSQL** (for production databases)\n\n## 🚀 Installation\n\n### Method 1: Using Composer (Recommended)\n\n1. **Clone the repository**\n   ```bash\n   git clone https://github.com/yourusername/splitmate.git\n   cd splitmate\n   ```\n\n2. **Install PHP dependencies**\n   ```bash\n   composer install\n   ```\n\n3. **Install Node.js dependencies**\n   ```bash\n   npm install\n   ```\n\n4. **Environment Setup**\n   ```bash\n   cp .env.example .env\n   php artisan key:generate\n   ```\n\n5. **Database Setup**\n   ```bash\n   # For SQLite (default)\n   touch database/database.sqlite\n   \n   # Or configure MySQL/PostgreSQL in .env file\n   # DB_CONNECTION=mysql\n   # DB_HOST=127.0.0.1\n   # DB_PORT=3306\n   # DB_DATABASE=splitmate\n   # DB_USERNAME=root\n   # DB_PASSWORD=\n   ```\n\n6. **Run Migrations**\n   ```bash\n   php artisan migrate\n   ```\n\n7. **Seed Database (Optional)**\n   ```bash\n   php artisan db:seed\n   ```\n\n8. **Build Frontend Assets**\n   ```bash\n   npm run build\n   ```\n\n9. **Start the Development Server**\n   ```bash\n   php artisan serve\n   ```\n\n   The application will be available at `http://localhost:8000`\n\n### Method 2: Using Laravel Sail (Docker)\n\n1. **Clone and setup**\n   ```bash\n   git clone https://github.com/yourusername/splitmate.git\n   cd splitmate\n   composer install\n   ```\n\n2. **Start Sail**\n   ```bash\n   ./vendor/bin/sail up -d\n   ```\n\n3. **Run migrations**\n   ```bash\n   ./vendor/bin/sail artisan migrate\n   ```\n\n4. **Build assets**\n   ```bash\n   ./vendor/bin/sail npm run build\n   ```\n\n   The application will be available at `http://localhost`\n\n## 🔧 Development\n\n### Running in Development Mode\n\nFor development with hot reloading:\n\n```bash\n# Terminal 1: Start Laravel server\nphp artisan serve\n\n# Terminal 2: Start Vite dev server\nnpm run dev\n\n# Or use the combined command\ncomposer run dev\n```\n\n### Database Management\n\n```bash\n# Create a new migration\nphp artisan make:migration create_table_name\n\n# Run migrations\nphp artisan migrate\n\n# Rollback last migration\nphp artisan migrate:rollback\n\n# Reset all migrations\nphp artisan migrate:reset\n```\n\n### Frontend Development\n\n```bash\n# Watch for changes and rebuild\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\n## 📁 Project Structure\n\n```\nsplitmate/\n├── app/\n│   ├── Http/Controllers/     # Application controllers\n│   │   ├── ExpenseController.php    # Main expense \u0026 settlement logic\n│   │   └── SettingsController.php   # User management\n│   └── Models/              # Eloquent models\n│       ├── User.php                 # User model with soft delete\n│       ├── Expense.php              # Expense model with relationships\n│       ├── Settlement.php           # Settlement model\n│       └── WalletSnapshot.php       # Historical balance tracking\n├── database/\n│   ├── migrations/          # Database migrations\n│   │   ├── create_expenses_table.php\n│   │   ├── create_settlements_table.php\n│   │   └── create_wallet_snapshots_table.php\n│   └── seeders/            # Database seeders\n├── resources/\n│   ├── css/                # Tailwind CSS files\n│   ├── js/                 # JavaScript for form validation\n│   └── views/              # Blade templates\n│       ├── layouts/app.blade.php    # Main layout\n│       ├── expenses/index.blade.php # Main dashboard\n│       └── settings/index.blade.php # User management\n├── routes/\n│   └── web.php             # Web routes\n└── public/                 # Public assets \u0026 file storage\n```\n\n## 🗄️ Database Schema\n\n### Core Tables:\n- **users**: User accounts with soft delete support\n- **expenses**: Shared expenses with receipt photos\n- **settlements**: Payment records between users\n- **wallet_snapshots**: Historical balance states\n- **expense_paybacks**: Individual payback tracking\n\n### Key Relationships:\n- Users have many expenses (as payer)\n- Users have many settlements (as payer/receiver)\n- Expenses belong to users (paid_by_user_id)\n- Settlements reference two users (from_user_id, to_user_id)\n- Wallet snapshots track balance changes over time\n\n## 🌐 API Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| GET | `/` | Main dashboard with expenses and balances |\n| POST | `/expenses` | Create new expense |\n| POST | `/settlements` | Record settlement payment |\n| GET | `/settings` | User management page |\n| POST | `/settings/users` | Update user list |\n| DELETE | `/settings/users/{user}` | Soft delete user |\n| POST | `/settings/users/{user}/reactivate` | Reactivate user |\n| GET | `/wallet-snapshots` | Get historical balance data |\n\n## 🧠 How the Automatic Debt Reduction Works\n\nSplitMate features a sophisticated algorithm that automatically reduces debts when someone pays for an expense:\n\n### Example Scenario:\n1. **Alice** owes **Bob** $20\n2. **Alice** pays for a $30 dinner (split 3 ways = $10 each)\n3. **Alice's** $10 share automatically reduces her debt to Bob from $20 to $10\n4. **Bob** now owes **Alice** $10 (the reduction amount)\n5. The remaining $20 is split normally among the group\n\n### Key Benefits:\n- **No Manual Work**: Debts are reduced automatically\n- **Optimal Cash Flow**: Highest debts are reduced first\n- **Transparent Calculations**: Every step is explained in detail\n- **Historical Accuracy**: All calculations are preserved and auditable\n\n## 🎯 Usage Guide\n\n### 👥 **Managing People**\n1. **Add Users**: Go to Settings → Add Person → Enter name\n2. **Remove Users**: Click the ghost emoji (👻) to soft-delete\n3. **Reactivate**: Former members can be brought back with all their history\n4. **Group Size**: Supports 2-10 people with automatic validation\n\n### 💸 **Adding Expenses**\n1. **Main Dashboard**: Click \"Add New Expense\"\n2. **Fill Details**:\n   - Description (e.g., \"Grocery Shopping\")\n   - Total amount\n   - Who paid (dropdown selection)\n   - Receipt photo (required - gallery or camera)\n   - Date (defaults to today)\n3. **Automatic Processing**: The system handles all calculations and debt reductions\n\n### 💳 **Recording Settlements**\n1. **View Balances**: Check the wallet status cards\n2. **Create Settlement**: Click \"Record Settlement\"\n3. **Select Users**: Who paid → Who received\n4. **Enter Amount**: System prevents overpayment\n5. **Upload Proof**: Payment screenshot required\n6. **Submit**: Balances update automatically\n\n### 📊 **Understanding Your Wallet**\n- **Green Balances**: Money others owe you\n- **Red Balances**: Money you owe others\n- **Net Balance**: Your overall financial position\n- **Breakdown Details**: Click to see step-by-step calculations\n\n## 🧪 Testing\n\n```bash\n# Run all tests\nphp artisan test\n\n# Run specific test\nphp artisan test --filter=ExpenseTest\n\n# Run with coverage\nphp artisan test --coverage\n```\n\n## 📦 Production Deployment\n\n1. **Environment Configuration**\n   ```bash\n   cp .env.example .env\n   # Edit .env with production settings\n   ```\n\n2. **Install Dependencies**\n   ```bash\n   composer install --optimize-autoloader --no-dev\n   npm ci \u0026\u0026 npm run build\n   ```\n\n3. **Database Setup**\n   ```bash\n   php artisan migrate --force\n   ```\n\n4. **Cache Configuration**\n   ```bash\n   php artisan config:cache\n   php artisan route:cache\n   php artisan view:cache\n   ```\n\n## 🌐 Hosting Configuration\n\n### Removing `/public` from URLs\n\nWhen deploying to shared hosting, you typically need to remove `/public` from your URLs. Here are several methods:\n\n#### Method 1: Move Files (Recommended for Shared Hosting)\n\n1. **Move all files from `public/` to root directory**\n   ```bash\n   # Move all files from public/ to your domain root\n   mv public/* ./\n   mv public/.* ./\n   rmdir public\n   ```\n\n2. **Update `index.php`**\n   ```php\n   // Change this line in index.php:\n   require __DIR__.'/../vendor/autoload.php';\n   // To:\n   require __DIR__.'/vendor/autoload.php';\n   \n   // Change this line:\n   $app = require_once __DIR__.'/../bootstrap/app.php';\n   // To:\n   $app = require_once __DIR__.'/bootstrap/app.php';\n   ```\n\n#### Method 2: Apache .htaccess (If you have access to document root)\n\nCreate a `.htaccess` file in your domain root:\n\n```apache\n\u003cIfModule mod_rewrite.c\u003e\n    RewriteEngine On\n    \n    # Redirect to public folder\n    RewriteCond %{REQUEST_URI} !^/public/\n    RewriteRule ^(.*)$ /public/$1 [L,QSA]\n\u003c/IfModule\u003e\n```\n\n#### Method 3: Nginx Configuration\n\nAdd this to your Nginx server block:\n\n```nginx\nserver {\n    listen 80;\n    server_name yourdomain.com;\n    root /path/to/your/splitmate/public;\n    index index.php;\n\n    location / {\n        try_files $uri $uri/ /index.php?$query_string;\n    }\n\n    location ~ \\.php$ {\n        fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;\n        fastcgi_index index.php;\n        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;\n        include fastcgi_params;\n    }\n}\n```\n\n#### Method 4: cPanel/Shared Hosting\n\n1. **Upload your Laravel files** to a subdirectory (e.g., `splitmate/`)\n2. **Create a subdomain** pointing to `splitmate/public/`\n3. **Or use the File Manager** to move contents of `public/` to `public_html/`\n\n#### Method 5: Using .htaccess Redirect\n\nIf you can't modify the document root, create this `.htaccess` in your domain root:\n\n```apache\nRewriteEngine On\nRewriteCond %{REQUEST_URI} !^/public/\nRewriteRule ^(.*)$ /public/$1 [L]\n```\n\n### Environment Variables for Production\n\nUpdate your `.env` file for production:\n\n```env\nAPP_ENV=production\nAPP_DEBUG=false\nAPP_URL=https://yourdomain.com\n\nDB_CONNECTION=mysql\nDB_HOST=your-db-host\nDB_PORT=3306\nDB_DATABASE=your-database-name\nDB_USERNAME=your-username\nDB_PASSWORD=your-password\n\n# Add your production settings here\n```\n\n### File Permissions\n\nSet proper permissions for your hosting:\n\n```bash\n# Set directory permissions\nchmod -R 755 storage bootstrap/cache\nchmod -R 644 .env\n\n# Make sure storage is writable\nchmod -R 775 storage\nchmod -R 775 bootstrap/cache\n```\n\n## 🔧 Development Workflow\n\n### Quick Start for Developers\n```bash\n# Clone and setup\ngit clone https://github.com/yourusername/splitmate.git\ncd splitmate\ncomposer install \u0026\u0026 npm install\n\n# Database setup\ntouch database/database.sqlite\nphp artisan migrate\n\n# Development server\ncomposer run dev  # Runs Laravel + Vite + Queue + Logs\n```\n\n### Key Development Commands\n```bash\n# Database operations\nphp artisan migrate:fresh --seed  # Reset database with sample data\nphp artisan tinker                # Interactive PHP shell\n\n# Frontend development\nnpm run dev                       # Watch mode with hot reload\nnpm run build                     # Production build\n\n# Testing\nphp artisan test                  # Run all tests\nphp artisan test --coverage       # With coverage report\n```\n\n### Code Structure Guidelines\n- **Controllers**: Handle business logic and data processing\n- **Models**: Define relationships and data access patterns\n- **Views**: Blade templates with Tailwind CSS styling\n- **Migrations**: Database schema changes\n- **JavaScript**: Client-side validation and interactions\n\n## 🤝 Contributing\n\nWe welcome contributions! Here's how to get started:\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Follow coding standards**: Use Laravel Pint for PHP formatting\n4. **Write tests**: Ensure new features are properly tested\n5. **Update documentation**: Keep README and code comments current\n6. **Submit a Pull Request**: Include detailed description of changes\n\n### Areas for Contribution\n- **UI/UX Improvements**: Better mobile experience, animations\n- **Algorithm Enhancements**: More sophisticated debt reduction logic\n- **Testing**: Unit and integration tests\n- **Documentation**: Code comments, API documentation\n- **Performance**: Database optimization, caching strategies\n\n## 📝 License\n\nThis project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n\n## 🆘 Support \u0026 Community\n\n### Getting Help\n1. **Documentation**: Check this README and code comments\n2. **Issues**: Search existing issues or create a new one\n3. **Discussions**: Use GitHub Discussions for questions\n4. **Contact**: Reach out to maintainers for urgent issues\n\n### Reporting Bugs\nWhen reporting bugs, please include:\n- **Steps to reproduce**: Clear, numbered steps\n- **Expected behavior**: What should happen\n- **Actual behavior**: What actually happens\n- **Environment**: PHP version, Laravel version, browser\n- **Screenshots**: If applicable\n\n## 🙏 Acknowledgments\n\n### Core Technologies\n- **[Laravel](https://laravel.com)** - The PHP framework that powers the backend\n- **[Tailwind CSS](https://tailwindcss.com)** - Utility-first CSS framework\n- **[Vite](https://vitejs.dev)** - Fast build tool and dev server\n\n### Inspiration\n- **Real-world problems**: Solving actual group expense management challenges\n- **User experience**: Mobile-first design for practical usage\n- **Mathematical accuracy**: Ensuring fair and transparent calculations\n\n### Special Thanks\n- **Laravel Community** - For the amazing ecosystem and documentation\n- **Open Source Contributors** - For the tools and libraries that make this possible\n- **Beta Testers** - For feedback and bug reports during development\n\n---\n\n## 🎯 Why SplitMate?\n\nSplitMate isn't just another expense splitting app. It's a **sophisticated financial management tool** that handles the complexities of group finances with:\n\n- **Zero Manual Work**: Automatic debt reduction eliminates tedious calculations\n- **Complete Transparency**: Every calculation is explained step-by-step\n- **Mobile-First**: Designed for real-world usage with camera integration\n- **Historical Accuracy**: Maintains data integrity across group changes\n- **Professional Grade**: Built with enterprise-level Laravel architecture\n\n**Ready to revolutionize your group expense management? Let's get splitting! 💸**\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb-dev-nav%2Fsplitmate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweb-dev-nav%2Fsplitmate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweb-dev-nav%2Fsplitmate/lists"}