# 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