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:

   npm install
   

2. Set up environment variables:

   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:

   npm run dev
   

4. Open in browser: Navigate to 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

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:

   npm run test:integration
   

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