# LuckyChit - Chit Fund Management System

A complete, production-ready chit fund management application with Flutter frontend and Node.js backend.

## 🎯 Features

### For Managers
- ✅ Create and manage multiple chit groups
- ✅ Add members to groups (with auto-assigned member numbers #1, #2, #3...)
- ✅ Conduct monthly draws with animated lottery system
- ✅ Track payments and generate receipts
- ✅ **Complete admin controls**: Edit/delete draws, groups, and member details
- ✅ WhatsApp integration for notifications
- ✅ Financial reports and analytics
- ✅ Import existing groups with historical data

### For Members
- ✅ View all groups they belong to
- ✅ Track payment history
- ✅ View draw results
- ✅ Verify draws using provably fair system
- ✅ Receive payment reminders

### Accessibility
- ✅ **Optimized for elderly users (50+)** with 30% larger fonts
- ✅ High contrast colors for better visibility
- ✅ Large touch targets (WCAG AAA compliant)
- ✅ Simple member numbers instead of complex UUIDs

---

## 📁 Project Structure

```
chitfund/
├── backend/              # Node.js + Express + PostgreSQL
│   ├── src/
│   │   ├── controllers/  # Business logic
│   │   ├── models/       # Database models
│   │   ├── routes/       # API routes
│   │   └── services/     # Background services
│   └── migrations/       # Database migrations
│
├── luckychit/           # Flutter mobile app
│   ├── lib/
│   │   ├── core/        # Services, models, themes
│   │   ├── features/    # Feature modules
│   │   ├── interfaces/  # UI screens
│   │   └── shared/      # Shared widgets
│   └── assets/          # Images, fonts, icons
│
└── docs/                # Additional documentation
```

---

## 🚀 Quick Start

### Backend Setup
```bash
cd backend
npm install
cp env.example .env
# Edit .env with your database credentials
npm start
```

See `backend/README.md` for detailed setup instructions.

### Frontend Setup
```bash
cd luckychit
flutter pub get
flutter run
```

---

## 📚 Documentation

### Essential Guides
- **[Admin Features](./ADMIN_GUIDE.md)** - Complete guide for all admin features
- **[API Documentation](./backend/API_DOCUMENTATION.md)** - All API endpoints
- **[Deployment Guide](./DEPLOYMENT.md)** - Production deployment steps

### Additional Docs
- **[How to Add Past Draws](./HOW_TO_ADD_PAST_DRAWS.md)** - Import historical data
- **[WhatsApp Integration](./backend/WHATSAPP_USAGE_EXAMPLES.md)** - WhatsApp features
- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and fixes

---

## 🔑 Key Features

### Member Numbers
Each member gets a readable serial number (#1, #2, #3...) instead of just UUID:
- Easy to reference: "Call Member #5"
- Large display for elderly users
- Unique per group
- Auto-assigned when member joins

### Admin Controls
Managers can:
- ✅ Edit/delete monthly draws (fix mistakes)
- ✅ Edit member details (name, phone, email)
- ✅ Edit group details (before starting)
- ✅ Delete empty groups
- ✅ Remove members from groups (without deleting user account)

### Accessibility
Designed for elderly users with:
- 30% larger fonts throughout
- High contrast colors (pure black on white)
- Large buttons (67px height)
- Bold text for clarity
- Simple member numbers

### Provably Fair Draws
- Cryptographic verification
- Multiple animation options (wheel, roulette, cards)
- Transparent and auditable
- Screen recording capability

---

## 🛠️ Tech Stack

### Backend
- Node.js + Express
- PostgreSQL (Sequelize ORM)
- JWT authentication
- WhatsApp integration
- PM2 for process management

### Frontend
- Flutter (cross-platform)
- GetX (state management)
- ScreenUtil (responsive design)
- Dio (HTTP client)

---

## 📱 Supported Platforms

- ✅ Android
- ✅ iOS
- ✅ Web
- ⏳ Windows/Mac/Linux (Flutter supports, not tested)

---

## 🔐 Security Features

- JWT token authentication
- Password hashing (bcrypt)
- Manager-only operations
- Rate limiting
- Input validation
- SQL injection protection

---

## 📊 Database Schema

### Main Tables
- `users` - User accounts (managers and members)
- `chit_groups` - Chit fund groups
- `group_members` - Member relationships with **member_number**
- `monthly_draws` - Draw results
- `payments` - Payment records
- `notifications` - Notification log

---

## 🎨 Screenshots

*Add screenshots of your app here*

---

## 📝 License

*Add your license here*

---

## 👥 Credits

Developed for managing chit funds with ease, especially designed for elderly users.

---

## 📞 Support

For issues or questions, see `TROUBLESHOOTING.md` or contact support.

---

**Version**: 2.0 (November 2025)  
**Status**: Production Ready ✅