# 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
