deepkoluguri
/
chitfund
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
chitfund/LuckyChit_Development_Plan_...

572 lines
25 KiB
Markdown
Raw Blame History

# LuckyChit - Revised Development Plan
## Digital Platform for Lottery-Based Indian Chit Funds
### Executive Summary
LuckyChit is a **Flutter Web-based** digital solution designed to streamline traditional Indian lottery-based chit funds. The platform consists of a **single Flutter Web application** with **dual interfaces** - a **Manager Dashboard** and a **Member Dashboard**, implementing a fixed prize, winner-by-lottery system without auctions or dividends. The MVP approach focuses on manager-controlled onboarding and core functionality validation through a unified web experience.
---
## 1. Detailed Feature List (User Stories)
### 1.1 Onboarding & Authentication (MVP Approach)
#### Manager Account Creation
- **As a Manager**, I want to create an account (e.g., with a mobile number and a temporary password) for a new member, so I can securely add trusted individuals to my chit groups.
- **As a Manager**, I want to manage all member accounts from my web dashboard, so I have complete control over who joins my groups.
- **As a Manager**, I want to reset member passwords when needed, so I can help members who forget their credentials.
#### Member First-Time Login
- **As a new Member**, I want to log in for the first time using the credentials given by my manager and be prompted to set a new, secure password, so my account is private and accessible only to me.
- **As a Member**, I want to update my profile information after first login, so my details are accurate in the system.
- **As a Member**, I want to set up my preferred payment methods, so I can easily make monthly payments.
### 1.2 Chit Manager Features (Flutter Web Dashboard)
#### Dashboard
- **As a Manager**, I want a comprehensive web dashboard to view all my chit groups, see upcoming payment deadlines, track total collections, and see the next draw dates at a glance.
- **As a Manager**, I want to see real-time statistics including total members, active groups, and monthly collections across all my groups.
- **As a Manager**, I want to view pending actions like member approvals and payment reconciliations in a prioritized list.
- **As a Manager**, I want to see quick summaries of recent draws and upcoming events.
#### Chit Group Creation
- **As a Manager**, I want to create a new chit group, defining its value (e.g., ₹1,00,000), duration (20 months), number of members (20), monthly installment (₹5,000), and my fixed commission percentage (e.g., 5%).
- **As a Manager**, I want to set the monthly installment amount and draw date for each group.
- **As a Manager**, I want to configure payment reminders and late payment policies.
- **As a Manager**, I want to generate unique group codes for easy member identification.
#### Member Management
- **As a Manager**, I want to add my registered members to a specific chit group, monitor their real-time payment status (Paid/Unpaid), and have the option to remove them if necessary.
- **As a Manager**, I want to view member profiles including their payment history and participation status.
- **As a Manager**, I want to send bulk notifications to all group members about important updates.
- **As a Manager**, I want to export member lists and payment reports for accounting purposes.
#### Automated Lottery/Draw System
- **As a Manager**, I want to initiate a secure and verifiable digital lottery with a single click, which randomly selects a winner from the list of paid, eligible members.
- **As a Manager**, I want to schedule automatic draws on predetermined dates.
- **As a Manager**, I want to view the complete draw history with timestamps and winner details.
- **As a Manager**, I want to generate audit logs for all lottery draws for transparency.
#### Payment Reconciliation
- **As a Manager**, I want the system to automatically mark members as 'Paid' when they complete a transaction, giving me a clear view of who is yet to pay.
- **As a Manager**, I want to send automated payment reminders to defaulters.
- **As a Manager**, I want to view payment analytics including collection rates and trends.
- **As a Manager**, I want to manually override payment status if needed for offline payments.
#### Payout Management
- **As a Manager**, I want to log the date and transaction details of the prize payout to the winner, creating an auditable record for the group.
- **As a Manager**, I want to generate payout receipts and certificates for winners.
- **As a Manager**, I want to track all payout transactions with status updates.
- **As a Manager**, I want to view payout history and generate financial reports.
### 1.3 Member Features (Flutter Web Member Interface)
#### Group Discovery
- **As a Member**, after being added by my manager, I want to see the chit groups I've been assigned to on my web dashboard.
- **As a Member**, I want to view group details including total value, duration, and member count.
- **As a Member**, I want to see the foreman's contact information for direct communication.
- **As a Member**, I want to view my position and status within each group.
#### Payment Dashboard
- **As a Member**, I want a simple web interface that clearly shows my next payment amount, the due date, and my complete payment history.
- **As a Member**, I want to receive payment reminders before due dates.
- **As a Member**, I want to view my payment status across all my chit groups.
- **As a Member**, I want to download payment receipts for tax purposes.
#### Integrated Payments
- **As a Member**, I want to pay my monthly installment easily and securely through UPI (like Google Pay, PhonePe) with a single click from my web browser.
- **As a Member**, I want to set up automatic recurring payments for monthly installments.
- **As a Member**, I want to choose from multiple payment methods including UPI, net banking, and cards.
- **As a Member**, I want to receive instant payment confirmation and receipts.
#### Lottery Transparency
- **As a Member**, I want to view the list of all eligible participants before each draw and receive an instant notification with the lottery result, so I can trust the process is fair.
- **As a Member**, I want to receive real-time notifications when I win a prize.
- **As a Member**, I want to view the complete draw history of my groups.
- **As a Member**, I want to see the provably fair algorithm details for transparency.
#### Transaction Ledger
- **As a Member**, I want a complete, easy-to-read statement of all my contributions and my prize winnings (if any).
- **As a Member**, I want to export my transaction history for personal records.
- **As a Member**, I want to view tax summaries for financial planning.
- **As a Member**, I want to track my net position across all chit groups.
---
## 2. Core Application Workflows
### 2.1 The Monthly Draw Cycle (Unified Flutter Web)
#### Phase 1: Payment Collection (Days 1-25)
1. **Automated Reminders**: Web app sends browser notifications to members on days 1, 15, and 20
2. **Payment Processing**: Members pay via web app using integrated UPI gateway
3. **Payment Verification**: System confirms payments and updates member status
4. **Collection Tracking**: Manager monitors real-time collection progress on web dashboard
#### Phase 2: Eligibility Confirmation (Day 26)
1. **Payment Deadline**: Final payment cutoff at 11:59 PM on day 25
2. **Eligibility List Generation**: System creates final list of eligible members
3. **Transparency Display**: List is visible to all group members on web app and to Manager on dashboard
4. **Audit Log Creation**: Complete audit trail of eligibility determination
#### Phase 3: Lottery Execution (Day 27)
1. **Draw Initiation**: Manager logs into web app and clicks "Conduct Draw" button
2. **Random Selection**: Backend executes provably fair random selection algorithm
3. **Result Verification**: Cryptographic proof of fairness generated
4. **Winner Declaration**: System announces winner to all members
#### Phase 4: Winner Declaration (Day 27)
1. **Real-time Notification**: All members receive instant winner announcement via browser notification
2. **Result Display**: Winner details shown on Manager's web dashboard and member web interfaces
3. **Audit Trail**: Complete draw process logged for transparency
4. **Certificate Generation**: Digital winner certificate created
#### Phase 5: Payout (Days 28-30)
1. **Prize Calculation**: System calculates prize amount (Total - Commission)
2. **Offline Payout**: Manager disburses prize money offline
3. **Transaction Recording**: Manager logs payout details in web app for record-keeping
4. **Receipt Generation**: Digital receipt sent to winner via web interface
### 2.2 Defaulter Handling
#### Late Payment Process
1. **Automatic Exclusion**: Member automatically excluded from draw if payment not received by deadline
2. **Status Update**: Payment status updated to "Unpaid" on web platform
3. **Manager Notification**: Manager receives alert about unpaid members on web dashboard
4. **Offline Follow-up**: Manager follows up with defaulters offline
#### Recovery Process
1. **Payment Recovery**: Member can pay outstanding amount via web app
2. **Reinstatement**: Member reinstated after full payment
3. **Manual Override**: Manager can manually mark payments as received for offline transactions
4. **Future Planning**: System tracks default patterns for future reference
---
## 3. Recommended Technology Stack
### 3.1 Frontend (Unified Flutter Web)
#### Primary Recommendation: Flutter Web
**Justification**:
- **Single Codebase**: Build both Manager and Member interfaces from one Flutter Web codebase
- **Cost Efficiency**: Drastically reduces development time and costs
- **Consistent Experience**: Same business logic and UI components across interfaces
- **Performance**: Excellent performance on modern web browsers
- **Responsive Design**: Automatic adaptation to different screen sizes
- **PWA Capabilities**: Can be installed as a web app on mobile devices
- **Future-Proof**: Easy to add mobile apps later if needed
#### Interface Differentiation Strategy
- **Manager Dashboard**: Desktop-optimized layout with data-rich interface
- **Member Dashboard**: Mobile-responsive design with simplified interface
- **Role-based Routing**: Automatic interface switching based on user role
- **Shared Components**: Common UI components and business logic
### 3.2 Backend
#### Primary Recommendation: Node.js with Express.js
**Justification**:
- **JavaScript/TypeScript**: Unified language across frontend and backend
- **Real-time Features**: Excellent support for WebSockets and real-time updates
- **Payment Integration**: Rich ecosystem for payment gateway integrations
- **Scalability**: Easy to scale from monolith to microservices
- **Development Speed**: Rapid development with extensive npm ecosystem
#### Alternative: Python with FastAPI
**Justification**:
- **Data Processing**: Excellent for analytics and reporting features
- **Machine Learning**: Easy integration with ML libraries for future features
- **Performance**: High performance with async support
- **Documentation**: Auto-generated API documentation
### 3.3 Provably Fair Lottery Algorithm
#### Implementation Strategy
```javascript
class ProvablyFairLottery {
constructor() {
this.serverSeed = this.generateServerSeed();
this.serverSeedHash = this.hashSeed(this.serverSeed);
}
// Before draw: Publish server seed hash
getServerSeedHash() {
return this.serverSeedHash;
}
// During draw: Generate result
generateResult(clientSeed, nonce, eligibleMembers) {
const combined = this.serverSeed + clientSeed + nonce.toString();
const hash = crypto.createHash('sha256').update(combined).digest('hex');
const randomNumber = parseInt(hash.substring(0, 8), 16);
const winnerIndex = randomNumber % eligibleMembers.length;
return {
winnerId: eligibleMembers[winnerIndex].id,
serverSeed: this.serverSeed, // Revealed after draw
serverSeedHash: this.serverSeedHash,
clientSeed,
nonce,
resultHash: hash,
proof: { combined, randomNumber, winnerIndex }
};
}
// Verification: Users can verify fairness
verifyResult(serverSeed, clientSeed, nonce, resultHash, eligibleMembers, winnerId) {
const combined = serverSeed + clientSeed + nonce.toString();
const calculatedHash = crypto.createHash('sha256').update(combined).digest('hex');
if (calculatedHash !== resultHash) return false;
const randomNumber = parseInt(calculatedHash.substring(0, 8), 16);
const winnerIndex = randomNumber % eligibleMembers.length;
return eligibleMembers[winnerIndex].id === winnerId;
}
}
```
### 3.4 Database
#### Primary: PostgreSQL
**Justification**:
- **ACID Compliance**: Critical for financial transactions
- **JSON Support**: Flexible data storage for complex objects
- **Performance**: Excellent indexing and query optimization
- **Reliability**: Enterprise-grade database for financial applications
- **Scalability**: Easy to scale with read replicas and sharding
### 3.5 Real-time Notifications
#### Technology Stack
- **Browser Notifications**: Web Notifications API
- **Web Real-time**: WebSockets (Socket.io)
- **In-app Notifications**: Custom notification center
- **Email Notifications**: Nodemailer or SendGrid
### 3.6 Payment Gateway
#### Primary Recommendation: Razorpay
**Justification**:
- **UPI Support**: Excellent UPI integration for Indian market
- **API Quality**: Comprehensive and well-documented APIs
- **Security**: PCI DSS compliant with robust security features
- **Support**: Excellent customer support and dispute resolution
- **Pricing**: Competitive transaction fees
### 3.7 Cloud & DevOps
#### Primary Recommendation: AWS
**Services**:
- **Compute**: EC2 Auto Scaling Groups or ECS Fargate
- **Database**: RDS PostgreSQL with Multi-AZ deployment
- **Storage**: S3 for file storage and backups
- **CDN**: CloudFront for static assets
- **Monitoring**: CloudWatch for application and infrastructure monitoring
- **CI/CD**: AWS CodePipeline or GitHub Actions
---
## 4. Non-Functional Requirements
### 4.1 Transparency & Fairness
- **Provably Fair Algorithm**: Cryptographic hash chain with verifiable randomness
- **Pre-published Hashes**: Server seed hash published before each draw
- **Public Verification**: Members can verify draw fairness independently
- **Audit Trail**: Complete logging of all lottery draws with cryptographic proofs
### 4.2 Security
- **Data Encryption**: AES-256 encryption for sensitive data
- **API Security**: JWT tokens with refresh mechanism
- **Payment Security**: PCI DSS compliance
- **Password Security**: Secure password hashing (bcrypt)
- **Role-based Access**: Manager vs. Member permissions
### 4.3 Compliance
- **Chit Fund Act, 1982**: Architecture designed for future KYC integration
- **Data Privacy**: GDPR and Indian data protection laws compliance
- **Financial Records**: Complete audit trail for all transactions
- **Tax Compliance**: GST and TDS reporting capabilities
### 4.4 Scalability
- **Monolith First**: Well-structured monolith on AWS/GCP for MVP
- **Microservices Ready**: Architecture designed for future microservices migration
- **Database Scaling**: Read replicas and connection pooling
- **CDN**: Global content delivery for static assets
### 4.5 Usability & UI/UX
- **Manager Web Interface**: Data-rich interface optimized for desktop use
- **Member Web Interface**: Simple, focused interface for payments and results
- **Responsive Design**: Mobile-first approach for member interface
- **Accessibility**: WCAG 2.1 compliance for both interfaces
- **PWA Features**: Installable web app with offline capabilities
---
## 5. High-Level Project Roadmap
### Phase 1: MVP - The Private Management Tool (Months 1-4)
#### Goal
Launch with a few trusted Chit Fund Managers to validate core functionality.
#### Platform
- **Unified Flutter Web App**: Single web application with dual interfaces
- **Manager Dashboard**: Comprehensive web interface for chit fund management
- **Member Dashboard**: Mobile-responsive web interface for member interactions
#### Core Features
- **Manager Account Creation**: Managers create member accounts
- **Group Management**: Create groups, add members, configure settings
- **Payment Collection**: UPI integration for monthly payments
- **Lottery System**: Provably fair draw execution
- **Basic Reporting**: Payment status and draw history
#### Success Criteria
- 5-10 trusted managers using the platform
- 100+ members successfully making payments
- 20+ successful lottery draws completed
- Payment success rate > 95%
### Phase 2: Growth & Compliance (Months 5-8)
#### Feature 1: Self-Onboarding & e-KYC (Priority 1)
- **Public Registration**: Self-service member registration
- **Aadhaar/PAN Verification**: Full KYC integration
- **Document Upload**: Profile photo and identity documents
- **Verification Workflow**: Automated and manual verification processes
#### Feature 2: Automated Defaulter Management
- **Late Payment Penalties**: Automated penalty calculation
- **Escalation Workflows**: Progressive reminder system
- **Payment Plans**: Flexible payment arrangements
- **Recovery Automation**: Automated recovery processes
#### Feature 3: Enhanced Reporting
- **Financial Analytics**: Detailed financial reports for managers
- **Member Analytics**: Payment patterns and behavior analysis
- **Compliance Reports**: Regulatory reporting capabilities
- **Export Functionality**: Data export for accounting systems
### Phase 3: Scale & Ecosystem (Months 9-12)
#### Public Chit Group Listings
- **Marketplace**: Public discovery of chit groups
- **Group Ratings**: Member reviews and ratings
- **Search & Filter**: Advanced group discovery features
- **Trust Scores**: Reputation system for managers
#### Credit Scoring Integration
- **Member Credit Profiles**: Credit history and scoring
- **Risk Assessment**: Automated risk evaluation
- **Lending Integration**: Connect with financial institutions
- **Credit Reports**: Credit score tracking and reporting
#### Advanced Chit Fund Models
- **Auction-based Chits**: Support for traditional auction models
- **Hybrid Models**: Combination of lottery and auction
- **Custom Rules**: Flexible rule configuration
- **Multi-tier Groups**: Complex group structures
---
## 6. Technical Architecture
### 6.1 System Architecture
```
┌─────────────────────────────────────────┐
│ Flutter Web Application │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Manager │ │ Member │ │
│ │ Dashboard │ │ Dashboard │ │
│ │ (Desktop UI) │ │ (Mobile UI) │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────┘
│
│
┌─────────────────┐
│ API Gateway │
│ (Express.js) │
└─────────────────┘
│
┌─────────────────┐
│ PostgreSQL │
│ (Primary DB) │
└─────────────────┘
│
┌─────────────────┐
│ Redis │
│ (Cache/Queue) │
└─────────────────┘
```
### 6.2 Database Schema (Simplified MVP)
#### Users Table
```sql
CREATE TABLE users (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
mobile_number VARCHAR(15) UNIQUE NOT NULL,
full_name VARCHAR(255) NOT NULL,
password_hash VARCHAR(255) NOT NULL,
role ENUM('manager', 'member') NOT NULL,
created_by UUID REFERENCES users(id), -- Manager who created this account
is_active BOOLEAN DEFAULT true,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### Chit Groups Table
```sql
CREATE TABLE chit_groups (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
name VARCHAR(255) NOT NULL,
total_value DECIMAL(15,2) NOT NULL,
monthly_installment DECIMAL(15,2) NOT NULL,
duration_months INTEGER NOT NULL,
max_members INTEGER NOT NULL,
foreman_commission_percentage DECIMAL(5,2) NOT NULL,
draw_date INTEGER NOT NULL, -- Day of month
status ENUM('forming', 'active', 'completed') DEFAULT 'forming',
manager_id UUID REFERENCES users(id),
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```
#### Group Members Table
```sql
CREATE TABLE group_members (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
group_id UUID REFERENCES chit_groups(id),
user_id UUID REFERENCES users(id),
status ENUM('active', 'suspended', 'removed') DEFAULT 'active',
joined_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(group_id, user_id)
);
```
#### Monthly Draws Table
```sql
CREATE TABLE monthly_draws (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
group_id UUID REFERENCES chit_groups(id),
month INTEGER NOT NULL,
year INTEGER NOT NULL,
draw_date TIMESTAMP NOT NULL,
eligible_members JSONB NOT NULL,
winner_id UUID REFERENCES users(id),
prize_amount DECIMAL(15,2),
server_seed VARCHAR(255),
server_seed_hash VARCHAR(255),
client_seed VARCHAR(255),
nonce INTEGER,
result_hash VARCHAR(255),
status ENUM('pending', 'completed') DEFAULT 'pending',
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(group_id, month, year)
);
```
#### Payments Table
```sql
CREATE TABLE payments (
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
group_id UUID REFERENCES chit_groups(id),
user_id UUID REFERENCES users(id),
month INTEGER NOT NULL,
year INTEGER NOT NULL,
amount DECIMAL(15,2) NOT NULL,
payment_method ENUM('upi', 'offline') NOT NULL,
transaction_id VARCHAR(255),
status ENUM('pending', 'success', 'failed') DEFAULT 'pending',
paid_at TIMESTAMP,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
UNIQUE(group_id, user_id, month, year)
);
```
---
## 7. Development Timeline
### Month 1: Foundation
- **Week 1-2**: Project setup, architecture design, development environment
- **Week 3-4**: Basic Flutter Web app structure, authentication system
### Month 2: Core Features
- **Week 5-6**: Group management, member management
- **Week 7-8**: Payment integration, basic dashboard
### Month 3: Lottery System
- **Week 9-10**: Provably fair algorithm implementation
- **Week 11-12**: Draw execution, result broadcasting
### Month 4: Testing & Launch
- **Week 13-14**: End-to-end testing, bug fixes
- **Week 15-16**: Production deployment, MVP launch
---
## 8. Success Metrics
### Technical Metrics
- **App Performance**: < 3 seconds load time
- **API Response Time**: < 500ms p95
- **System Uptime**: > 99.9%
- **Payment Success Rate**: > 99%
### Business Metrics
- **Manager Adoption**: 10+ managers in first 3 months
- **Member Engagement**: 500+ active members
- **Payment Volume**: ₹50 Lakhs in first 6 months
- **Draw Success Rate**: 100% successful draws
### User Experience Metrics
- **Manager Satisfaction**: > 4.5/5 rating
- **Member Retention**: > 80% after 30 days
- **Payment Completion**: > 95% on-time payments
- **Support Tickets**: < 5% of users
---
## 9. Risk Assessment & Mitigation
### Technical Risks
- **Risk**: Lottery algorithm compromise
- **Mitigation**: Regular security audits, open-source verification
### Business Risks
- **Risk**: Low manager adoption
- **Mitigation**: Focus on trusted managers, provide excellent support
### Compliance Risks
- **Risk**: Regulatory changes affecting chit funds
- **Mitigation**: Legal consultation, flexible architecture
---
## 10. Conclusion
The revised LuckyChit development plan focuses on a practical MVP approach with manager-controlled onboarding and a unified Flutter Web platform. This approach reduces complexity while ensuring core functionality validation before scaling.
**Key Advantages of This Approach**:
1. **Reduced Complexity**: No public KYC in MVP phase
2. **Trusted Network**: Start with known, trusted managers
3. **Unified Technology**: Single Flutter Web codebase for both interfaces
4. **Proven Fairness**: Cryptographic lottery algorithm builds trust
5. **Scalable Architecture**: Easy to add features in future phases
6. **Cost Efficiency**: Single codebase reduces development and maintenance costs
7. **PWA Capabilities**: Can be installed on mobile devices as a web app
**Next Steps**:
1. Finalize technology stack and architecture
2. Begin Phase 1 development with MVP features
3. Establish partnerships with payment gateways
4. Set up development and testing environments
5. Start with 2-3 trusted managers for initial validation
Reference in New Issue View Git Blame Copy Permalink