SEO_iamge_renamer_starting_point/packages/frontend/README.md

# SEO Image Renamer Frontend

A modern Next.js frontend application for the SEO Image Renamer platform with complete backend integration.

## Features

### 🚀 Core Functionality
- **Complete API Integration**: Full connection to backend APIs with authentication, file upload, and real-time updates
- **Google OAuth Authentication**: Seamless sign-in flow with JWT token management
- **File Upload System**: Drag & drop interface with validation and progress tracking
- **Real-time Updates**: WebSocket integration for live batch processing updates
- **Stripe Payments**: Complete billing and subscription management

### 🎨 User Experience
- **Responsive Design**: Mobile-first approach with Tailwind CSS
- **Dark Mode Support**: Automatic theme detection and manual toggle
- **Error Handling**: Comprehensive error boundaries and user feedback
- **Loading States**: Proper loading indicators and skeleton screens
- **Toast Notifications**: User-friendly success/error messages

### 🔧 Technical Stack
- **Next.js 14**: App Router with TypeScript
- **React 18**: Modern React with hooks and context
- **Tailwind CSS**: Utility-first styling with custom design system
- **Socket.IO**: Real-time WebSocket communication
- **Axios**: HTTP client with interceptors and error handling
- **Stripe.js**: Payment processing integration

## Getting Started

### Prerequisites
- Node.js 18+ and npm 8+
- Backend API running on localhost:3001
- Google OAuth credentials
- Stripe test account (for payments)

### Installation

1. **Install dependencies**:
   ```bash
   npm install
   ```

2. **Set up environment variables**:
   ```bash
   cp .env.example .env.local
   ```
   
   Update `.env.local` with your actual values:
   - `NEXT_PUBLIC_GOOGLE_CLIENT_ID`: Your Google OAuth client ID
   - `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`: Your Stripe publishable key
   - `NEXT_PUBLIC_API_URL`: Backend API URL (default: http://localhost:3001)

3. **Start development server**:
   ```bash
   npm run dev
   ```

4. **Open in browser**:
   Navigate to [http://localhost:3000](http://localhost:3000)

### Available Scripts

- `npm run dev` - Start development server
- `npm run build` - Build for production
- `npm run start` - Start production server
- `npm run lint` - Run ESLint
- `npm run type-check` - Run TypeScript compiler check
- `npm test` - Run Jest tests
- `npm run storybook` - Start Storybook development server

## Project Structure

```
src/
├── app/                    # Next.js 14 App Router
│   ├── auth/              # Authentication pages
│   ├── billing/           # Billing and subscription pages
│   ├── admin/             # Admin dashboard pages
│   ├── globals.css        # Global styles
│   ├── layout.tsx         # Root layout
│   └── page.tsx           # Home page
├── components/            # React components
│   ├── Auth/              # Authentication components
│   ├── Billing/           # Payment and subscription components
│   ├── Dashboard/         # User dashboard components
│   ├── Images/            # Image display and editing components
│   ├── Landing/           # Marketing landing page components
│   ├── Layout/            # Layout components (header, footer)
│   ├── UI/                # Reusable UI components
│   ├── Upload/            # File upload components
│   └── Workflow/          # Processing workflow components
├── hooks/                 # Custom React hooks
│   ├── useAuth.ts         # Authentication hook
│   ├── useUpload.ts       # File upload hook
│   └── useWebSocket.ts    # WebSocket connection hook
├── lib/                   # Utility libraries
│   └── api-client.ts      # API client with full backend integration
├── types/                 # TypeScript type definitions
│   ├── api.ts             # API response types
│   └── index.ts           # Component prop types
└── store/                 # State management (if needed)
```

## Key Components

### Authentication (`useAuth`)
- Google OAuth integration
- JWT token management
- Protected route handling
- Session persistence

### File Upload (`useUpload`)
- Drag & drop functionality
- File validation (size, type, duplicates)
- Progress tracking
- Batch creation

### WebSocket Integration (`useWebSocket`)
- Real-time progress updates
- Batch processing status
- Automatic reconnection
- Event-driven updates

### API Client
- Full REST API integration
- Authentication headers
- Error handling
- File upload with progress
- WebSocket connection management

## Backend Integration

This frontend connects to the following backend endpoints:

### Authentication
- `POST /api/auth/google` - Get OAuth URL
- `POST /api/auth/callback` - Handle OAuth callback
- `GET /api/auth/me` - Get user profile
- `POST /api/auth/logout` - Logout user

### Batches & Images
- `POST /api/batches` - Create new batch
- `GET /api/batches/:id` - Get batch details
- `POST /api/images/upload` - Upload images
- `PUT /api/images/:id` - Update image filename

### Payments
- `GET /api/payments/plans` - Get available plans
- `POST /api/payments/checkout` - Create checkout session
- `POST /api/payments/portal` - Create customer portal session

### WebSocket Events
- `progress:update` - Real-time processing updates
- `batch:completed` - Batch processing completion
- `quota:updated` - User quota updates

## Environment Variables

### Required
- `NEXT_PUBLIC_API_URL` - Backend API URL
- `NEXT_PUBLIC_GOOGLE_CLIENT_ID` - Google OAuth client ID
- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` - Stripe publishable key

### Optional
- `NEXT_PUBLIC_WS_URL` - WebSocket URL (defaults to API URL)
- `NEXT_PUBLIC_ENABLE_ANALYTICS` - Enable analytics tracking
- `NEXT_PUBLIC_ENABLE_DEBUG` - Enable debug mode

## Development

### Code Style
- TypeScript strict mode enabled
- ESLint configuration with Next.js rules
- Prettier for code formatting
- Tailwind CSS for styling

### Testing
- Jest for unit testing
- React Testing Library for component testing
- Cypress for E2E testing (configured)

### Storybook
- Component development and documentation
- Visual testing and design system showcase

## Deployment

### Production Build
```bash
npm run build
npm run start
```

### Environment Setup
1. Set production environment variables
2. Configure domain and SSL
3. Set up CDN for static assets
4. Configure monitoring and analytics

### Deployment Targets
- **Vercel**: Optimized for Next.js deployment
- **Netlify**: Static site deployment with serverless functions
- **Docker**: Containerized deployment with provided Dockerfile
- **Traditional Hosting**: Static export with `npm run build`

## Integration Testing

To test the complete integration:

1. **Start backend services**:
   - API server on port 3001
   - Database (PostgreSQL)
   - Redis for WebSocket
   - MinIO for file storage

2. **Configure authentication**:
   - Set up Google OAuth app
   - Configure redirect URIs
   - Add client ID to environment

3. **Test payment flow**:
   - Set up Stripe test account
   - Configure webhooks
   - Add publishable key to environment

4. **Run integration tests**:
   ```bash
   npm run test:integration
   ```

This frontend provides a complete, production-ready interface that seamlessly integrates with the existing backend infrastructure.