Dökümanlar oluşturuldu

2025-11-17 11:39:53 +03:00
parent b6c9fb795b
commit 2008349af2
5 changed files with 1777 additions and 0 deletions
--- a/doc/application-workflows.md
+++ 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