Skip to content

Latest commit

 

History

History
246 lines (188 loc) · 5.37 KB

IMPLEMENTATION_PLAN.md

File metadata and controls

246 lines (188 loc) · 5.37 KB

Email Validator - Implementation Plan

Overview

Production-ready Email Validator web application with Next.js 14, TypeScript, and Tailwind CSS.

Phase 1: Project Setup

1.1 Initialize Next.js Project

npx create-next-app@latest . --typescript --tailwind --eslint --app --src-dir --no-git

1.2 Install Dependencies

npm install zustand zod react-hook-form @hookform/resolvers framer-motion lucide-react
npx shadcn@latest init -d
npx shadcn@latest add button input card tabs progress badge toast skeleton switch label textarea

1.3 Project Structure

src/
├── app/                    # Next.js App Router pages
├── components/             # React components
├── lib/                    # Utilities and validators
├── hooks/                  # Custom React hooks
├── stores/                 # Zustand stores
└── types/                  # TypeScript types

Phase 2: Data Files

2.1 Disposable Domains (500+ entries)

  • File: src/lib/data/disposable-domains.ts
  • Contains list of temporary/throwaway email domains
  • Used to detect disposable emails

2.2 Free Providers

  • File: src/lib/data/free-providers.ts
  • Contains Gmail, Yahoo, Outlook, etc.
  • Used to identify free email providers

2.3 Role-Based Prefixes

  • File: src/lib/data/role-emails.ts
  • Contains admin, support, info, etc.
  • Used to detect role-based emails

2.4 Common Typos

  • File: src/lib/data/common-typos.ts
  • Maps typos to correct domains
  • gmial.com → gmail.com

Phase 3: Core Validation Logic

3.1 Syntax Validator (src/lib/validators/syntax.ts)

  • RFC 5322 compliant regex
  • Check email format
  • Validate local part and domain

3.2 Domain Validator (src/lib/validators/domain.ts)

  • Check domain exists
  • DNS lookup for domain

3.3 MX Validator (src/lib/validators/mx.ts)

  • MX record lookup
  • Return mail server records

3.4 Disposable Detector (src/lib/validators/disposable.ts)

  • Check against disposable domains list
  • Return isDisposable status

3.5 Role-Based Detector (src/lib/validators/role-based.ts)

  • Check email prefix against role list
  • Return role type if detected

3.6 Typo Suggester (src/lib/validators/typo.ts)

  • Check domain against common typos
  • Suggest correction if found

3.7 Free Provider Detector (src/lib/validators/free-provider.ts)

  • Check if domain is free provider
  • Return provider name

3.8 Main Validator (src/lib/validators/index.ts)

  • Combine all validators
  • Calculate score (0-100)
  • Determine deliverability and risk

Phase 4: TypeScript Types

4.1 ValidationResult Interface

interface ValidationResult {
  email: string;
  isValid: boolean;
  score: number;
  checks: ValidationChecks;
  deliverability: DeliverabilityStatus;
  risk: RiskLevel;
  timestamp: string;
}

Phase 5: UI Components

5.1 Layout Components

  • Header with navigation
  • Footer with links
  • Theme toggle (dark/light)

5.2 Email Components

  • EmailValidator (main input)
  • ValidationResult (detailed display)
  • BulkValidator (multi-email)
  • ValidationHistory (localStorage)
  • ScoreIndicator (circular gauge)

Phase 6: Pages

6.1 Home Page (/)

  • Single email validation
  • Real-time validation
  • Detailed results display

6.2 Bulk Page (/bulk)

  • CSV/TXT upload
  • Multi-email paste
  • Progress tracking
  • Export results

6.3 API Docs Page (/api-docs)

  • API endpoint documentation
  • Request/response examples
  • Rate limit info

6.4 History Page (/history)

  • Recent validations
  • Clear history option
  • Re-validate option

Phase 7: API Routes

7.1 Single Validation (POST /api/validate)

  • Accept email in body
  • Return ValidationResult
  • Rate limited

7.2 Bulk Validation (POST /api/validate-bulk)

  • Accept email array
  • Return ValidationResult array
  • Rate limited

7.3 Health Check (GET /api/health)

  • Return API status
  • Version info

Phase 8: Hooks & Stores

8.1 Custom Hooks

  • useEmailValidator
  • useDebounce
  • useLocalStorage

8.2 Zustand Stores

  • validation-store (current validation)
  • history-store (validation history)

Phase 9: Testing & Polish

9.1 Build Verification

  • npm run build must pass
  • No TypeScript errors
  • No console errors

9.2 Responsive Design

  • Mobile-first approach
  • Test all breakpoints

9.3 Accessibility

  • ARIA labels
  • Keyboard navigation
  • Color contrast

How to Use (After Implementation)

Single Email Validation

  1. Navigate to home page
  2. Enter email in input field
  3. View real-time validation results
  4. See detailed breakdown of checks
  5. Copy results or view score

Bulk Validation

  1. Navigate to /bulk
  2. Upload CSV/TXT or paste emails
  3. Click "Validate All"
  4. Monitor progress
  5. Export results as CSV/JSON

API Usage

# Single validation
curl -X POST https://your-domain/api/validate \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'

# Bulk validation
curl -X POST https://your-domain/api/validate-bulk \
  -H "Content-Type: application/json" \
  -d '{"emails": ["test1@example.com", "test2@example.com"]}'

Completion Checklist

  • Project setup complete
  • All data files created
  • Core validators working
  • UI components built
  • All pages functional
  • API routes working
  • Dark/light mode working
  • Mobile responsive
  • Build passes
  • Pushed to GitHub