From 2008349af29d3e0d33fb25fd21b5d8258219f37c Mon Sep 17 00:00:00 2001 From: szbk Date: Mon, 17 Nov 2025 11:39:53 +0300 Subject: [PATCH] =?UTF-8?q?D=C3=B6k=C3=BCmanlar=20olu=C5=9Fturuldu?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/README.md | 176 +++++++++ doc/api-data-models.md | 626 ++++++++++++++++++++++++++++++++ doc/application-workflows.md | 321 ++++++++++++++++ doc/architecture-overview.md | 448 +++++++++++++++++++++++ doc/technical-infrastructure.md | 206 +++++++++++ 5 files changed, 1777 insertions(+) create mode 100644 doc/README.md create mode 100644 doc/api-data-models.md create mode 100644 doc/application-workflows.md create mode 100644 doc/architecture-overview.md create mode 100644 doc/technical-infrastructure.md diff --git a/doc/README.md b/doc/README.md new file mode 100644 index 0000000..5199a75 --- /dev/null +++ b/doc/README.md @@ -0,0 +1,176 @@ +# imgPub Project Documentation + +## Overview + +**imgPub** is a modern web application that converts image documents into EPUB format through comprehensive OCR processing. The application provides a wizard-style interface for step-by-step document processing including image upload, cropping, OCR, translation, and EPUB generation. + +## Documentation Structure + +This documentation is designed to help AI systems and developers quickly understand and work with the imgPub codebase. All documentation is comprehensive yet concise, focusing on essential information needed for project comprehension. + +### Available Documentation + +#### 1. [Technical Infrastructure & Services](./technical-infrastructure.md) +- Complete technology stack overview +- Service architecture details +- Component organization and file structure +- Environment configuration and deployment +- Security considerations and performance optimizations + +#### 2. [Application Workflows & Processes](./application-workflows.md) +- Complete user journey documentation +- Step-by-step wizard workflow +- State management and data flow +- Error handling and recovery strategies +- Performance considerations and resource management + +#### 3. [Architecture Overview & Design Patterns](./architecture-overview.md) +- System architecture and component design +- Design patterns implementation +- Data flow architecture +- Security and performance architecture +- Testing and deployment architecture + +#### 4. [API Documentation & Data Models](./api-data-models.md) +- Complete API endpoint documentation +- Request/response formats +- Data models and type definitions +- Error handling models +- Configuration and environment variables + +## Quick Reference + +### Technology Stack +``` +Frontend: React 18 + Vite + Material-UI + Zustand +Backend: Node.js + Express + epub-gen +Auth: Supabase Authentication +OCR: Tesseract.js (client-side) +Translation: GLM-4.6 API +Database: PostgreSQL (via Supabase) +``` + +### Core Features +``` +1. Multi-file image upload with drag & drop +2. Interactive image cropping with visual selection +3. Batch crop processing for multiple images +4. Client-side OCR with Turkish language support +5. Optional text translation via GLM-4.6 +6. EPUB generation with custom metadata +7. User authentication and session management +8. Progressive wizard-style interface +``` + +### Key Components +``` +src/ +├── components/ # Wizard step components +├── store/ # Zustand state management +├── utils/ # Utility functions and API clients +├── pages/auth/ # Authentication pages +└── lib/ # External library configurations + +server/ +├── index.js # Express EPUB generation server +└── package.json # Backend dependencies +``` + +### API Endpoints +``` +Supabase Auth: +- POST /auth/v1/signup +- POST /auth/v1/token +- GET /auth/v1/user + +Backend EPUB Service: +- POST /generate-epub + +GLM-4.6 Translation: +- POST /chat/completions +``` + +### Development Commands +```bash +# Frontend development +npm install +npm run dev + +# Backend development +cd server +npm install +npm run dev + +# Combined development +npm run dev:all + +# Production build +npm run build +``` + +### Environment Variables +```bash +# Frontend +VITE_API_BASE_URL=http://localhost:4000 +VITE_SUPABASE_URL=your-supabase-url +VITE_SUPABASE_ANON_KEY=your-supabase-key +VITE_GLM_API_KEY=your-glm-api-key + +# Backend +CLIENT_ORIGIN=http://localhost:5173 +PORT=4000 +``` + +## Project Understanding Guide + +### For AI Systems + +This documentation provides complete information for: + +1. **Code Comprehension**: Understanding the entire codebase structure and functionality +2. **Feature Development**: Adding new features or modifying existing ones +3. **Bug Fixing**: Identifying and resolving issues in the application +4. **Testing**: Writing comprehensive tests for components and functionality +5. **Deployment**: Understanding the deployment architecture and requirements + +### Key Architectural Decisions + +1. **Client-Side OCR**: Tesseract.js runs in the browser for privacy and performance +2. **Progressive Wizard**: Step-by-step interface for complex document processing +3. **State Management**: Zustand for centralized, performant state handling +4. **Authentication**: Supabase for secure user management +5. **Microservices**: Separate EPUB generation service for scalability + +### Data Flow Summary + +``` +User Images → Upload → Crop → OCR → Translation → EPUB → Download + ↓ ↓ ↓ ↓ ↓ ↓ ↓ + Files State Canvas Text API Blob File + Storage Store Process Engine Call Data Download +``` + +### Security Considerations + +- JWT-based authentication via Supabase +- Client-side OCR (no server image uploads) +- Environment-based configuration +- CORS protection for API endpoints +- Input validation and sanitization + +### Performance Optimizations + +- Sequential image processing to manage memory +- Automatic blob URL cleanup +- Lazy loading of heavy assets +- Efficient state management +- Code splitting for better loading times + +## Getting Started + +1. **Read the Technical Infrastructure document** to understand the stack and services +2. **Review the Application Workflows** to understand the user journey and data flow +3. **Study the Architecture Overview** to understand design patterns and structure +4. **Reference the API Documentation** for integration details and data models + +This comprehensive documentation should provide everything needed to understand, modify, and extend the imgPub application effectively. \ No newline at end of file diff --git a/doc/api-data-models.md b/doc/api-data-models.md new file mode 100644 index 0000000..a452630 --- /dev/null +++ b/doc/api-data-models.md @@ -0,0 +1,626 @@ +# API Documentation & Data Models + +## Overview + +This document describes all API endpoints, request/response formats, and data models used throughout the imgPub application ecosystem. + +## External APIs + +### 1. Supabase Authentication API + +#### Configuration +```javascript +const supabaseConfig = { + url: process.env.VITE_SUPABASE_URL, + anonKey: process.env.VITE_SUPABASE_ANON_KEY, +}; +``` + +#### Authentication Endpoints + +##### User Registration +```http +POST /auth/v1/signup +Content-Type: application/json + +{ + "email": "user@example.com", + "password": "securePassword123", + "options": { + "data": { + "username": "preferredUsername" + } + } +} + +Response: +{ + "user": { + "id": "uuid-string", + "email": "user@example.com", + "username": "preferredUsername", + "created_at": "2024-01-01T00:00:00Z" + }, + "session": { + "access_token": "jwt-token", + "refresh_token": "refresh-token", + "expires_in": 3600 + } +} +``` + +##### User Login +```http +POST /auth/v1/token?grant_type=password +Content-Type: application/json + +{ + "email": "user@example.com", + "password": "securePassword123" +} + +Response: +{ + "access_token": "jwt-token", + "refresh_token": "refresh-token", + "expires_in": 3600, + "user": { + "id": "uuid-string", + "email": "user@example.com", + "username": "preferredUsername" + } +} +``` + +##### Google OAuth +```http +GET /auth/v1/authorize?provider=google +Redirect URI configured in Supabase dashboard + +Response (after redirect): +{ + "access_token": "oauth-jwt-token", + "refresh_token": "oauth-refresh-token", + "expires_in": 3600, + "user": { + "id": "uuid-string", + "email": "user@gmail.com", + "username": "usergmail" + } +} +``` + +##### Current User Info +```http +GET /auth/v1/user +Authorization: Bearer {access_token} + +Response: +{ + "id": "uuid-string", + "email": "user@example.com", + "username": "preferredUsername", + "created_at": "2024-01-01T00:00:00Z", + "last_sign_in_at": "2024-01-15T10:30:00Z" +} +``` + +### 2. Backend EPUB Generation API + +#### Base URL +``` +Development: http://localhost:4000 +Production: https://api.imgpub.com +``` + +#### Generate EPUB Endpoint +```http +POST /generate-epub +Content-Type: application/json +Authorization: Bearer {auth_token} (optional) + +Request Body: +{ + "text": "Complete OCR text content with Turkish characters...", + "meta": { + "title": "Book Title", + "author": "Author Name", + "publisher": "Publisher Name", + "description": "Book description", + "isbn": "978-3-16-148410-0", + "language": "tr", + "coverImage": "base64-encoded-image-data" + } +} + +Response (200 OK): +{ + "success": true, + "filename": "book-title.epub", + "data": "base64-encoded-epub-content", + "metadata": { + "title": "Book Title", + "author": "Author Name", + "created_at": "2024-01-15T14:30:00Z", + "file_size": 1024000 + } +} + +Error Response (400 Bad Request): +{ + "success": false, + "error": "Invalid metadata format", + "details": "Title and author are required fields" +} + +Error Response (500 Internal Server Error): +{ + "success": false, + "error": "EPUB generation failed", + "details": "Unable to process text content" +} +``` + +### 3. GLM-4.6 Translation API + +#### Configuration +```javascript +const translationConfig = { + baseUrl: 'https://apiglm.example.com/v1', + apiKey: process.env.VITE_GLM_API_KEY, + model: 'glm-4.6', + maxTokens: 4000, + temperature: 0.3 +}; +``` + +#### Translation Endpoint +```http +POST /chat/completions +Content-Type: application/json +Authorization: Bearer {glm_api_key} + +Request Body: +{ + "model": "glm-4.6", + "messages": [ + { + "role": "system", + "content": "You are a professional translator. Translate the following Turkish text to English while preserving meaning and context." + }, + { + "role": "user", + "content": "Turkish text to translate..." + } + ], + "max_tokens": 4000, + "temperature": 0.3, + "stream": false +} + +Response (200 OK): +{ + "id": "chatcmpl-translation-id", + "object": "chat.completion", + "created": 1705315200, + "model": "glm-4.6", + "choices": [ + { + "index": 0, + "message": { + "role": "assistant", + "content": "Translated English text..." + }, + "finish_reason": "stop" + } + ], + "usage": { + "prompt_tokens": 1500, + "completion_tokens": 1800, + "total_tokens": 3300 + } +} + +Error Response (401 Unauthorized): +{ + "error": { + "message": "Invalid API key", + "type": "invalid_request_error" + } +} + +Error Response (429 Rate Limited): +{ + "error": { + "message": "Rate limit exceeded", + "type": "rate_limit_error", + "retry_after": 60 + } +} +``` + +## Internal Data Models + +### Application State Model (Zustand Store) + +#### Complete State Structure +```typescript +interface AppState { + // File Management + uploadedImages: UploadedImage[]; + cropConfig: CropConfiguration; + croppedImages: CroppedImage[]; + coverImageId: string | null; + coverCropConfig: CropConfiguration; + croppedCoverImage: CroppedImage | null; + + // Text Processing + ocrText: string; + bookTitle: string; + bookMetadata: BookMetadata | null; + translatedText: string; + translationStatus: TranslationStatus; + translationError: string | null; + translationProgress: number; + + // Generated Content + generatedEpub: EpubData | null; + + // Authentication + authToken: string | null; + currentUser: User | null; + + // Error Handling + error: string | null; + + // Actions + // ... (actions omitted for brevity) +} +``` + +#### Data Type Definitions +```typescript +interface UploadedImage { + id: string; + file: File; + url: string; // Blob URL for preview + name: string; + size: number; + type: string; + uploadedAt: Date; +} + +interface CropConfiguration { + x: number; + y: number; + zoom: number; + width: number; + height: number; + top: number; + bottom: number; + left: number; + right: number; + cropAreaX: number; + cropAreaY: number; + imageWidth: number; + imageHeight: number; + referenceImageId: string | null; + selection: CropSelection | null; +} + +interface CropSelection { + x: number; + y: number; + width: number; + height: number; +} + +interface CroppedImage { + id: string; + originalImageId: string; + blob: Blob; + url: string; // Blob URL for display + cropConfig: CropConfiguration; + processedAt: Date; +} + +interface BookMetadata { + title: string; + author: string; + publisher?: string; + description?: string; + isbn?: string; + language: string; + publishedDate?: string; + tags?: string[]; + coverImageData?: string; // Base64 +} + +type TranslationStatus = 'idle' | 'processing' | 'completed' | 'error'; + +interface User { + id: string; + email: string; + username: string; + createdAt: string; + lastSignInAt?: string; + profileImageUrl?: string; +} + +interface EpubData { + filename: string; + blob: Blob; + url: string; // Download URL + metadata: BookMetadata; + createdAt: Date; + fileSize: number; +} +``` + +### Component Props Models + +#### Upload Step Component +```typescript +interface UploadStepProps { + onFilesUploaded: (files: File[]) => void; + maxFiles: number; + acceptedFileTypes: string[]; + maxFileSize: number; +} + +interface ImagePreviewProps { + images: UploadedImage[]; + onRemoveImage: (imageId: string) => void; + onCropImage: (imageId: string) => void; +} +``` + +#### Crop Step Component +```typescript +interface CropStepProps { + images: UploadedImage[]; + cropConfig: CropConfiguration; + onCropConfigChange: (config: CropConfiguration) => void; + referenceImageId: string; + onReferenceChange: (imageId: string) => void; +} + +interface CropControlsProps { + cropConfig: CropConfiguration; + onConfigChange: (config: CropConfiguration) => void; + imageDimensions: { width: number; height: number }; +} +``` + +#### OCR Step Component +```typescript +interface OcrStepProps { + images: CroppedImage[]; + onOcrComplete: (text: string) => void; + onProgressUpdate: (progress: number) => void; +} + +interface OcrProgressProps { + currentImage: number; + totalImages: number; + currentProgress: number; + extractedText: string; +} +``` + +### API Client Models + +#### Request Models +```typescript +interface GenerateEpubRequest { + text: string; + meta: BookMetadata; +} + +interface TranslationRequest { + text: string; + sourceLanguage: string; + targetLanguage: string; + maxTokens?: number; +} + +interface AuthRequest { + email: string; + password: string; + username?: string; +} +``` + +#### Response Models +```typescript +interface ApiResponse { + success: boolean; + data?: T; + error?: string; + details?: string; +} + +interface GenerateEpubResponse { + filename: string; + data: string; // Base64 encoded + metadata: { + title: string; + author: string; + created_at: string; + file_size: number; + }; +} + +interface TranslationResponse { + translatedText: string; + usage: { + promptTokens: number; + completionTokens: number; + totalTokens: number; + }; +} + +interface AuthResponse { + user: User; + session: Session; +} + +interface Session { + accessToken: string; + refreshToken: string; + expiresAt: number; +} +``` + +### Error Models + +#### Application Errors +```typescript +interface ApplicationError { + code: string; + message: string; + details?: any; + timestamp: Date; + context?: string; +} + +type ErrorCode = + | 'FILE_TOO_LARGE' + | 'INVALID_FILE_TYPE' + | 'OCR_PROCESSING_FAILED' + | 'TRANSLATION_FAILED' + | 'EPUB_GENERATION_FAILED' + | 'AUTHENTICATION_ERROR' + | 'NETWORK_ERROR' + | 'UNKNOWN_ERROR'; + +interface ErrorState { + code: ErrorCode; + message: string; + details?: any; + retryable: boolean; + userAction?: string; +} +``` + +### Configuration Models + +#### Application Configuration +```typescript +interface AppConfig { + api: { + baseUrl: string; + timeout: number; + retries: number; + }; + ocr: { + languages: string[]; + workerPath: string; + corePath: string; + langPath: string; + }; + translation: { + maxTextLength: number; + chunkSize: number; + timeout: number; + }; + upload: { + maxFileSize: number; + maxFiles: number; + allowedTypes: string[]; + }; + epub: { + defaultLanguage: string; + supportedFormats: string[]; + }; +} +``` + +#### Environment Configuration +```typescript +interface EnvConfig { + VITE_API_BASE_URL: string; + VITE_SUPABASE_URL: string; + VITE_SUPABASE_ANON_KEY: string; + VITE_GLM_API_KEY: string; + VITE_APP_NAME: string; + VITE_APP_VERSION: string; +} +``` + +## Data Flow Examples + +### File Upload Flow +```typescript +// File Upload Sequence +const handleFileUpload = async (files: FileList): Promise => { + try { + // 1. Validate files + const validFiles = validateFiles(files); + + // 2. Convert to UploadedImage model + const uploadedImages: UploadedImage[] = await Promise.all( + Array.from(validFiles).map(async (file) => ({ + id: generateId(), + file, + url: URL.createObjectURL(file), + name: file.name, + size: file.size, + type: file.type, + uploadedAt: new Date() + })) + ); + + // 3. Update state + useAppStore.getState().setUploadedImages(uploadedImages); + + // 4. Navigate to next step + navigate('/crop'); + + } catch (error) { + // 5. Handle error + useAppStore.getState().setError(error.message); + } +}; +``` + +### EPUB Generation Flow +```typescript +// EPUB Generation Sequence +const generateEpub = async (): Promise => { + try { + // 1. Prepare request data + const requestData: GenerateEpubRequest = { + text: finalText, + meta: bookMetadata + }; + + // 2. API call + const response = await epubService.generate(requestData); + + // 3. Process response + const epubData: EpubData = { + filename: response.filename, + blob: base64ToBlob(response.data), + url: '', // Will be created + metadata: response.metadata, + createdAt: new Date(), + fileSize: response.metadata.file_size + }; + + // 4. Create download URL + epubData.url = URL.createObjectURL(epubData.blob); + + // 5. Update state + useAppStore.getState().setGeneratedEpub(epubData); + + // 6. Navigate to download step + navigate('/download'); + + } catch (error) { + useAppStore.getState().setError('EPUB generation failed'); + } +}; +``` + +This comprehensive API and data model documentation provides complete information for understanding all data structures, API endpoints, and integration patterns within the imgPub application. \ No newline at end of file diff --git a/doc/application-workflows.md b/doc/application-workflows.md new file mode 100644 index 0000000..d1e25d7 --- /dev/null +++ b/doc/application-workflows.md @@ -0,0 +1,321 @@ +# Application Workflows & Processes Documentation + +## Wizard Workflow Overview + +The imgPub application follows a linear wizard-based workflow with 7 main steps. Each step builds upon the previous one, maintaining state throughout the entire process. + +## Complete User Journey + +### 1. Authentication Flow +``` +User Interaction: +├── Login Screen → Choose Google OAuth or Email/Password +├── Google OAuth → Redirect to Google → Return with token +├── Email Login → Input credentials → Validate via Supabase +└── Registration → Create account → Store user data + +Technical Process: +├── Supabase Auth handles authentication +├── JWT tokens stored in localStorage +├── User session maintained across app +└── Token sent with API requests for validation +``` + +### 2. Upload Step (Step 1) +``` +User Interaction: +├── Drag & Drop files into upload zone +├── Click to browse file selection +├── Multiple file selection supported +└── File type validation (PNG, JPG, JPEG) + +Technical Process: +├── Files stored as File objects in state +├── Preview URLs generated using URL.createObjectURL() +├── File validation for type and size +├── State update in useAppStore.uploadedImages +└── Navigation enabled to crop step +``` + +### 3. Crop Step (Step 2) +``` +User Interaction: +├── Select reference image from uploaded files +├── Visual crop selection with drag handles +├── Manual offset inputs (top, bottom, left, right) +├── Zoom controls for precision +└── Preview of crop area + +Technical Process: +├── Canvas-based image rendering +├── Interactive selection with mouse events +├── Percentage-based crop calculations +├── Crop configuration saved to state +└── Reference image tracking for batch processing +``` + +### 4. Bulk Crop Step (Step 3) +``` +User Interaction: +├── Apply crop configuration to all images +├── Progress indicator for processing +├── Preview of cropped images +├── Individual crop adjustments if needed +└── Continue to OCR step + +Technical Process: +├── Sequential canvas operations for each image +├── Blob generation from cropped canvas data +├── New URL creation for cropped images +├── State update with cropped image array +└── Memory management for old blob URLs +``` + +### 5. OCR Step (Step 4) +``` +User Interaction: +├── Start OCR processing button +├── Progress indicator for each image +├── Real-time text extraction display +├── Error handling for failed processing +└── Continue to translation step + +Technical Process: +├── Tesseract.js worker initialization +├── Sequential processing of cropped images +├── Turkish language detection (primary) +├── English fallback language support +├── Text cleaning and concatenation +├── Progress tracking and state updates +└── Complete OCR text stored in state +``` + +### 6. Translation Step (Step 5) +``` +User Interaction: +├── Skip translation (optional step) +├── Language selection (English as target) +├── Start translation button +├── Progress indicator for translation +└── Continue to EPUB step + +Technical Process: +├── GLM-4.6 API integration +├── Chunk-based text processing for large content +├── Progress tracking and status updates +├── Error handling for API failures +├── Translated text storage in state +└── Fallback to original text on translation failure +``` + +### 7. EPUB Generation Step (Step 6) +``` +User Interaction: +├── Book title input +├── Author information input +├── Cover image selection (optional) +├── Metadata configuration +└── Generate EPUB button + +Technical Process: +├── Metadata validation and storage +├── Cover image cropping and processing +├── API call to backend EPUB service +├── Base64 EPUB data reception +├── Blob creation and URL generation +└── EPUB data stored in application state +``` + +### 8. Download Step (Step 7) +``` +User Interaction: +├── EPUB metadata display +├── Preview download information +├── Download EPUB button +├── Start new process option +└── Navigation to reset workflow + +Technical Process: +├── EPUB blob retrieval from state +├── File download using HTML5 download attribute +├── Workflow reset functionality +├── Memory cleanup (blob URL revocation) +└── Return to initial upload step +``` + +## State Management Flow + +### Workflow State Transitions +```javascript +Initial State → Upload → Crop → Bulk Crop → OCR → Translation → EPUB → Download + +Reset Points: +├── resetFromStep('upload'): Clears everything after upload +├── resetFromStep('crop'): Clears crops, OCR, EPUB data +├── resetFromStep('ocr'): Clears OCR and EPUB data +└── resetFromStep('epub'): Clears only EPUB data +``` + +### Memory Management +``` +Automatic Cleanup: +├── Blob URL revocation on state updates +├── Canvas cleanup after image processing +├── Worker cleanup after OCR completion +├── Component unmount cleanup +└── Navigation guard cleanup + +Manual Cleanup: +├── Reset workflow buttons +├── Navigation step changes +├── Authentication state changes +└── Error recovery actions +``` + +## Data Processing Pipelines + +### Image Processing Pipeline +``` +Upload Files → File Validation → Preview Generation → +Reference Selection → Crop Configuration → Canvas Processing → +Blob Generation → URL Creation → Storage in State +``` + +### OCR Processing Pipeline +``` +Cropped Images → Worker Initialization → Sequential Processing → +Text Extraction → Language Detection → Text Cleaning → +Concatenation → State Storage +``` + +### EPUB Generation Pipeline +``` +OCR Text → Translation (optional) → Metadata Assembly → +API Request → Backend Processing → Base64 Response → +Blob Creation → Download Preparation +``` + +## Error Handling & Recovery + +### Common Error Scenarios +``` +File Upload Errors: +├── Invalid file types +├── File size exceeded +├── Multiple file limits +└── Browser compatibility issues + +OCR Processing Errors: +├── Tesseract worker failures +├── Language detection issues +├── Memory constraints +└── Image quality problems + +Translation Errors: +├── API unavailability +├── Rate limiting +├── Network connectivity +└── Text size limitations + +EPUB Generation Errors: +├── Backend service unavailability +├── Invalid metadata +├── File generation failures +└── Download preparation issues +``` + +### Recovery Strategies +``` +User-Friendly Recovery: +├── Retry buttons for failed operations +├── Step-wise reset options +├── Clear error messaging +├── Alternative action suggestions +└── State preservation during recovery + +Technical Recovery: +├── Automatic retry mechanisms +├── Fallback language support +├── Service health checks +├── Graceful degradation +└── Error boundary implementation +``` + +## Performance Considerations + +### Sequential Processing Benefits +``` +Memory Efficiency: +├── One image processed at a time +├── Predictable memory usage +├── Automatic cleanup between operations +└── Browser stability maintenance + +User Experience: +├── Clear progress indication +├── Cancellable operations +├── Real-time feedback +└── Estimated completion times +``` + +### Resource Management +``` +Optimization Strategies: +├── Worker reuse for OCR processing +├── Canvas pool for image operations +├── Lazy loading of heavy assets +├── Debounced user interactions +└── Efficient state updates + +Memory Patterns: +├── Minimal object creation +├── Reusable data structures +├── Blob lifecycle management +├── URL object cleanup +└── Component unmount handling +``` + +## Integration Points + +### External Service Dependencies +``` +Supabase Authentication: +├── User session management +├── OAuth integration +├── Token validation +└── User data persistence + +Tesseract.js OCR Engine: +├── Client-side processing +├── Local asset loading +├── Worker management +└── Text extraction + +GLM-4.6 Translation API: +├── RESTful API integration +├── Authentication headers +├── Error handling +└── Response processing + +Backend EPUB Service: +├── Express server communication +├── Base64 data handling +├── File generation +└── Response streaming +``` + +### Browser Compatibility +``` +Modern Browser Requirements: +├── ES6+ JavaScript support +├── Canvas API compatibility +├── File API support +├── Fetch API availability +└── WebAssembly support (for Tesseract) + +Progressive Enhancement: +├── Feature detection +├── Fallback mechanisms +├── Graceful degradation +├── Error boundary protection +└── Cross-browser testing \ No newline at end of file diff --git a/doc/architecture-overview.md b/doc/architecture-overview.md new file mode 100644 index 0000000..362061e --- /dev/null +++ b/doc/architecture-overview.md @@ -0,0 +1,448 @@ +# Architecture Overview & Design Patterns + +## System Architecture + +### High-Level Architecture +``` +┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ +│ Browser │ │ Backend │ │ External │ +│ (Frontend) │ │ Services │ │ Services │ +│ │ │ │ │ │ +│ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ +│ │ React App │◄┼────┼──│ Express API │◄┼────┼──│ GLM-4.6 API │ │ +│ │ (Vite) │ │ │ │ (EPUB Gen) │ │ │ │ (Translation)│ │ +│ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ +│ │ │ │ │ │ +│ ┌─────────────┐ │ │ │ │ ┌─────────────┐ │ +│ │ Supabase │◄┼────────────────────┼────┼──│ Supabase │ │ +│ │ Auth │ │ │ │ │ Database │ │ +│ └─────────────┘ │ │ │ └─────────────┘ │ +│ │ │ │ │ +│ ┌─────────────┐ │ │ │ │ +│ │ Tesseract │ │ │ │ │ +│ │ OCR Engine │ │ │ │ │ +│ └─────────────┘ │ │ │ │ +└─────────────────┘ └─────────────────┘ └─────────────────┘ +``` + +### Component Architecture + +#### Frontend Layer Architecture +``` +┌─────────────────────────────────────────────────────────────┐ +│ Presentation Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Header │ │ Stepper │ │ Main Content │ │ +│ │ Component │ │ Component │ │ (Router Outlet) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Application Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Router │ │ State │ │ Utility │ │ +│ │ Management │ │ Management │ │ Services │ │ +│ │(React Router)│ │ (Zustand) │ │ (API, Auth, Utils) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + │ +┌─────────────────────────────────────────────────────────────┐ +│ Data Layer │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │ +│ │ Browser │ │ Local │ │ External │ │ +│ │ Storage │ │ Storage │ │ APIs │ │ +│ │ (Blobs, URLs)│ │ (localStorage)│ │ (Supabase, Backend) │ │ +│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +## Design Patterns + +### 1. State Management Pattern (Zustand) +```javascript +// Centralized Store Pattern +const useAppStore = create((set, get) => ({ + // State + uploadedImages: [], + cropConfig: {}, + ocrText: '', + + // Actions + setUploadedImages: (images) => set({ uploadedImages: images }), + resetFromStep: (step) => set((state) => { + // Clean, atomic state updates + const newState = {}; + // Reset logic based on step + return newState; + }), +})); + +// Usage in components +const uploadedImages = useAppStore(state => state.uploadedImages); +const setUploadedImages = useAppStore(state => state.setUploadedImages); +``` + +### 2. Component Composition Pattern +```javascript +// Wizard Step Composition +const WizardStep = ({ children, title, onNext, onPrev }) => { + return ( + + {title} + {children} + + + ); +}; + +// Specific step implementation +const UploadStep = () => { + return ( + + + + + ); +}; +``` + +### 3. Service Layer Pattern +```javascript +// API Service Abstraction +export const epubService = { + generate: async (text, metadata) => { + const response = await fetch(`${API_BASE_URL}/generate-epub`, { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ text, meta: metadata }), + }); + return response.json(); + }, +}; + +// Authentication Service +export const authService = { + login: async (credentials) => { + // Authentication logic + }, + logout: async () => { + // Logout logic + }, +}; +``` + +### 4. Observer Pattern (Authentication) +```javascript +// Supabase Auth Observer +useEffect(() => { + const { data: subscription } = supabaseClient.auth.onAuthStateChange( + (event, session) => { + if (event === 'SIGNED_IN') { + // Handle sign in + exchangeGoogleSession(session); + } else if (event === 'SIGNED_OUT') { + // Handle sign out + clearAuthSession(); + } + } + ); + + return () => subscription.subscription.unsubscribe(); +}, []); +``` + +### 5. Strategy Pattern (OCR Processing) +```javascript +// OCR Language Strategy +const ocrLanguageStrategy = { + primary: 'tur', + fallback: 'eng', + detect: async (imageData) => { + try { + const result = await worker.recognize(imageData, 'tur'); + return result.data.text; + } catch (error) { + // Fallback to English + return await worker.recognize(imageData, 'eng'); + } + }, +}; +``` + +## Data Flow Architecture + +### Unidirectional Data Flow +``` +User Action → Component Event → State Update → Re-render → New UI + +Example: +1. User uploads files +2. Dropzone component triggers onDrop +3. useAppStore.setUploadedImages() called +4. State updated in Zustand store +5. Components subscribed to state re-render +6. New UI shows uploaded images +``` + +### Async Data Handling +```javascript +// Async Action Pattern +const handleOcrProcessing = async () => { + try { + setTranslationStatus('processing'); + setTranslationProgress(0); + + const processedText = await processOcrImages( + croppedImages, + (progress) => setTranslationProgress(progress) + ); + + setOcrText(processedText); + setTranslationStatus('completed'); + } catch (error) { + setTranslationError(error.message); + setTranslationStatus('error'); + } +}; +``` + +## Component Architecture + +### Hierarchy Structure +``` +App (Root Component) +├── Header (Authentication & Navigation) +├── Stepper (Wizard Progress) +├── Main Content (Router Outlet) +│ ├── UploadStep +│ ├── CropStep +│ ├── BulkCropStep +│ ├── OcrStep +│ ├── TranslationStep +│ ├── EpubStep +│ ├── DownloadStep +│ └── Auth Pages +└── Error Handling (Snackbar) +``` + +### Smart vs Dumb Components +```javascript +// Smart Component (Stateful) +const OcrStep = () => { + const { croppedImages, ocrText, setOcrText } = useAppStore(); + const [isProcessing, setIsProcessing] = useState(false); + + const handleOcrStart = async () => { + setIsProcessing(true); + // OCR processing logic + setOcrText(resultText); + setIsProcessing(false); + }; + + return ( + + ); +}; + +// Dumb Component (Presentational) +const OcrProcessing = ({ images, onStart, isProcessing, result }) => { + return ( + + + {isProcessing && } + {result && } + + ); +}; +``` + +## Security Architecture + +### Authentication Flow +``` +User Login Attempt + ↓ +Supabase Auth Service + ↓ +JWT Token Generation + ↓ +Token Storage (localStorage) + ↓ +Authenticated API Requests + ↓ +Token Validation & Refresh +``` + +### Data Security Measures +```javascript +// Secure API Requests +const secureApiCall = async (endpoint, data) => { + const token = useAppStore.getState().authToken; + + return await fetch(endpoint, { + headers: { + 'Authorization': `Bearer ${token}`, + 'Content-Type': 'application/json', + }, + body: JSON.stringify(data), + }); +}; + +// Data Sanitization +const sanitizeInput = (input) => { + return input + .trim() + .replace(/[<>]/g, '') // Remove potential HTML + .substring(0, MAX_LENGTH); // Length limit +}; +``` + +## Performance Architecture + +### Lazy Loading Pattern +```javascript +// Code Splitting +const UploadStep = lazy(() => import('./components/UploadStep')); +const CropStep = lazy(() => import('./components/CropStep')); + +// Asset Lazy Loading +const loadTesseractAssets = async () => { + const worker = await createWorker('tur', 1, { + workerPath: '/tesseract/worker.min.js', + corePath: '/tesseract/tesseract-core-simd-lstm.wasm.js', + langPath: '/tesseract/', + }); + return worker; +}; +``` + +### Memory Management Pattern +```javascript +// Resource Cleanup +useEffect(() => { + return () => { + // Cleanup on unmount + if (generatedEpub?.url) { + URL.revokeObjectURL(generatedEpub.url); + } + }; +}, []); + +// Batch Processing Control +const processImagesInBatches = async (images, batchSize = 5) => { + for (let i = 0; i < images.length; i += batchSize) { + const batch = images.slice(i, i + batchSize); + await processBatch(batch); + + // Allow UI to breathe + await new Promise(resolve => setTimeout(resolve, 100)); + } +}; +``` + +## Error Handling Architecture + +### Error Boundary Pattern +```javascript +const ErrorBoundary = ({ children }) => { + const [hasError, setHasError] = useState(false); + const [error, setError] = useState(null); + + const handleError = (error, errorInfo) => { + setHasError(true); + setError(error); + // Log error to service + logError(error, errorInfo); + }; + + if (hasError) { + return ; + } + + return ( + + {children} + + ); +}; +``` + +### Global Error Handling +```javascript +// Global Error Store +const useErrorStore = create((set) => ({ + error: null, + setError: (message) => set({ error: message }), + clearError: () => set({ error: null }), +})); + +// Error Display Component +const ErrorDisplay = () => { + const error = useAppStore(state => state.error); + const clearError = useAppStore(state => state.clearError); + + return ( + + + {error} + + + ); +}; +``` + +## Testing Architecture + +### Component Testing Strategy +``` +Unit Tests: +├── Utility functions (fileUtils, ocrUtils) +├── Service layer functions +└── Custom hooks + +Integration Tests: +├── Component interactions +├── State management flow +└── API service integration + +E2E Tests: +├── Complete user workflows +├── Authentication flows +└── File processing pipelines +``` + +## Deployment Architecture + +### Build Process +``` +Development: +├── Vite dev server +├── Hot module replacement +├── Source maps +└── Fast refresh + +Production: +├── Code optimization +├── Asset bundling +├── Tree shaking +└── Compression +``` + +### Container Strategy +```dockerfile +# Multi-stage Docker build +FROM node:18-alpine AS builder +# Build stage + +FROM nginx:alpine AS production +# Production stage with static files +``` + +This architecture provides a robust, scalable foundation for the imgPub application with clear separation of concerns, maintainable code structure, and optimized performance characteristics. \ No newline at end of file diff --git a/doc/technical-infrastructure.md b/doc/technical-infrastructure.md new file mode 100644 index 0000000..70031cf --- /dev/null +++ b/doc/technical-infrastructure.md @@ -0,0 +1,206 @@ +# Technical Infrastructure & Services Documentation + +## Project Overview +**imgPub** is a modern web application that converts image documents into EPUB format through OCR processing. The application provides a wizard-style interface for step-by-step document processing including image upload, cropping, OCR, translation, and EPUB generation. + +## Technology Stack + +### Frontend +- **Framework**: React 18.3.1 +- **Build Tool**: Vite 5.4.10 +- **UI Library**: Material-UI (MUI) v6.1.1 +- **State Management**: Zustand 5.0.2 +- **Routing**: React Router DOM v7.0.2 +- **HTTP Client**: Axios/Fetch API +- **Authentication**: Supabase Auth + +### Backend Services +- **Authentication**: Supabase (PostgreSQL database) +- **EPUB Generation**: Node.js + Express + epub-gen +- **OCR Processing**: Tesseract.js 5.1.1 (client-side) +- **Translation**: GLM-4.6 API integration + +### Development Tools +- **Containerization**: Docker & Docker Compose +- **Package Manager**: npm +- **Code Style**: ESLint (ES6+) + +## Core Services Architecture + +### 1. Frontend Application (Port 5173) +- Single Page Application (SPA) with wizard-style navigation +- Client-side OCR processing using Tesseract.js +- Real-time image cropping with canvas manipulation +- State management through Zustand store +- Authentication integration with Supabase + +### 2. Backend EPUB Service (Port 4000) +- Express.js server running in `/server` directory +- Single endpoint: `POST /generate-epub` +- Uses epub-gen library for EPUB generation +- Returns base64-encoded EPUB files +- CORS enabled for frontend communication + +### 3. Authentication Service (Supabase) +- User registration and login +- Google OAuth integration +- Session management +- User data persistence + +## Key Components + +### Image Processing Pipeline +1. **Upload**: Multi-file drag-drop interface with preview +2. **Crop**: Interactive cropping with visual selection handles +3. **Bulk Processing**: Batch crop application to multiple images +4. **OCR**: Text extraction from cropped images (Turkish + English) +5. **Translation**: Optional text translation using GLM-4.6 +6. **EPUB Generation**: Final document creation and download + +### State Management Structure +```javascript +Core State: +- uploadedImages: File array with preview URLs +- cropConfig: Cropping selection data +- croppedImages: Processed image blobs +- ocrText: Extracted text content +- translatedText: Optional translated content +- generatedEpub: Final EPUB blob and metadata +- authToken/currentUser: Authentication state +``` + +## File Organization + +``` +src/ +├── components/ # React components for wizard steps +│ ├── UploadStep.jsx # File upload interface +│ ├── CropStep.jsx # Image cropping +│ ├── BulkCropStep.jsx # Batch processing +│ ├── OcrStep.jsx # OCR processing +│ ├── TranslationStep.jsx # Text translation +│ ├── EpubStep.jsx # EPUB metadata +│ └── DownloadStep.jsx # Final download +├── pages/auth/ # Authentication pages +├── store/ +│ └── useAppStore.js # Zustand state management +├── utils/ +│ ├── fileUtils.js # File handling utilities +│ ├── ocrUtils.js # OCR processing +│ ├── cropUtils.js # Image cropping +│ ├── epubUtils.js # EPUB API client +│ ├── authApi.js # Authentication API +│ └── translationUtils.js # Translation handling +└── lib/ + └── supabaseClient.js # Supabase configuration + +server/ +├── index.js # Express server +├── package.json # Backend dependencies +└── node_modules/ # Backend packages + +public/ +├── tesseract/ # OCR engine assets +│ ├── worker.min.js +│ ├── tesseract-core-simd-lstm.wasm(.js) +│ ├── eng.traineddata +│ └── tur.traineddata +└── fonts/ # Font assets for UI +``` + +## Data Flow + +### User Workflow +1. **Authentication**: Login via Supabase (Google OAuth or email/password) +2. **Image Upload**: Multiple files selected, preview URLs generated +3. **Reference Selection**: Choose reference image for crop configuration +4. **Crop Configuration**: Visual selection area definition +5. **Batch Processing**: Apply crop to all uploaded images +6. **OCR Processing**: Sequential text extraction from cropped images +7. **Optional Translation**: Text translation via GLM-4.6 API +8. **EPUB Generation**: Send text to backend service +9. **Download**: Retrieve and download generated EPUB + +### API Endpoints + +#### Frontend ↔ Backend +- `POST /generate-epub` (EPUB service) + - Request: `{ text: string, meta: object }` + - Response: `{ filename: string, data: base64-string }` + +#### Frontend ↔ Supabase +- Authentication endpoints (handled by Supabase client) +- User profile management +- Session validation + +## Environment Configuration + +### Frontend (.env) +- `VITE_API_BASE_URL`: Backend service URL +- `VITE_SUPABASE_URL`: Supabase project URL +- `VITE_SUPABASE_ANON_KEY`: Supabase anonymous key + +### Backend (.env) +- `CLIENT_ORIGIN`: Frontend URL for CORS +- `PORT`: Server port (default: 4000) + +## Security Considerations + +### Authentication +- JWT tokens stored in localStorage +- Session management via Supabase +- Google OAuth integration with proper token handling + +### Data Handling +- Client-side OCR processing (no server upload of images) +- Temporary blob URLs automatically revoked +- No persistent storage of user images + +### API Security +- CORS configuration for cross-origin requests +- Environment variable for API keys +- No sensitive data in frontend code + +## Performance Optimizations + +### OCR Processing +- Single Tesseract worker reused across images +- Local asset serving (no CDN dependencies) +- Sequential processing to manage CPU usage + +### Memory Management +- Automatic blob URL revocation +- State cleanup on workflow reset +- Efficient state management with Zustand + +### Build Optimization +- Vite's optimized bundling +- Asset chunking for large libraries +- Development hot refresh + +## Deployment + +### Development +```bash +# Frontend +npm install +npm run dev + +# Backend +cd server +npm install +npm run dev + +# Combined development +npm run dev:all +``` + +### Production Build +```bash +npm run build # Frontend build to dist/ +``` + +### Containerization +- Dockerfile for frontend containerization +- docker-compose.yml for multi-service deployment +- Production-ready configuration included \ No newline at end of file