# Base Infrastructure

This directory contains the core backend utilities for the task-based earning platform.

## Structure

```
app/lib/
├── types.ts           # TypeScript type definitions
├── auth.ts            # Authentication utilities
├── points.ts          # Points management
├── badges.ts          # Badge logic
└── db/
    └── store.ts       # In-memory data store
```

## Types (types.ts)

All TypeScript interfaces and enums:
- **User**: User account data
- **Transaction**: Points transactions (earned/spent)
- **Task**: Task definitions (checkin, ad, survey, quiz, etc.)
- **UserTask**: Completed tasks by users
- **Badge**: Achievement definitions
- **UserBadge**: Badges earned by users
- **Quiz**: Quiz questions and answers
- **Referral**: User referral tracking
- **API Response Types**: Structured responses for all endpoints

## Database Store (db/store.ts)

In-memory storage with CRUD operations:
- User management (create, find, update)
- Transaction tracking
- Task management
- Badge operations
- Quiz handling
- Referral tracking

### Seed Data

Pre-populated with:
- **6 Tasks**: Daily checkin, watch ad, survey, quiz, video, reading
- **6 Badges**: First steps, point collector, dedicated, week warrior, referral master, point millionaire
- **1 Quiz**: Sample quiz for quiz task

## Authentication (auth.ts)

User authentication and security:
- `hashPassword()`: Hash passwords (base64 for MVP)
- `verifyPassword()`: Verify password against hash
- `generateToken()`: Create JWT-like tokens
- `verifyToken()`: Validate and decode tokens
- `getCurrentUser()`: Extract user from request
- `requireAuth()`: Middleware for protected routes
- `isValidEmail()`: Email validation
- `isValidPassword()`: Password strength validation
- `sanitizeUser()`: Remove sensitive data from user object

## Points Management (points.ts)

Points and transactions:
- `addPoints()`: Award points to user
- `deductPoints()`: Spend points (with balance check)
- `getBalance()`: Get current balance
- `getTransactions()`: Get transaction history
- `getTransactionStats()`: Earnings/spending statistics
- `getPointsBreakdown()`: Points by source
- `awardTaskPoints()`: Task completion rewards
- `awardReferralBonus()`: Referral bonuses
- `awardStreakBonus()`: Daily streak bonuses

## Badge System (badges.ts)

Achievement tracking:
- `checkAndAwardBadges()`: Auto-award eligible badges
- `getUserBadgesWithDetails()`: Get earned badges
- `getAvailableBadges()`: Get unearned badges
- `getBadgeProgress()`: Progress towards specific badge
- `getAllBadgeProgress()`: Progress for all badges
- `getBadgeStats()`: Badge statistics

### Badge Requirements

- **POINTS_TOTAL**: Total points earned
- **TASKS_COMPLETED**: Number of tasks completed
- **STREAK_DAYS**: Consecutive daily activity
- **REFERRALS**: Number of successful referrals

## Usage Example

```typescript
import { createUser, findUserByEmail } from './db/store';
import { hashPassword, generateToken } from './auth';
import { addPoints, getBalance } from './points';
import { checkAndAwardBadges } from './badges';

// Register user
const passwordHash = await hashPassword('SecurePass123');
const user = createUser('user@example.com', passwordHash, 'John Doe');

// Generate auth token
const token = generateToken(user.id);

// Award points for task completion
addPoints(user.id, 10, 'task:daily_checkin');

// Check balance
const balance = getBalance(user.id);

// Check and award badges
const newBadges = checkAndAwardBadges(user.id);
```

## Next Steps

This base infrastructure is ready for API endpoint integration:
1. Create `/api/auth/*` routes (register, login, logout)
2. Create `/api/tasks/*` routes (list, complete)
3. Create `/api/points/*` routes (balance, transactions)
4. Create `/api/badges/*` routes (earned, available, progress)
5. Create `/api/leaderboard` route