imgPub/doc/application-workflows.md

# 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