521 lines
15 KiB
Markdown
521 lines
15 KiB
Markdown
# LuckyChit - Technical Architecture Document
|
|
|
|
## System Architecture Overview
|
|
|
|
### High-Level Architecture
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Mobile App │ │ Web Dashboard │ │ Admin Panel │
|
|
│ (Flutter) │ │ (React) │ │ (React) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
└───────────────────────┼───────────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ API Gateway │
|
|
│ (Kong/Nginx) │
|
|
└─────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ Load Balancer │
|
|
│ (AWS ALB) │
|
|
└─────────────────┘
|
|
│
|
|
┌───────────────────────┼───────────────────────┐
|
|
│ │ │
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ Auth Service │ │ Payment Service│ │ Lottery Service│
|
|
│ (Node.js) │ │ (Node.js) │ │ (Node.js) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│ │ │
|
|
└───────────────────────┼───────────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ PostgreSQL │
|
|
│ (Primary DB) │
|
|
└─────────────────┘
|
|
│
|
|
┌─────────────────┐
|
|
│ Redis │
|
|
│ (Cache/Queue) │
|
|
└─────────────────┘
|
|
```
|
|
|
|
## Microservices Architecture
|
|
|
|
### 1. Authentication Service
|
|
**Purpose**: Handle user authentication, KYC verification, and session management
|
|
|
|
**Key Components**:
|
|
- JWT token generation and validation
|
|
- OTP-based authentication
|
|
- Aadhaar/PAN verification integration
|
|
- Session management with Redis
|
|
- Role-based access control (RBAC)
|
|
|
|
**API Endpoints**:
|
|
```
|
|
POST /auth/register
|
|
POST /auth/login
|
|
POST /auth/verify-otp
|
|
POST /auth/kyc/verify-aadhaar
|
|
POST /auth/kyc/verify-pan
|
|
POST /auth/refresh-token
|
|
DELETE /auth/logout
|
|
```
|
|
|
|
### 2. Payment Service
|
|
**Purpose**: Handle all payment-related operations and integrations
|
|
|
|
**Key Components**:
|
|
- Razorpay integration
|
|
- UPI payment processing
|
|
- Payment status tracking
|
|
- Refund management
|
|
- Payment analytics
|
|
|
|
**API Endpoints**:
|
|
```
|
|
POST /payments/create-order
|
|
POST /payments/process-upi
|
|
GET /payments/status/:id
|
|
POST /payments/refund
|
|
GET /payments/history
|
|
POST /payments/webhook
|
|
```
|
|
|
|
### 3. Lottery Service
|
|
**Purpose**: Handle lottery draw execution and result management
|
|
|
|
**Key Components**:
|
|
- Provably fair algorithm implementation
|
|
- Draw scheduling and execution
|
|
- Result verification and broadcasting
|
|
- Audit trail management
|
|
- Winner notification system
|
|
|
|
**API Endpoints**:
|
|
```
|
|
POST /lottery/initiate-draw
|
|
GET /lottery/eligible-members
|
|
POST /lottery/execute-draw
|
|
GET /lottery/results/:drawId
|
|
GET /lottery/verify-result/:drawId
|
|
GET /lottery/history
|
|
```
|
|
|
|
### 4. Chit Group Service
|
|
**Purpose**: Manage chit group operations and member management
|
|
|
|
**Key Components**:
|
|
- Group creation and configuration
|
|
- Member invitation and approval
|
|
- Group status tracking
|
|
- Commission calculation
|
|
- Group analytics
|
|
|
|
**API Endpoints**:
|
|
```
|
|
POST /groups/create
|
|
GET /groups/:id
|
|
PUT /groups/:id
|
|
POST /groups/:id/invite
|
|
POST /groups/:id/join
|
|
GET /groups/:id/members
|
|
PUT /groups/:id/members/:memberId
|
|
```
|
|
|
|
### 5. Notification Service
|
|
**Purpose**: Handle all notification and communication
|
|
|
|
**Key Components**:
|
|
- Push notifications (FCM)
|
|
- SMS notifications
|
|
- Email notifications
|
|
- In-app notifications
|
|
- Notification preferences
|
|
|
|
**API Endpoints**:
|
|
```
|
|
POST /notifications/send
|
|
POST /notifications/bulk
|
|
GET /notifications/history
|
|
PUT /notifications/preferences
|
|
POST /notifications/subscribe
|
|
```
|
|
|
|
## Database Schema Design
|
|
|
|
### Core Tables
|
|
|
|
#### Users Table
|
|
```sql
|
|
CREATE TABLE users (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
mobile_number VARCHAR(15) UNIQUE NOT NULL,
|
|
email VARCHAR(255) UNIQUE,
|
|
full_name VARCHAR(255) NOT NULL,
|
|
profile_photo_url TEXT,
|
|
aadhaar_number VARCHAR(12),
|
|
pan_number VARCHAR(10),
|
|
kyc_status ENUM('pending', 'verified', 'rejected') DEFAULT 'pending',
|
|
bank_account_details JSONB,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
is_active BOOLEAN DEFAULT true
|
|
);
|
|
```
|
|
|
|
#### 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', 'cancelled') DEFAULT 'forming',
|
|
foreman_id UUID REFERENCES users(id),
|
|
invite_code VARCHAR(10) UNIQUE,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
updated_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('pending', 'active', 'suspended', 'removed') DEFAULT 'pending',
|
|
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),
|
|
client_seed VARCHAR(255),
|
|
nonce INTEGER,
|
|
result_hash VARCHAR(255),
|
|
status ENUM('pending', 'completed', 'cancelled') 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', 'net_banking', 'card') NOT NULL,
|
|
transaction_id VARCHAR(255),
|
|
status ENUM('pending', 'success', 'failed', 'refunded') DEFAULT 'pending',
|
|
paid_at TIMESTAMP,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
UNIQUE(group_id, user_id, month, year)
|
|
);
|
|
```
|
|
|
|
#### Payouts Table
|
|
```sql
|
|
CREATE TABLE payouts (
|
|
id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
|
|
draw_id UUID REFERENCES monthly_draws(id),
|
|
winner_id UUID REFERENCES users(id),
|
|
amount DECIMAL(15,2) NOT NULL,
|
|
bank_transaction_id VARCHAR(255),
|
|
status ENUM('pending', 'completed', 'failed') DEFAULT 'pending',
|
|
paid_at TIMESTAMP,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
|
|
);
|
|
```
|
|
|
|
## Provably Fair Lottery Algorithm
|
|
|
|
### Implementation Details
|
|
|
|
```javascript
|
|
const crypto = require('crypto');
|
|
|
|
class ProvablyFairLottery {
|
|
constructor() {
|
|
this.serverSeed = this.generateServerSeed();
|
|
this.serverSeedHash = this.hashSeed(this.serverSeed);
|
|
}
|
|
|
|
generateServerSeed() {
|
|
return crypto.randomBytes(32).toString('hex');
|
|
}
|
|
|
|
hashSeed(seed) {
|
|
return crypto.createHash('sha256').update(seed).digest('hex');
|
|
}
|
|
|
|
generateResult(clientSeed, nonce, eligibleMembers) {
|
|
const combined = this.serverSeed + clientSeed + nonce.toString();
|
|
const hash = crypto.createHash('sha256').update(combined).digest('hex');
|
|
|
|
// Use first 8 characters of hash to generate random number
|
|
const randomNumber = parseInt(hash.substring(0, 8), 16);
|
|
|
|
// Map to eligible member index
|
|
const winnerIndex = randomNumber % eligibleMembers.length;
|
|
|
|
return {
|
|
winnerId: eligibleMembers[winnerIndex].id,
|
|
serverSeed: this.serverSeed,
|
|
serverSeedHash: this.serverSeedHash,
|
|
clientSeed,
|
|
nonce,
|
|
resultHash: hash,
|
|
proof: {
|
|
combined,
|
|
randomNumber,
|
|
winnerIndex
|
|
}
|
|
};
|
|
}
|
|
|
|
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;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Security Implementation
|
|
|
|
### 1. API Security
|
|
- **Rate Limiting**: Implement rate limiting using Redis
|
|
- **Input Validation**: Joi schema validation for all inputs
|
|
- **SQL Injection Prevention**: Parameterized queries only
|
|
- **CORS Configuration**: Strict CORS policies
|
|
- **API Versioning**: Version all APIs for backward compatibility
|
|
|
|
### 2. Authentication & Authorization
|
|
```javascript
|
|
// JWT Token Structure
|
|
const tokenPayload = {
|
|
userId: user.id,
|
|
role: user.role,
|
|
permissions: user.permissions,
|
|
iat: Math.floor(Date.now() / 1000),
|
|
exp: Math.floor(Date.now() / 1000) + (24 * 60 * 60) // 24 hours
|
|
};
|
|
|
|
// Role-based Access Control
|
|
const permissions = {
|
|
FOREMAN: ['create_group', 'manage_members', 'initiate_draw', 'manage_payouts'],
|
|
MEMBER: ['join_group', 'make_payment', 'view_results', 'view_ledger'],
|
|
ADMIN: ['manage_users', 'view_analytics', 'system_config']
|
|
};
|
|
```
|
|
|
|
### 3. Data Encryption
|
|
```javascript
|
|
// AES-256 Encryption for sensitive data
|
|
const crypto = require('crypto');
|
|
|
|
class DataEncryption {
|
|
constructor(secretKey) {
|
|
this.algorithm = 'aes-256-gcm';
|
|
this.secretKey = Buffer.from(secretKey, 'hex');
|
|
}
|
|
|
|
encrypt(text) {
|
|
const iv = crypto.randomBytes(16);
|
|
const cipher = crypto.createCipher(this.algorithm, this.secretKey);
|
|
cipher.setAAD(Buffer.from('lucky-chit', 'utf8'));
|
|
|
|
let encrypted = cipher.update(text, 'utf8', 'hex');
|
|
encrypted += cipher.final('hex');
|
|
|
|
const authTag = cipher.getAuthTag();
|
|
|
|
return {
|
|
encrypted,
|
|
iv: iv.toString('hex'),
|
|
authTag: authTag.toString('hex')
|
|
};
|
|
}
|
|
|
|
decrypt(encryptedData) {
|
|
const decipher = crypto.createDecipher(this.algorithm, this.secretKey);
|
|
decipher.setAAD(Buffer.from('lucky-chit', 'utf8'));
|
|
decipher.setAuthTag(Buffer.from(encryptedData.authTag, 'hex'));
|
|
|
|
let decrypted = decipher.update(encryptedData.encrypted, 'hex', 'utf8');
|
|
decrypted += decipher.final('utf8');
|
|
|
|
return decrypted;
|
|
}
|
|
}
|
|
```
|
|
|
|
## Deployment Architecture
|
|
|
|
### AWS Infrastructure
|
|
|
|
#### Compute Layer
|
|
- **EC2 Auto Scaling Groups**: For application servers
|
|
- **ECS Fargate**: For containerized services
|
|
- **Lambda Functions**: For serverless operations
|
|
|
|
#### Data Layer
|
|
- **RDS PostgreSQL**: Primary database with Multi-AZ deployment
|
|
- **ElastiCache Redis**: Caching and session storage
|
|
- **S3**: File storage and backups
|
|
|
|
#### Network Layer
|
|
- **VPC**: Private subnets for application servers
|
|
- **ALB**: Application Load Balancer for traffic distribution
|
|
- **CloudFront**: CDN for static assets
|
|
- **Route 53**: DNS management
|
|
|
|
#### Monitoring & Logging
|
|
- **CloudWatch**: Application and infrastructure monitoring
|
|
- **CloudTrail**: API call logging
|
|
- **X-Ray**: Distributed tracing
|
|
- **SNS**: Alert notifications
|
|
|
|
### CI/CD Pipeline
|
|
|
|
```yaml
|
|
# GitHub Actions Workflow
|
|
name: Deploy LuckyChit
|
|
|
|
on:
|
|
push:
|
|
branches: [main, develop]
|
|
|
|
jobs:
|
|
test:
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- uses: actions/checkout@v2
|
|
- name: Run Tests
|
|
run: npm test
|
|
|
|
build:
|
|
needs: test
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Build Docker Images
|
|
run: docker build -t luckychit:${{ github.sha }} .
|
|
|
|
deploy:
|
|
needs: build
|
|
runs-on: ubuntu-latest
|
|
steps:
|
|
- name: Deploy to AWS
|
|
run: |
|
|
aws ecs update-service --cluster luckychit --service api --force-new-deployment
|
|
```
|
|
|
|
## Performance Optimization
|
|
|
|
### 1. Database Optimization
|
|
- **Indexing Strategy**: Composite indexes for common queries
|
|
- **Query Optimization**: Use EXPLAIN ANALYZE for slow queries
|
|
- **Connection Pooling**: PgBouncer for connection management
|
|
- **Read Replicas**: For read-heavy operations
|
|
|
|
### 2. Caching Strategy
|
|
```javascript
|
|
// Multi-layer caching
|
|
const cacheLayers = {
|
|
L1: 'In-memory (Node.js)', // Session data, user info
|
|
L2: 'Redis', // API responses, payment status
|
|
L3: 'CDN', // Static assets, images
|
|
L4: 'Database' // Persistent data
|
|
};
|
|
|
|
// Cache invalidation strategy
|
|
const cacheInvalidation = {
|
|
'user:profile': 'TTL: 1 hour',
|
|
'group:members': 'TTL: 30 minutes',
|
|
'payment:status': 'TTL: 5 minutes',
|
|
'lottery:results': 'TTL: 24 hours'
|
|
};
|
|
```
|
|
|
|
### 3. API Performance
|
|
- **Response Compression**: Gzip compression for all responses
|
|
- **Pagination**: Implement cursor-based pagination
|
|
- **GraphQL**: For complex data fetching
|
|
- **CDN**: For static assets and API responses
|
|
|
|
## Monitoring & Alerting
|
|
|
|
### Key Metrics
|
|
```javascript
|
|
const metrics = {
|
|
// Application Metrics
|
|
'api.response_time': 'p95 < 500ms',
|
|
'api.error_rate': '< 1%',
|
|
'payment.success_rate': '> 99%',
|
|
'lottery.draw_time': '< 30 seconds',
|
|
|
|
// Business Metrics
|
|
'users.active_daily': 'Track growth',
|
|
'groups.created_monthly': 'Track adoption',
|
|
'payments.volume_daily': 'Track revenue',
|
|
|
|
// Infrastructure Metrics
|
|
'cpu.utilization': '< 70%',
|
|
'memory.utilization': '< 80%',
|
|
'disk.usage': '< 85%',
|
|
'database.connections': '< 80% of max'
|
|
};
|
|
```
|
|
|
|
### Alerting Rules
|
|
```yaml
|
|
alerts:
|
|
- name: "High Error Rate"
|
|
condition: "api.error_rate > 5%"
|
|
duration: "5 minutes"
|
|
action: "slack-notification"
|
|
|
|
- name: "Payment Gateway Down"
|
|
condition: "payment.success_rate < 90%"
|
|
duration: "2 minutes"
|
|
action: "pager-duty"
|
|
|
|
- name: "Database High Load"
|
|
condition: "database.connections > 90%"
|
|
duration: "10 minutes"
|
|
action: "email-notification"
|
|
```
|
|
|
|
This technical architecture provides a robust, scalable, and secure foundation for the LuckyChit application, ensuring it can handle the demands of a fintech application while maintaining transparency and trust.
|