{"id":48552199,"url":"https://github.com/kere-hore/split-bill","last_synced_at":"2026-04-08T09:01:01.008Z","repository":{"id":316624301,"uuid":"1047432193","full_name":"kere-hore/split-bill","owner":"kere-hore","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-16T09:49:55.000Z","size":1809,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-01-16T23:49:08.014Z","etag":null,"topics":["bill","splitter","team"],"latest_commit_sha":null,"homepage":"https://split-bill-mu.vercel.app","language":"TypeScript","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/kere-hore.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","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-08-30T12:09:56.000Z","updated_at":"2026-01-16T09:48:58.000Z","dependencies_parsed_at":"2025-09-25T19:35:31.685Z","dependency_job_id":null,"html_url":"https://github.com/kere-hore/split-bill","commit_stats":null,"previous_names":["kere-hore/split-bill"],"tags_count":3,"template":false,"template_full_name":"pradiktabagus/feature-toggle","purl":"pkg:github/kere-hore/split-bill","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kere-hore%2Fsplit-bill","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kere-hore%2Fsplit-bill/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kere-hore%2Fsplit-bill/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kere-hore%2Fsplit-bill/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kere-hore","download_url":"https://codeload.github.com/kere-hore/split-bill/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kere-hore%2Fsplit-bill/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31547845,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-07T16:28:08.000Z","status":"online","status_checked_at":"2026-04-08T02:00:06.127Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["bill","splitter","team"],"created_at":"2026-04-08T09:00:42.224Z","updated_at":"2026-04-08T09:01:00.998Z","avatar_url":"https://github.com/kere-hore.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg width=\"1200\" height=\"720\" alt=\"Screenshot from 2025-09-21 15-31-10\" src=\"https://github.com/user-attachments/assets/a594ebd8-74d0-4e5d-afb3-a4661885ebda\" /\u003e\n\u003cimg width=\"1200\" height=\"720\" alt=\"Screenshot from 2025-09-21 15-32-00\" src=\"https://github.com/user-attachments/assets/03b75446-2a2e-470c-844d-f43b4b4077cb\" /\u003e\n\n# 💰 Split Bill - Expense Tracker\n\nA modern, full-stack split bill management application built with Next.js, TypeScript, and PostgreSQL. Track shared expenses and calculate splits among friends and groups with real-time updates.\n\n## ✨ Features\n\n- 🔐 **Authentication**: Clerk with Email, Google \u0026 GitHub OAuth\n- 👥 **Group Management**: Create and manage expense groups with member invitations\n- 💸 **Expense Tracking**: Add, edit, delete shared expenses with receipt upload\n- 📷 **OCR Receipt Scanning**: Google Vision API for automatic expense extraction\n- 🧮 **Smart Splitting**: Automatic calculation of who owes what with custom allocations\n- 💳 **Settlement Tracking**: Record payments between group members\n- 📱 **WhatsApp Integration**: Broadcast allocation summaries via WhatsApp\n- 🌐 **Public Bill Sharing**: Share expense summaries with public URLs\n- 📊 **Dashboard**: Overview of all groups and balances\n- 🎨 **Modern UI**: Built with shadcn/ui and Tailwind CSS\n- 🌙 **Dark Mode**: Full theme switching support\n- 📱 **Responsive**: Mobile-first design\n- 🔄 **Real-time**: Optimistic UI updates\n- 🛡️ **Type Safe**: Full TypeScript coverage\n- 🗄️ **Database**: PostgreSQL with Prisma ORM\n- 📚 **API Documentation**: Comprehensive Swagger/OpenAPI documentation\n- ☁️ **CloudFront CDN**: Global edge caching for public APIs\n- 🚀 **S3 Integration**: File storage and cache management\n- ⚡ **Auto-Invalidation**: Instant cache updates on data changes\n\n## 🛠️ Tech Stack\n\n- **Framework**: Next.js 15.4.6\n- **Language**: TypeScript\n- **Database**: PostgreSQL\n- **ORM**: Prisma\n- **Authentication**: Clerk\n- **OCR**: Google Cloud Vision API\n- **Messaging**: WhatsApp URL generation\n- **UI**: shadcn/ui + Tailwind CSS\n- **Package Manager**: Bun\n- **Deployment**: Vercel\n- **CDN**: AWS CloudFront\n- **Storage**: AWS S3\n- **Cache**: CloudFront + S3 hybrid caching\n\n## 📋 Prerequisites\n\n### Required Services\n\n1. **PostgreSQL Database** - Database hosting (Neon, Supabase, or local)\n2. **Clerk Account** - Authentication service\n3. **Google Cloud Platform** - Vision API for OCR\n4. **Vercel Account** - Deployment platform\n5. **AWS Account** - S3 storage and CloudFront CDN\n6. **AWS S3 Bucket** - File storage and caching\n7. **AWS CloudFront Distribution** - Global CDN\n\n### Development Tools\n\n- Node.js 18+ or Bun\n- Git\n\n## 🚀 Quick Start\n\n### 1. Clone Repository\n\n```bash\ngit clone https://github.com/pradiktabagus/split-bill.git\ncd split-bill\n```\n\n### 2. Install Dependencies\n\n```bash\nbun install\n# or\nnpm install\n```\n\n### 3. Environment Setup\n\nCopy `.env.example` to `.env.local`:\n\n```bash\ncp .env.example .env.local\n```\n\nFill in your environment variables:\n\n```env\n# Database\nDATABASE_URL=\"postgresql://username:password@localhost:5432/split-bill\"\n\n# Clerk Authentication\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=\"pk_test_...\"\nCLERK_SECRET_KEY=\"sk_test_...\"\nNEXT_PUBLIC_CLERK_SIGN_IN_URL=\"/sign-in\"\nNEXT_PUBLIC_CLERK_SIGN_UP_URL=\"/sign-up\"\nNEXT_PUBLIC_CLERK_AFTER_SIGN_IN_URL=\"/dashboard\"\nNEXT_PUBLIC_CLERK_AFTER_SIGN_UP_URL=\"/dashboard\"\n\n# Google Cloud Vision API\nGOOGLE_CLOUD_PROJECT_ID=\"your-project-id\"\nGOOGLE_CLOUD_PRIVATE_KEY=\"-----BEGIN PRIVATE KEY-----\\n...\\n-----END PRIVATE KEY-----\\n\"\nGOOGLE_CLOUD_CLIENT_EMAIL=\"your-service-account@project.iam.gserviceaccount.com\"\n\n# AWS Configuration\nAWS_ACCESS_KEY_ID=\"your-aws-access-key\"\nAWS_SECRET_ACCESS_KEY=\"your-aws-secret-key\"\nAWS_REGION=\"ap-southeast-1\"\nS3_BUCKET_NAME=\"split-bill-cache\"\nCLOUDFRONT_DISTRIBUTION_ID=\"your-cloudfront-distribution-id\"\nNEXT_PUBLIC_CLOUDFRONT_URL=\"https://your-domain.cloudfront.net\"\n\n# Cache Configuration (in seconds)\nBROWSER_CACHE_SECONDS=300      # Browser cache: 5 minutes\nCLOUDFRONT_CACHE_SECONDS=3600  # CloudFront cache: 1 hour\n```\n\n### 4. Database Setup\n\n```bash\n# Generate Prisma client\nbun run db:generate\n\n# Push schema to database\nbun run db:push\n```\n\n### 5. Run Development Server\n\n```bash\nbun dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) in your browser.\n\n## 📄 Configuration Files\n\n### Core Configuration\n\n- **`package.json`** - Dependencies, scripts, and project metadata\n- **`tsconfig.json`** - TypeScript compiler configuration\n- **`next.config.ts`** - Next.js framework configuration\n- **`tailwind.config.ts`** - Tailwind CSS styling configuration\n- **`prisma/schema.prisma`** - Database schema and ORM configuration\n\n### UI \u0026 Components\n\n- **`components.json`** - shadcn/ui component library configuration\n  - Defines component paths and aliases\n  - Sets up Tailwind integration\n  - Configures icon library (Lucide)\n\n### Deployment \u0026 Infrastructure\n\n- **`vercel.json`** - Vercel deployment configuration\n  - Sets API function timeout (30s)\n  - Optimizes serverless function performance\n- **`aws-iam-policy.json`** - AWS IAM permissions template\n  - S3 bucket access (read/write/delete)\n  - CloudFront invalidation permissions\n  - Use this to create IAM policy in AWS Console\n\n### Environment Files\n\n- **`.env.local`** - Local development environment variables\n- **`.env.example`** - Template for required environment variables\n- **`.gitignore`** - Files and folders excluded from Git\n\n### Development Tools\n\n- **`.eslintrc.json`** - Code linting rules and configuration\n- **`bun.lockb`** - Dependency lock file for Bun package manager\n\n## 🔧 Setup Guide\n\n### PostgreSQL Database Setup\n\n1. **Option 1 - Neon (Recommended)**:\n\n   - Create account at [Neon](https://neon.tech/)\n   - Create new database\n   - Copy connection string to `DATABASE_URL`\n\n2. **Option 2 - Supabase**:\n\n   - Create account at [Supabase](https://supabase.com/)\n   - Create new project\n   - Get database URL from settings\n\n3. **Option 3 - Local PostgreSQL**:\n   - Install PostgreSQL locally\n   - Create database: `createdb split-bill`\n   - Use: `postgresql://username:password@localhost:5432/split-bill`\n\n### Clerk Setup\n\n1. Go to [Clerk Dashboard](https://dashboard.clerk.com/)\n2. Create new application\n3. Choose authentication methods:\n   - Email/Password\n   - Google OAuth\n   - GitHub OAuth\n4. Configure redirect URLs:\n   - Sign-in URL: `/sign-in`\n   - Sign-up URL: `/sign-up`\n   - After sign-in: `/dashboard`\n   - After sign-up: `/dashboard`\n5. Copy API keys to `.env.local`\n\n### Google Cloud Vision API Setup\n\n1. Go to [Google Cloud Console](https://console.cloud.google.com/)\n2. Create new project or select existing one\n3. Enable Vision API\n4. Create service account with Vision API permissions\n5. Download service account JSON key\n6. Extract credentials to environment variables\n\n### AWS Setup\n\n1. Create AWS account and get access keys\n2. Create S3 bucket for file storage\n3. Create CloudFront distribution pointing to your API\n4. Set up IAM permissions for S3 and CloudFront access\n5. Configure CloudFront to cache `/api/public/*` paths\n\n## 📦 Available Scripts\n\n```bash\n# Development\nbun dev              # Start development server\nbun build            # Build for production\nbun start            # Start production server\n\n# Database\nbun run db:generate  # Generate Prisma client\nbun run db:push      # Push schema to database\nbun run db:studio    # Open Prisma Studio\n\n# Deployment\nbun run deploy       # Deploy to Vercel\n```\n\n## 🚀 Deployment\n\nThis project uses a **release-based deployment strategy** with multiple environments:\n\n```\nDevelopment → Master (Staging) → Release Tag → Production\n```\n\n### Deployment Environments\n\n#### 1. **Preview Deployments**\n\n- **Trigger**: Pull Request to master\n- **Environment**: Vercel Preview\n- **Purpose**: Feature testing before merge\n\n#### 2. **Staging Deployment**\n\n- **Trigger**: Push to `master` branch\n- **Environment**: Vercel Preview (staging)\n- **Purpose**: Integration testing and UAT\n\n#### 3. **Production Deployment**\n\n- **Trigger**: Release tag published\n- **Environment**: Vercel Production\n- **URL**: https://split-bill-mu.vercel.app/\n\n### How to Deploy to Production\n\n#### Method 1: Automated Release (Recommended)\n\n1. **Create Release via GitHub Actions**:\n\n   - Go to GitHub → Actions → \"Create Release\"\n   - Click \"Run workflow\"\n   - Enter version (e.g., `v1.2.0`)\n   - Add release notes (optional)\n   - Click \"Run workflow\"\n\n2. **Automated Process**:\n   - Runs tests and build validation\n   - Generates changelog from commits\n   - Creates release tag\n   - Triggers production deployment\n\n#### Method 2: Manual Release\n\n1. **Create and push tag**:\n\n   ```bash\n   git tag -a v1.2.0 -m \"Release version 1.2.0\"\n   git push origin v1.2.0\n   ```\n\n2. **Create GitHub Release**:\n   - Go to GitHub → Releases → \"Create a new release\"\n   - Select the tag\n   - Add release notes\n   - Click \"Publish release\"\n\n### Environment Variables Setup\n\nSet these in GitHub Secrets for CI/CD:\n\n```bash\n# Production\nDATABASE_URL\nNEXT_PUBLIC_CLERK_PUBLISHABLE_KEY\nCLERK_SECRET_KEY\nVERCEL_TOKEN\nVERCEL_ORG_ID\nVERCEL_PROJECT_ID\n\n# Staging (Optional)\nSTAGING_DATABASE_URL\nSTAGING_CLERK_PUBLISHABLE_KEY\nSTAGING_CLERK_SECRET_KEY\n\n# Shared\nGEMINI_API_KEY\nDEEPSEEK_API_KEY\n```\n\n### Manual Vercel Setup (First Time)\n\n1. **Install Vercel CLI**:\n\n   ```bash\n   bun add -g vercel\n   ```\n\n2. **Login and Link Project**:\n\n   ```bash\n   vercel login\n   vercel link\n   ```\n\n3. **Set Environment Variables**:\n   ```bash\n   vercel env add DATABASE_URL production\n   vercel env add NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY production\n   # ... add other variables\n   ```\n\n### Release Process Documentation\n\nFor detailed release process, see [Release Process Guide](./.github/RELEASE_PROCESS.md).\n\n### Rollback Process\n\nIf issues occur in production:\n\n1. **Quick Rollback**: Deploy previous release tag via GitHub Actions\n2. **Hotfix**: Create hotfix branch, merge to master, create patch release\n\n## 🎯 Usage\n\n### Managing Split Bills\n\n1. Login with Email, Google, or GitHub\n2. Create a new group for shared expenses\n3. Invite members to the group via email or username\n4. Add expenses by:\n   - Manual entry with description and amount\n   - Upload receipt image for OCR scanning\n   - System extracts expense details automatically\n5. Configure expense allocation (equal split or custom amounts)\n6. Save allocations and generate WhatsApp broadcast messages\n7. Track settlements and payment status between members\n8. Share public bill summaries with group members\n9. View dashboard for overview of all groups and balances\n\n### API Endpoints\n\n- `GET /api/groups` - List user's groups\n- `POST /api/groups` - Create new group\n- `PUT /api/groups/[id]` - Update group\n- `DELETE /api/groups/[id]` - Delete group\n- `GET /api/groups/[id]/bills` - Get group bills\n- `POST /api/groups/[id]/bills` - Create new bill\n- `GET /api/groups/[id]/allocations` - Get allocations\n- `POST /api/groups/[id]/allocations` - Save allocations with WhatsApp broadcast\n- `POST /api/ocr` - Process receipt image with OCR\n- `GET /api/settlements` - List settlements\n- `POST /api/settlements` - Record payment\n- `PATCH /api/settlements/[id]/status` - Update payment status\n- `GET /api/public/bills/[groupId]` - Get public bill summary (cached)\n- `GET /api/public/allocations/[groupId]/[memberId]` - Get member allocations (cached)\n- `GET /api/docs` - Swagger API documentation\n\n### Caching Strategy\n\n- **Public API**: Cached via CloudFront + S3 hybrid\n- **Auto-Invalidation**: Cache cleared on bill/allocation updates\n- **Cache Headers**: Configurable via environment variables\n- **Monitoring**: CloudFront hit/miss tracking in response headers\n- **OCR Results**: Cached in S3 for performance\n- **Static Assets**: Optimized delivery via CloudFront\n\n## 🔒 Security Features\n\n- ✅ Authentication required for all operations\n- ✅ CSRF protection via Clerk\n- ✅ Input validation with Zod schemas\n- ✅ Type-safe database operations\n- ✅ Environment variable security\n- ✅ AWS IAM permissions for S3/CloudFront\n- ✅ Google Cloud service account security\n- ✅ Public API rate limiting via CloudFront\n- ✅ Secure file uploads to S3\n- ✅ OCR data sanitization\n- ✅ Group member access control\n- ✅ Public URL access restrictions\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create feature branch (`git checkout -b feature/amazing-feature`)\n3. Follow Feature-Sliced Design (FSD) architecture\n4. Add comprehensive API documentation\n5. Include tests for new features\n6. Commit changes (`git commit -m 'Add amazing feature'`)\n7. Push to branch (`git push origin feature/amazing-feature`)\n8. Open Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## 🆘 Support\n\nIf you encounter any issues:\n\n1. Check the [Issues](https://github.com/pradiktabagus/split-bill/issues) page\n2. Review the comprehensive API documentation at `/api/docs`\n3. Check troubleshooting guide in project rules\n4. Create a new issue with detailed description\n5. Include error logs and environment details\n\n## 🎉 Demo\n\nLive demo: [https://split-bill-mu.vercel.app](https://split-bill-mu.vercel.app)\n\n## 🎯 Key Features Highlights\n\n### 📷 OCR Receipt Scanning\n\n- Upload receipt images (JPEG, PNG, WebP)\n- Automatic text extraction using Google Vision API\n- Smart parsing of merchant, amount, and date\n- Fallback to manual entry if OCR fails\n- Support for various receipt formats\n\n### 📱 WhatsApp Integration\n\n- Generate WhatsApp broadcast URLs\n- Pre-filled messages with allocation summaries\n- One-click sharing with group members\n- Custom message formatting\n- Auto-open WhatsApp with payment details\n\n### 🌐 Public Bill Sharing\n\n- Generate public URLs for bill summaries\n- Share expense details without requiring login\n- Cached for fast loading worldwide\n- Mobile-optimized public pages\n- Individual member allocation views\n\n### 📚 Comprehensive API Documentation\n\n- Complete Swagger/OpenAPI specification\n- Interactive API explorer\n- Detailed request/response examples\n- Error handling documentation\n- Performance and caching information\n\n---\n\n**Built with ❤️ using Next.js and modern web technologies**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkere-hore%2Fsplit-bill","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkere-hore%2Fsplit-bill","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkere-hore%2Fsplit-bill/lists"}