From 91969c525f98da8988ba38ca5de834f8ba30f8d3 Mon Sep 17 00:00:00 2001 From: "tembo[bot]" <208362400+tembo[bot]@users.noreply.github.com> Date: Wed, 3 Dec 2025 22:50:22 +0000 Subject: [PATCH] docs(README): overhaul with detailed sections, badges, and structure Co-authored-by: Anurag --- README.md | 435 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 339 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index b82fe51..2a8d6bf 100644 --- a/README.md +++ b/README.md @@ -1,119 +1,262 @@ -# SplitSimple +
-A modern, collaborative bill-splitting app with real-time sync and universal sharing. Split bills with friends effortlessly, whether you're dining out, sharing expenses, or planning group activities. +# ๐Ÿงพ SplitSimple -## โœจ Key Features +**A modern, collaborative bill-splitting app with real-time sync and universal sharing** -### ๐Ÿ”— **Universal Sharing & Collaboration** -* **Shareable Links**: Generate unique URLs that work for anyone, anywhere -* **Real-time Collaboration**: Multiple people can edit the same bill simultaneously -* **Cloud Sync**: Automatic syncing with visual status indicators -* **No Accounts Required**: Anonymous, temporary bill storage (auto-deletes after ~6 months) +Split bills with friends effortlessly, whether you're dining out, sharing expenses, or planning group activities. -### ๐Ÿ’ฐ **Smart Bill Management** -* **Intelligent Status System**: Draft โ†’ Active โ†’ Closed workflow with contextual actions -* **Flexible Splitting**: Split items evenly, by shares, percentage, or exact amounts -* **Tax & Tip Allocation**: Distribute proportionally or evenly among participants -* **Accurate Calculations**: Precision math to avoid "penny problems" +[![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat&logo=next.js)](https://nextjs.org/) +[![TypeScript](https://img.shields.io/badge/TypeScript-5-blue?style=flat&logo=typescript)](https://www.typescriptlang.org/) +[![License](https://img.shields.io/badge/license-MIT-green?style=flat)](LICENSE) +[![Tests](https://img.shields.io/badge/tests-79%20passing-success?style=flat)](https://github.com/Aarekaz/splitsimple) -### ๐ŸŽจ **Modern User Experience** -* **Clean Interface**: Simplified item entry and intuitive controls -* **Drag & Drop**: Reorder items with smooth animations -* **Auto-collapse**: Focus on active items while keeping interface clean -* **Responsive Design**: Optimized for both desktop and mobile devices +[Features](#-features) โ€ข [Quick Start](#-quick-start) โ€ข [Demo](#-demo) โ€ข [Architecture](#๏ธ-architecture) โ€ข [Contributing](#-contributing) -### โšก **Power Features** -* **Keyboard Shortcuts**: `Enter` to add items, `Cmd/Ctrl+D` to duplicate, arrow navigation -* **Export Options**: Copy text summaries or download CSV files -* **Visual Feedback**: Success animations, hover effects, and smooth transitions -* **Persistent State**: Never lose your work with automatic local storage +
-## ๐Ÿš€ Getting Started +--- + +## โœจ Features + +### ๐Ÿ”— Universal Sharing & Collaboration +- **Shareable Links** โ€” Generate unique URLs that work for anyone, anywhere +- **Real-time Collaboration** โ€” Multiple people can edit the same bill simultaneously +- **Cloud Sync** โ€” Automatic syncing with visual status indicators +- **No Accounts Required** โ€” Anonymous, temporary bill storage (auto-deletes after ~6 months) + +### ๐Ÿ’ฐ Smart Bill Management +- **Intelligent Status System** โ€” Draft โ†’ Active โ†’ Closed workflow with contextual actions +- **Flexible Splitting** โ€” Split items evenly, by shares, percentage, or exact amounts +- **Tax & Tip Allocation** โ€” Distribute proportionally or evenly among participants +- **Accurate Calculations** โ€” Precision math to avoid "penny problems" + +### ๐ŸŽจ Modern User Experience +- **Clean Interface** โ€” Simplified item entry and intuitive controls +- **Drag & Drop** โ€” Reorder items with smooth animations +- **Auto-collapse** โ€” Focus on active items while keeping interface clean +- **Responsive Design** โ€” Optimized for both desktop and mobile devices + +### โšก Power Features +- **Keyboard Shortcuts** โ€” `Enter` to add items, `Cmd/Ctrl+D` to duplicate, arrow navigation +- **Export Options** โ€” Copy text summaries or download CSV files +- **Visual Feedback** โ€” Success animations, hover effects, and smooth transitions +- **Persistent State** โ€” Never lose your work with automatic local storage +- **Undo/Redo** โ€” Full history tracking (50 actions) + +--- + +## ๐Ÿš€ Quick Start ### Prerequisites -* Node.js 18+ and pnpm - -### Local Development -1. **Clone and install:** - ```sh - git clone https://github.com/aarekaz/splitsimple - cd splitsimple - pnpm install - ``` - -2. **Set up Redis (for sharing features):** - ```sh - # Create .env.local with your Redis URL - echo 'REDIS_URL="your-redis-url-here"' > .env.local - ``` - -3. **Run the development server:** - ```sh - pnpm dev - ``` - -4. **Open [http://localhost:3000](http://localhost:3000)** in your browser - -### Development Commands -* `pnpm dev` - Start development server -* `pnpm build` - Build for production -* `pnpm start` - Start production server -* `pnpm test` - Run all tests -* `pnpm test:watch` - Run tests in watch mode -* `pnpm test:coverage` - Run tests with coverage report -* `pnpm lint` - Check code style -* `pnpm type-check` - Run TypeScript checks - -### Deployment -Deploy to Vercel with Redis KV for full sharing functionality: -1. Connect your GitHub repo to Vercel -2. Add a Redis database from Vercel's marketplace -3. Deploy - sharing and collaboration work automatically! - -## ๐ŸŽฏ Perfect For - -* **Restaurant bills** - Split dinner costs among friends -* **Group trips** - Track shared expenses and settlements -* **Roommate expenses** - Fairly divide household costs -* **Event planning** - Manage group purchases and contributions + +Ensure you have the following installed: +- **Node.js** 18+ ([Download](https://nodejs.org/)) +- **pnpm** 9+ (`npm install -g pnpm`) +- **Redis** URL for sharing features (optional for local dev) + +### Installation + +```bash +# Clone the repository +git clone https://github.com/aarekaz/splitsimple.git +cd splitsimple + +# Install dependencies +pnpm install + +# Set up environment variables +cp .env.example .env.local +# Edit .env.local and add your REDIS_URL +``` + +### Environment Configuration + +Create a `.env.local` file in the root directory: + +```ini +# Required for sharing features +REDIS_URL="redis://your-redis-url-here" + +# Optional analytics +NEXT_PUBLIC_POSTHOG_KEY="your-posthog-key" +NEXT_PUBLIC_POSTHOG_HOST="https://app.posthog.com" + +# Optional receipt scanning +OCR_PROVIDER="google" # or "openai" or "anthropic" +GOOGLE_AI_API_KEY="your-google-ai-key" +OPENAI_API_KEY="your-openai-key" +ANTHROPIC_API_KEY="your-anthropic-key" +``` + +> **Note:** The app works without Redis for local-only bill management. OCR features fall back to mock data if keys are not provided. + +### Development + +```bash +# Start the development server +pnpm dev + +# Open http://localhost:3000 in your browser +``` + +### Available Scripts + +| Command | Description | +|---------|-------------| +| `pnpm dev` | Start development server | +| `pnpm dev:clean` | Clear cache and start dev server | +| `pnpm build` | Build for production | +| `pnpm start` | Start production server | +| `pnpm lint` | Run ESLint checks | +| `pnpm typecheck` | Run TypeScript type checking | +| `pnpm test` | Run all tests | +| `pnpm test:watch` | Run tests in watch mode | +| `pnpm test:coverage` | Generate coverage report | + +--- + +## ๐ŸŽฏ Use Cases + + + + + + + + +
+ +**๐Ÿฝ๏ธ Restaurant Bills** + +Split dinner costs fairly among friends with per-item tracking + + + +**โœˆ๏ธ Group Trips** + +Track shared expenses and settlements for vacations + + + +**๐Ÿ  Roommate Expenses** + +Fairly divide household costs and utilities + + + +**๐ŸŽ‰ Event Planning** + +Manage group purchases and contributions + +
+ +--- ## ๐Ÿ—๏ธ Architecture -### Core Technologies -* **Next.js 15** - React framework with App Router -* **TypeScript** - Type-safe development with strict mode -* **Tailwind CSS v4** - Modern utility-first styling -* **Redis** - Cloud storage for bill sharing -* **shadcn/ui** - High-quality component library +### Tech Stack + + + + + + + +
+ +**Frontend** +- Next.js 15 (App Router) +- React 19 +- TypeScript 5 +- Tailwind CSS v4 +- shadcn/ui components +- Radix UI primitives + + + +**State & Data** +- React Context + useReducer +- Local Storage persistence +- Redis for cloud sync +- Real-time collaboration +- Undo/Redo system + + -### State Management -* **React Context + useReducer** - Predictable state management -* **Local Storage** - Persistent bill data -* **Real-time Sync** - Automatic cloud synchronization -* **Undo/Redo System** - Full history tracking (50 actions) +**Developer Experience** +- Jest + React Testing Library +- MSW for API mocking +- GitHub Actions CI/CD +- ESLint + TypeScript strict mode +- Vercel Analytics + +
+ +### Project Structure + +``` +splitsimple/ +โ”œโ”€โ”€ app/ # Next.js App Router +โ”‚ โ”œโ”€โ”€ api/ # API routes (sharing, sync) +โ”‚ โ””โ”€โ”€ page.tsx # Main bill-splitting page +โ”œโ”€โ”€ components/ # React components +โ”‚ โ”œโ”€โ”€ bill/ # Bill management UI +โ”‚ โ”œโ”€โ”€ mobile/ # Mobile-optimized views +โ”‚ โ””โ”€โ”€ ui/ # shadcn/ui components +โ”œโ”€โ”€ contexts/ # React Context providers +โ”‚ โ””โ”€โ”€ BillContext.tsx # Global state management +โ”œโ”€โ”€ lib/ # Core logic +โ”‚ โ”œโ”€โ”€ calculations.ts # Bill splitting math +โ”‚ โ”œโ”€โ”€ validation.ts # Input sanitization +โ”‚ โ””โ”€โ”€ export.ts # Export utilities +โ”œโ”€โ”€ hooks/ # Custom React hooks +โ”œโ”€โ”€ tests/ # Test suite +โ””โ”€โ”€ public/ # Static assets +``` ### Key Features Implementation -* **Mathematical Precision** - Cent-based calculations to avoid floating-point errors -* **XSS Prevention** - Input sanitization and validation -* **Drag & Drop** - Smooth item reordering with @dnd-kit -* **Responsive Design** - Mobile-first approach with adaptive layouts -## ๐Ÿงช Testing & Quality Assurance +**Mathematical Precision** +- Cent-based calculations to avoid floating-point errors +- Rounding strategies that eliminate "penny problems" +- Proportional distribution algorithms for tax/tip + +**Security** +- XSS prevention through input sanitization +- Zod schema validation +- Redis data expiration (6 months) +- No user authentication required -### Testing Stack -* **Jest** - Test framework with 70% coverage targets -* **React Testing Library** - Component testing utilities -* **MSW** - API mocking for integration tests -* **GitHub Actions** - Automated CI/CD pipeline +**Real-time Collaboration** +- WebSocket-like sync with Redis pub/sub +- Optimistic UI updates +- Conflict resolution for concurrent edits + +**Responsive Design** +- Mobile-first approach +- Dedicated mobile sheets and modals +- Touch-friendly interactions +- Adaptive layouts for all screen sizes + +--- + +## ๐Ÿงช Testing & Quality ### Test Coverage -* **98% calculations.ts** - Business logic validation -* **96% validation.ts** - Input sanitization and security -* **95% BillContext.tsx** - State management integrity -* **79 passing tests** - Comprehensive test suite + +We maintain high test coverage for critical components: + +| Module | Coverage | Tests | +|--------|----------|-------| +| `calculations.ts` | 98% | Business logic validation | +| `validation.ts` | 96% | Input sanitization | +| `BillContext.tsx` | 95% | State management | +| **Overall** | **70%+** | **79 passing tests** | ### Running Tests -```sh + +```bash # Run all tests pnpm test @@ -127,4 +270,104 @@ pnpm test:coverage pnpm test calculations ``` -Built with **Next.js**, **TypeScript**, **Tailwind CSS**, and **Redis** for a fast, reliable experience. +### Continuous Integration + +Our CI pipeline runs on every push: +- โœ… ESLint code quality checks +- โœ… TypeScript type checking +- โœ… Unit tests with coverage reporting +- โœ… Integration tests with Redis +- โœ… Build verification + +--- + +## ๐Ÿšข Deployment + +### Deploy to Vercel (Recommended) + +[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/aarekaz/splitsimple) + +1. **Connect Repository** โ€” Link your GitHub repo to Vercel +2. **Add Redis Database** โ€” Provision Vercel KV or connect external Redis +3. **Configure Environment** โ€” Set `REDIS_URL` in Vercel dashboard +4. **Deploy** โ€” Sharing and collaboration work automatically! + +### Manual Deployment + +```bash +# Build the application +pnpm build + +# Start production server +pnpm start +``` + +For other platforms (AWS, Google Cloud, etc.), ensure you: +- Set environment variables (especially `REDIS_URL`) +- Configure Redis for sharing features +- Use Node.js 18+ runtime + +--- + +## ๐Ÿ“– Documentation + +Additional documentation is available in the repository: + +- [**Testing Guide**](README-testing.md) โ€” Comprehensive testing documentation +- [**Infrastructure**](INFRASTRUCTURE.md) โ€” Deployment and scaling guide +- [**Analytics**](ANALYTICS.md) โ€” PostHog integration details +- [**Receipt Scanning**](RECEIPT_SCANNING_SETUP.md) โ€” OCR feature setup +- [**Changelog**](changelog.md) โ€” Version history + +--- + +## ๐Ÿค Contributing + +We welcome contributions! Here's how you can help: + +1. **Fork the repository** +2. **Create a feature branch** (`git checkout -b feature/amazing-feature`) +3. **Make your changes** +4. **Run tests** (`pnpm test`) +5. **Commit your changes** (`git commit -m 'Add amazing feature'`) +6. **Push to the branch** (`git push origin feature/amazing-feature`) +7. **Open a Pull Request** + +### Development Guidelines + +- Write tests for new features +- Maintain or improve code coverage +- Follow existing code style +- Update documentation as needed +- Keep commits atomic and well-described + +--- + +## ๐Ÿ“ License + +This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. + +--- + +## ๐Ÿ™ Acknowledgments + +Built with these amazing open-source projects: + +- [Next.js](https://nextjs.org/) โ€” React framework +- [shadcn/ui](https://ui.shadcn.com/) โ€” Component library +- [Tailwind CSS](https://tailwindcss.com/) โ€” Utility-first CSS +- [Radix UI](https://www.radix-ui.com/) โ€” Accessible components +- [dnd-kit](https://dndkit.com/) โ€” Drag and drop +- [Redis](https://redis.io/) โ€” In-memory database + +--- + +
+ +**Made with โค๏ธ by the SplitSimple team** + +[Report Bug](https://github.com/aarekaz/splitsimple/issues) โ€ข [Request Feature](https://github.com/aarekaz/splitsimple/issues) โ€ข [GitHub](https://github.com/aarekaz/splitsimple) + +โญ Star us on GitHub โ€” it helps! + +