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"
+[](https://nextjs.org/)
+[](https://www.typescriptlang.org/)
+[](LICENSE)
+[](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)
+
+[](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!
+
+