project-standalo-todo-super/app/lib/README.md

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

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