# 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.