chitfund/README

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

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

cd luckychit
flutter pub get
flutter run

---

📚 Documentation

Essential Guides

• Admin Features - Complete guide for all admin features
• API Documentation - All API endpoints
• Deployment Guide - Production deployment steps

Additional Docs

• How to Add Past Draws - Import historical data
• WhatsApp Integration - WhatsApp features
• Troubleshooting - 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 ✅