8.9 KiB
8.9 KiB
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
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