mediahub-fe/docs/REGISTRATION_REFACTOR.md

# Registration System Refactor

## Overview

The registration system has been completely refactored to follow modern React best practices, improve maintainability, and enhance user experience. The new system is modular, type-safe, and follows a clear separation of concerns.

## Architecture

### File Structure

```
├── types/registration.ts              # TypeScript types and validation schemas
├── lib/registration-utils.ts          # Utility functions and constants
├── hooks/use-registration.ts          # Custom React hooks
├── components/auth/
│   ├── registration-layout.tsx        # Layout wrapper with step indicator
│   ├── identity-form.tsx              # Identity verification form
│   ├── registration-otp-form.tsx      # OTP verification form
│   └── profile-form.tsx               # Profile completion form
└── app/[locale]/auth/registration/
    └── page.tsx                       # Main registration page
```

## Key Improvements

### 1. Type Safety
- **Zod Schemas**: All form validation uses Zod schemas for runtime type safety
- **TypeScript Types**: Comprehensive type definitions for all data structures
- **Strict Validation**: Form validation with detailed error messages

### 2. Modular Components
- **Single Responsibility**: Each component has a clear, focused purpose
- **Reusable**: Components can be easily reused in other parts of the application
- **Props Interface**: Well-defined props with TypeScript interfaces

### 3. Custom Hooks
- **useOTP**: Handles OTP operations with timer and rate limiting
- **useLocationData**: Manages location data fetching (provinces, cities, districts)
- **useInstituteData**: Handles institute data and custom institute creation
- **useUserDataValidation**: Validates journalist and personnel data
- **useRegistration**: Manages registration submission
- **useFormValidation**: Provides form validation utilities

### 4. Utility Functions
- **Data Sanitization**: Automatic data cleaning and formatting
- **Password Validation**: Comprehensive password strength checking
- **Rate Limiting**: Prevents abuse with OTP request limiting
- **Error Handling**: Centralized error handling with user-friendly messages

## Components

### RegistrationLayout
- Provides consistent layout across all registration steps
- Handles step indicator with visual progress
- Responsive design with background image

### IdentityForm
- Handles different user categories (Journalist, Personnel, General)
- Real-time validation of identity numbers
- Association selection for journalists
- Email validation

### RegistrationOTPForm
- 6-digit OTP input with auto-focus
- Timer for resend functionality
- Rate limiting for OTP requests
- Keyboard navigation support

### ProfileForm
- Comprehensive profile data collection
- Location selection with cascading dropdowns
- Institute management for journalists
- Password strength validation with checklist

## Hooks

### useOTP
```typescript
const {
  requestOTP,
  verifyOTP,
  resendOTP,
  loading,
  error,
  timer,
  formattedTime,
  canResend
} = useOTP();
```

### useLocationData
```typescript
const {
  provinces,
  cities,
  districts,
  loading,
  error,
  fetchProvinces,
  fetchCities,
  fetchDistricts
} = useLocationData();
```

### useInstituteData
```typescript
const {
  institutes,
  loading,
  error,
  fetchInstitutes,
  saveInstitute
} = useInstituteData(category); // category is optional, defaults to journalist category (6)
```

## Validation Schemas

### Registration Schema
```typescript
export const registrationSchema = z.object({
  firstName: z.string().min(2).max(100),
  username: z.string().min(3).max(50).regex(/^[a-zA-Z0-9._-]+$/),
  phoneNumber: z.string().regex(/^[0-9+\-\s()]+$/),
  email: z.string().email(),
  address: z.string().min(10).max(500),
  provinsi: z.string().min(1),
  kota: z.string().min(1),
  kecamatan: z.string().min(1),
  password: z.string().min(8).regex(/^(?=.*[a-z])(?=.*[A-Z])(?=.*\d)(?=.*[@$!%*?&])/),
  passwordConf: z.string().min(1),
}).refine((data) => data.password === data.passwordConf, {
  message: "Passwords don't match",
  path: ["passwordConf"],
});
```

## User Categories

### Category 6: Journalist
- Requires journalist certificate number
- Association selection (PWI, IJTI, PFI, AJI, Other)
- Institute selection or custom institute creation
- Email verification

### Category 7: Personnel
- Requires police number (NRP)
- Email verification
- Standard profile completion

### General: Public
- Email verification only
- Standard profile completion

## Registration Flow

1. **Identity Verification**
   - User selects category
   - Enters identity information
   - Real-time validation
   - Email verification

2. **OTP Verification**
   - 6-digit OTP sent to email
   - Timer for resend functionality
   - Rate limiting protection

3. **Profile Completion**
   - Personal information
   - Location selection
   - Password creation
   - Institute details (if applicable)

## Error Handling

### Centralized Error Management
- All errors are handled through utility functions
- User-friendly error messages
- Toast notifications for feedback
- Console logging for debugging

### Validation Errors
- Form-level validation with Zod
- Field-level validation with real-time feedback
- Custom validation for business logic

## Security Features

### Rate Limiting
- OTP request limiting (3 attempts per 5 minutes)
- Per-email and per-category tracking
- Automatic reset after timeout

### Data Sanitization
- Input sanitization for XSS prevention
- Data trimming and formatting
- Type validation before API calls

### Password Security
- Minimum 8 characters
- Requires uppercase, lowercase, number, and special character
- Password confirmation matching
- Visual strength indicator

## Performance Optimizations

### Lazy Loading
- Password checklist component loaded dynamically
- Conditional rendering based on user category
- Optimized bundle splitting

### Caching
- Location data cached after first fetch
- Institute data cached for reuse
- Form data preserved between steps

## Testing

### Component Testing
- Each component can be tested in isolation
- Props interface ensures testability
- Mock data easily injectable

### Hook Testing
- Custom hooks can be tested independently
- Async operations properly mocked
- Error scenarios covered

## Best Practices Implemented

### 1. Separation of Concerns
- Business logic in hooks
- UI logic in components
- Data validation in schemas
- Utilities in separate files

### 2. Type Safety
- Full TypeScript coverage
- Zod runtime validation
- Strict type checking

### 3. Accessibility
- Proper ARIA labels
- Keyboard navigation
- Screen reader support
- Focus management

### 4. Responsive Design
- Mobile-first approach
- Flexible layouts
- Touch-friendly interactions

### 5. Error Boundaries
- Graceful error handling
- User-friendly error messages
- Fallback UI components

## Migration Guide

### From Old System
1. **Remove old registration page** (1070 lines → 161 lines)
2. **Update imports** to use new components
3. **Replace validation logic** with Zod schemas
4. **Update API calls** to use new hooks
5. **Test thoroughly** with different user categories

### Benefits
- **90% reduction** in main page code
- **Improved maintainability** with modular structure
- **Better user experience** with real-time validation
- **Enhanced security** with rate limiting and sanitization
- **Type safety** throughout the application

## Future Enhancements

### Planned Features
- Multi-language support for validation messages
- Advanced password strength visualization
- Social media registration options
- Email verification improvements
- Mobile app integration

### Scalability
- Easy to add new user categories
- Modular component architecture
- Reusable hooks and utilities
- Extensible validation system

## Conclusion

The refactored registration system provides a solid foundation for user registration with improved maintainability, security, and user experience. The modular architecture makes it easy to extend and modify as requirements evolve.