201 lines
4.7 KiB
Markdown
201 lines
4.7 KiB
Markdown
# 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 ✅
|