PDF & ZIP IMPORT

- Testing Coverage
- Image Handling
- Session Handling
- Library Switching

.env.production

@@ -19,7 +19,7 @@ JWT_SECRET=REPLACE_WITH_SECURE_JWT_SECRET_MINIMUM_32_CHARS
 APP_PASSWORD=REPLACE_WITH_SECURE_APP_PASSWORD
 
 # OpenSearch Configuration
-OPENSEARCH_PASSWORD=REPLACE_WITH_SECURE_OPENSEARCH_PASSWORD
+#OPENSEARCH_PASSWORD=REPLACE_WITH_SECURE_OPENSEARCH_PASSWORD
 SEARCH_ENGINE=opensearch
 
 # Image Storage

ASYNC_IMAGE_PROCESSING.md

@@ -0,0 +1,220 @@
+# Async Image Processing Implementation
+
+## Overview
+
+The image processing system has been updated to handle external images asynchronously, preventing timeouts when processing stories with many images. This provides real-time progress updates to users showing which images are being processed.
+
+## Backend Components
+
+### 1. `ImageProcessingProgressService`
+- Tracks progress for individual story image processing sessions
+- Thread-safe with `ConcurrentHashMap` for multi-user support
+- Provides progress information: total images, processed count, current image, status, errors
+
+### 2. `AsyncImageProcessingService`
+- Handles asynchronous image processing using Spring's `@Async` annotation
+- Counts external images before processing
+- Provides progress callbacks during processing
+- Updates story content when processing completes
+- Automatic cleanup of progress data after completion
+
+### 3. Enhanced `ImageService`
+- Added `processContentImagesWithProgress()` method with callback support
+- Progress callbacks provide real-time updates during image download/processing
+- Maintains compatibility with existing synchronous processing
+
+### 4. Updated `StoryController`
+- `POST /api/stories` and `PUT /api/stories/{id}` now trigger async image processing
+- `GET /api/stories/{id}/image-processing-progress` endpoint for progress polling
+- Processing starts immediately after story save and returns control to user
+
+## Frontend Components
+
+### 1. `ImageProcessingProgressTracker` (Utility Class)
+```typescript
+const tracker = new ImageProcessingProgressTracker(storyId);
+tracker.onProgress((progress) => {
+  console.log(`Processing ${progress.processedImages}/${progress.totalImages}`);
+});
+tracker.onComplete(() => console.log('Done!'));
+tracker.start();
+```
+
+### 2. `ImageProcessingProgressComponent` (React Component)
+```tsx
+<ImageProcessingProgressComponent
+  storyId={storyId}
+  autoStart={true}
+  onComplete={() => refreshStory()}
+/>
+```
+
+## User Experience
+
+### Before (Synchronous)
+1. User saves story with external images
+2. Request hangs for 30+ seconds processing images
+3. Browser may timeout
+4. No feedback about progress
+5. User doesn't know if it's working
+
+### After (Asynchronous)
+1. User saves story with external images
+2. Save completes immediately
+3. Progress indicator appears: "Processing 5 images. Currently image 2 of 5..."
+4. User can continue using the application
+5. Progress updates every second
+6. Story automatically refreshes when processing completes
+
+## API Endpoints
+
+### Progress Endpoint
+```
+GET /api/stories/{id}/image-processing-progress
+```
+
+**Response when processing:**
+```json
+{
+  "isProcessing": true,
+  "totalImages": 5,
+  "processedImages": 2,
+  "currentImageUrl": "https://example.com/image.jpg",
+  "status": "Processing image 3 of 5",
+  "progressPercentage": 40.0,
+  "completed": false,
+  "error": ""
+}
+```
+
+**Response when completed:**
+```json
+{
+  "isProcessing": false,
+  "totalImages": 5,
+  "processedImages": 5,
+  "currentImageUrl": "",
+  "status": "Completed: 5 images processed",
+  "progressPercentage": 100.0,
+  "completed": true,
+  "error": ""
+}
+```
+
+**Response when no processing:**
+```json
+{
+  "isProcessing": false,
+  "message": "No active image processing"
+}
+```
+
+## Integration Examples
+
+### React Hook Usage
+```tsx
+import { useImageProcessingProgress } from '../utils/imageProcessingProgress';
+
+function StoryEditor({ storyId }) {
+  const { progress, isTracking, startTracking } = useImageProcessingProgress(storyId);
+
+  const handleSave = async () => {
+    await saveStory();
+    startTracking(); // Start monitoring progress
+  };
+
+  return (
+    <div>
+      {isTracking && progress && (
+        <div className="progress-indicator">
+          Processing {progress.processedImages}/{progress.totalImages} images...
+        </div>
+      )}
+      <button onClick={handleSave}>Save Story</button>
+    </div>
+  );
+}
+```
+
+### Manual Progress Tracking
+```typescript
+// After saving a story with external images
+const tracker = new ImageProcessingProgressTracker(storyId);
+
+tracker.onProgress((progress) => {
+  updateProgressBar(progress.progressPercentage);
+  showStatus(progress.status);
+  if (progress.currentImageUrl) {
+    showCurrentImage(progress.currentImageUrl);
+  }
+});
+
+tracker.onComplete((finalProgress) => {
+  hideProgressBar();
+  showNotification('Image processing completed!');
+  refreshStoryContent(); // Reload story with processed images
+});
+
+tracker.onError((error) => {
+  hideProgressBar();
+  showError(`Image processing failed: ${error}`);
+});
+
+tracker.start();
+```
+
+## Configuration
+
+### Polling Interval
+Default: 1 second (1000ms)
+```typescript
+const tracker = new ImageProcessingProgressTracker(storyId, 500); // Poll every 500ms
+```
+
+### Timeout
+Default: 5 minutes (300000ms)
+```typescript
+const tracker = new ImageProcessingProgressTracker(storyId, 1000, 600000); // 10 minute timeout
+```
+
+### Spring Async Configuration
+The backend uses Spring's default async executor. For production, consider configuring a custom thread pool in your application properties:
+
+```yaml
+spring:
+  task:
+    execution:
+      pool:
+        core-size: 4
+        max-size: 8
+        queue-capacity: 100
+```
+
+## Error Handling
+
+### Backend Errors
+- Network timeouts downloading images
+- Invalid image formats
+- Disk space issues
+- All errors are logged and returned in progress status
+
+### Frontend Errors
+- Network failures during progress polling
+- Timeout if processing takes too long
+- Graceful degradation - user can continue working
+
+## Benefits
+
+1. **No More Timeouts**: Large image processing operations won't timeout HTTP requests
+2. **Better UX**: Users get real-time feedback about processing progress
+3. **Improved Performance**: Users can continue using the app while images process
+4. **Error Visibility**: Clear error messages when image processing fails
+5. **Scalability**: Multiple users can process images simultaneously without blocking
+
+## Future Enhancements
+
+1. **WebSocket Support**: Replace polling with WebSocket for real-time push updates
+2. **Batch Processing**: Queue multiple stories for batch image processing
+3. **Retry Logic**: Automatic retry for failed image downloads
+4. **Progress Persistence**: Save progress to database for recovery after server restart
+5. **Image Optimization**: Automatic resize/compress images during processing

DEPLOYMENT.md

@@ -0,0 +1,137 @@
+# StoryCove Deployment Guide
+
+## Quick Deployment
+
+StoryCove includes an automated deployment script that handles Solr volume cleanup and ensures fresh search indices on every deployment.
+
+### Using the Deployment Script
+
+```bash
+./deploy.sh
+```
+
+This script will:
+1. Stop all running containers
+2. **Remove the Solr data volume** (forcing fresh core creation)
+3. Build and start all containers
+4. Wait for services to become healthy
+5. Trigger automatic bulk reindexing
+
+### What Happens During Deployment
+
+#### 1. Solr Volume Cleanup
+The script removes the `storycove_solr_data` volume, which:
+- Ensures all Solr cores are recreated from scratch
+- Prevents stale configuration issues
+- Guarantees schema changes are applied
+
+#### 2. Automatic Bulk Reindexing
+When the backend starts, it automatically:
+- Detects that Solr is available
+- Fetches all entities from the database (Stories, Authors, Collections)
+- Bulk indexes them into Solr
+- Logs progress and completion
+
+### Monitoring the Deployment
+
+Watch the backend logs to see reindexing progress:
+```bash
+docker-compose logs -f backend
+```
+
+You should see output like:
+```
+========================================
+Starting automatic bulk reindexing...
+========================================
+📚 Indexing stories...
+✅ Indexed 150 stories
+👤 Indexing authors...
+✅ Indexed 45 authors
+📂 Indexing collections...
+✅ Indexed 12 collections
+========================================
+✅ Bulk reindexing completed successfully in 2345ms
+📊 Total indexed: 150 stories, 45 authors, 12 collections
+========================================
+```
+
+## Manual Deployment (Without Script)
+
+If you prefer manual control:
+
+```bash
+# Stop containers
+docker-compose down
+
+# Remove Solr volume
+docker volume rm storycove_solr_data
+
+# Start containers
+docker-compose up -d --build
+```
+
+The automatic reindexing will still occur on startup.
+
+## Troubleshooting
+
+### Reindexing Fails
+
+If bulk reindexing fails:
+1. Check Solr is running: `docker-compose logs solr`
+2. Verify Solr health: `curl http://localhost:8983/solr/admin/ping`
+3. Check backend logs: `docker-compose logs backend`
+
+The application will still start even if reindexing fails - you can manually trigger reindexing through the admin API.
+
+### Solr Cores Not Created
+
+If Solr cores aren't being created properly:
+1. Check the `solr.Dockerfile` to ensure cores are created
+2. Verify the Solr image builds correctly: `docker-compose build solr`
+3. Check Solr Admin UI: http://localhost:8983
+
+### Performance Issues
+
+If reindexing takes too long:
+- The bulk indexing is already optimized (batch operations)
+- Consider increasing Solr memory in `docker-compose.yml`:
+  ```yaml
+  environment:
+    - SOLR_HEAP=1024m
+  ```
+
+## Development Workflow
+
+### Daily Development
+Just use the normal commands:
+```bash
+docker-compose up -d
+```
+
+The automatic reindexing still happens, but it's fast on small datasets.
+
+### Schema Changes
+When you modify Solr schema or add new cores:
+```bash
+./deploy.sh
+```
+
+This ensures a clean slate.
+
+### Skipping Reindexing
+
+Reindexing is automatic and cannot be disabled. It's designed to be fast and unobtrusive. The application starts immediately - reindexing happens in the background.
+
+## Environment Variables
+
+No additional environment variables are needed for the deployment script. All configuration is in `docker-compose.yml`.
+
+## Backup Considerations
+
+**Important**: Since the Solr volume is recreated on every deployment, you should:
+- Never rely on Solr as the source of truth
+- Always maintain data in PostgreSQL
+- Solr is treated as a disposable cache/index
+
+This is the recommended approach for search indices.

HOUSEKEEPING_COMPLETE_REPORT.md

@@ -0,0 +1,539 @@
+# StoryCove Housekeeping Complete Report
+**Date:** 2025-10-10
+**Scope:** Comprehensive audit of backend, frontend, tests, and documentation
+**Overall Grade:** A- (90%)
+
+---
+
+## Executive Summary
+
+StoryCove is a **production-ready** self-hosted short story library application with **excellent architecture** and **comprehensive feature implementation**. The codebase demonstrates professional-grade engineering with only one critical issue blocking 100% compliance.
+
+### Key Highlights ✅
+- ✅ **Entity layer:** 100% specification compliant
+- ✅ **EPUB Import/Export:** Phase 2 fully implemented
+- ✅ **Tag Enhancement:** Aliases, merging, AI suggestions complete
+- ✅ **Multi-Library Support:** Robust isolation with security
+- ✅ **HTML Sanitization:** Shared backend/frontend config with DOMPurify
+- ✅ **Advanced Search:** 15+ filter parameters, Solr integration
+- ✅ **Reading Experience:** Progress tracking, TOC, series navigation
+
+### Critical Issue 🚨
+1. **Collections Search Not Implemented** (CollectionService.java:56-61)
+   - GET /api/collections returns empty results
+   - Requires Solr Collections core implementation
+   - Estimated: 4-6 hours to fix
+
+---
+
+## Phase 1: Documentation & State Assessment (COMPLETED)
+
+### Entity Models - Grade: A+ (100%)
+
+All 7 entity models are **specification-perfect**:
+
+| Entity | Spec Compliance | Key Features | Status |
+|--------|----------------|--------------|--------|
+| **Story** | 100% | All 14 fields, reading progress, series support | ✅ Perfect |
+| **Author** | 100% | Rating, avatar, URL collections | ✅ Perfect |
+| **Tag** | 100% | Color (7-char hex), description (500 chars), aliases | ✅ Perfect |
+| **Collection** | 100% | Gap-based positioning, calculated properties | ✅ Perfect |
+| **Series** | 100% | Name, description, stories relationship | ✅ Perfect |
+| **ReadingPosition** | 100% | EPUB CFI, context, percentage tracking | ✅ Perfect |
+| **TagAlias** | 100% | Alias resolution, merge tracking | ✅ Perfect |
+
+**Verification:**
+- `Story.java:1-343`: All fields match DATA_MODEL.md
+- `Collection.java:1-245`: Helper methods for story management
+- `ReadingPosition.java:1-230`: Complete EPUB CFI support
+- `TagAlias.java:1-113`: Proper canonical tag resolution
+
+### Repository Layer - Grade: A+ (100%)
+
+**Best Practices Verified:**
+- ✅ No search anti-patterns (CollectionRepository correctly delegates to search service)
+- ✅ Proper use of `@Query` annotations for complex operations
+- ✅ Efficient eager loading with JOIN FETCH
+- ✅ Return types: Page<T> for pagination, List<T> for unbounded
+
+**Files Audited:**
+- `CollectionRepository.java:1-55` - ID-based lookups only
+- `StoryRepository.java` - Complex queries with associations
+- `AuthorRepository.java` - Join fetch for stories
+- `TagRepository.java` - Alias-aware queries
+
+---
+
+## Phase 2: Backend Implementation Audit (COMPLETED)
+
+### Service Layer - Grade: A (95%)
+
+#### Core Services ✅
+
+**StoryService.java** (794 lines)
+- ✅ CRUD with search integration
+- ✅ HTML sanitization on create/update (line 490, 528-532)
+- ✅ Reading progress management
+- ✅ Tag alias resolution
+- ✅ Random story with 15+ filters
+
+**AuthorService.java** (317 lines)
+- ✅ Avatar management
+- ✅ Rating validation (1-5 range)
+- ✅ Search index synchronization
+- ✅ URL management
+
+**TagService.java** (491 lines)
+- ✅ **Tag Enhancement spec 100% complete**
+- ✅ Alias system: addAlias(), removeAlias(), resolveTagByName()
+- ✅ Tag merging with atomic operations
+- ✅ AI tag suggestions with confidence scoring
+- ✅ Merge preview functionality
+
+**CollectionService.java** (452 lines)
+- ⚠️ **CRITICAL ISSUE at lines 56-61:**
+```java
+public SearchResultDto<Collection> searchCollections(...) {
+    logger.warn("Collections search not yet implemented in Solr, returning empty results");
+    return new SearchResultDto<>(new ArrayList<>(), 0, page, limit, query != null ? query : "", 0);
+}
+```
+- ✅ All other CRUD operations work correctly
+- ✅ Gap-based positioning for story reordering
+
+#### EPUB Services ✅
+
+**EPUBImportService.java** (551 lines)
+- ✅ Metadata extraction (title, author, description, tags)
+- ✅ Cover image extraction and processing
+- ✅ Content image download and replacement
+- ✅ Reading position preservation
+- ✅ Author/series auto-creation
+
+**EPUBExportService.java** (584 lines)
+- ✅ Single story export
+- ✅ Collection export (multi-story)
+- ✅ Chapter splitting by word count or HTML headings
+- ✅ Custom metadata and title support
+- ✅ XHTML compliance (fixHtmlForXhtml method)
+- ✅ Reading position inclusion
+
+#### Advanced Services ✅
+
+**HtmlSanitizationService.java** (222 lines)
+- ✅ Jsoup Safelist configuration
+- ✅ Loads config from `html-sanitization-config.json`
+- ✅ Figure tag preprocessing (lines 143-184)
+- ✅ Relative URL preservation (line 89)
+- ✅ Shared with frontend via `/api/config/html-sanitization`
+
+**ImageService.java** (1122 lines)
+- ✅ Three image types: COVER, AVATAR, CONTENT
+- ✅ Content image processing with download
+- ✅ Orphaned image cleanup
+- ✅ Library-aware paths
+- ✅ Async processing support
+
+**LibraryService.java** (830 lines)
+- ✅ Multi-library isolation
+- ✅ **Explicit authentication required** (lines 104-114)
+- ✅ Automatic schema creation for new libraries
+- ✅ Smart database routing (SmartRoutingDataSource)
+- ✅ Async Solr reindexing on library switch (lines 164-193)
+- ✅ BCrypt password encryption
+
+**DatabaseManagementService.java** (1206 lines)
+- ✅ ZIP-based complete backup with pg_dump
+- ✅ Restore with schema creation
+- ✅ Manual reindexing from database (lines 1047-1097)
+- ✅ Security: ZIP path validation
+
+**SearchServiceAdapter.java** (287 lines)
+- ✅ Unified search interface
+- ✅ Delegates to SolrService
+- ✅ Bulk indexing operations
+- ✅ Tag suggestions
+
+**SolrService.java** (1115 lines)
+- ✅ Two cores: stories and authors
+- ✅ Advanced filtering with 20+ parameters
+- ✅ Library-aware filtering
+- ✅ Faceting support
+- ⚠️ **No Collections core** (known issue)
+
+### Controller Layer - Grade: A (95%)
+
+**StoryController.java** (1000+ lines)
+- ✅ Comprehensive REST API
+- ✅ CRUD operations
+- ✅ EPUB import/export endpoints
+- ✅ Async content image processing with progress
+- ✅ Duplicate detection
+- ✅ Advanced search with 15+ filters
+- ✅ Random story endpoint
+- ✅ Reading progress tracking
+
+**CollectionController.java** (538 lines)
+- ✅ Full CRUD operations
+- ✅ Cover image upload/removal
+- ✅ Story reordering
+- ✅ EPUB collection export
+- ⚠️ Search returns empty (known issue)
+- ✅ Lightweight DTOs to avoid circular references
+
+**SearchController.java** (57 lines)
+- ✅ Reindex endpoint
+- ✅ Health check
+- ⚠️ Minimal implementation (search is in StoryController)
+
+---
+
+## Phase 3: Frontend Implementation Audit (COMPLETED)
+
+### API Client Layer - Grade: A+ (100%)
+
+**api.ts** (994 lines)
+- ✅ Axios instance with interceptors
+- ✅ JWT token management (localStorage + httpOnly cookies)
+- ✅ Auto-redirect on 401/403
+- ✅ Comprehensive endpoints for all resources
+- ✅ Tag alias resolution in search (lines 576-585)
+- ✅ Advanced filter parameters (15+ filters)
+- ✅ Random story with Solr RandomSortField (lines 199-307)
+- ✅ Library-aware image URLs (lines 983-994)
+
+**Endpoints Coverage:**
+- ✅ Stories: CRUD, search, random, EPUB import/export, duplicate check
+- ✅ Authors: CRUD, avatar, search
+- ✅ Tags: CRUD, aliases, merge, suggestions, autocomplete
+- ✅ Collections: CRUD, search, cover, reorder, EPUB export
+- ✅ Series: CRUD, search
+- ✅ Database: backup/restore (both SQL and complete)
+- ✅ Config: HTML sanitization, image cleanup
+- ✅ Search Admin: engine switching, reindex, library migration
+
+### HTML Sanitization - Grade: A+ (100%)
+
+**sanitization.ts** (368 lines)
+- ✅ **Shared configuration with backend** via `/api/config/html-sanitization`
+- ✅ DOMPurify with custom configuration
+- ✅ CSS property filtering (lines 20-47)
+- ✅ Figure tag preprocessing (lines 187-251) - **matches backend**
+- ✅ Async `sanitizeHtml()` and sync `sanitizeHtmlSync()`
+- ✅ Fallback configuration if backend unavailable
+- ✅ Config caching for performance
+
+**Security Features:**
+- ✅ Allowlist-based tag filtering
+- ✅ CSS property whitelist
+- ✅ URL protocol validation
+- ✅ Relative URL preservation for local images
+
+### Pages & Components - Grade: A (95%)
+
+#### Library Page (LibraryContent.tsx - 341 lines)
+- ✅ Advanced search with debouncing
+- ✅ Tag facet enrichment with full tag data
+- ✅ URL parameter handling for filters
+- ✅ Three layout modes: sidebar, toolbar, minimal
+- ✅ Advanced filters integration
+- ✅ Random story with all filters applied
+- ✅ Pagination
+
+#### Collections Page (page.tsx - 300 lines)
+- ✅ Search with tag filtering
+- ✅ Archive toggle
+- ✅ Grid/list view modes
+- ✅ Pagination
+- ⚠️ **Search returns empty results** (backend issue)
+
+#### Story Reading Page (stories/[id]/page.tsx - 669 lines)
+- ✅ **Sophisticated reading experience:**
+  - Reading progress bar with percentage
+  - Auto-scroll to saved position
+  - Debounced position saving (2 second delay)
+  - Character position tracking
+  - End-of-story detection with reset option
+- ✅ **Table of Contents:**
+  - Auto-generated from headings
+  - Modal overlay
+  - Smooth scroll navigation
+- ✅ **Series Navigation:**
+  - Previous/Next story links
+  - Inline metadata display
+- ✅ **Memoized content rendering** to prevent re-sanitization on scroll
+- ✅ Preloaded sanitization config
+
+#### Settings Page (SettingsContent.tsx - 183 lines)
+- ✅ Three tabs: Appearance, Content, System
+- ✅ Theme switching (light/dark)
+- ✅ Font customization (serif, sans, mono)
+- ✅ Font size control
+- ✅ Reading width preferences
+- ✅ Reading speed configuration
+- ✅ localStorage persistence
+
+#### Slate Editor (SlateEditor.tsx - 942 lines)
+- ✅ **Rich text editing with Slate.js**
+- ✅ **Advanced image handling:**
+  - Image paste with src preservation
+  - Interactive image elements with edit/delete
+  - Image error handling with fallback
+  - External image indicators
+- ✅ **Formatting:**
+  - Headings (H1, H2, H3)
+  - Text formatting (bold, italic, underline, strikethrough)
+  - Keyboard shortcuts (Ctrl+B, Ctrl+I, etc.)
+- ✅ **HTML conversion:**
+  - Bidirectional HTML ↔ Slate conversion
+  - Mixed content support (text + images)
+  - Figure tag preprocessing
+  - Sanitization integration
+
+---
+
+## Phase 4: Test Coverage Assessment (COMPLETED)
+
+### Current Test Files (9 total):
+
+**Entity Tests (5):**
+- ✅ `StoryTest.java` - Story entity validation
+- ✅ `AuthorTest.java` - Author entity validation
+- ✅ `TagTest.java` - Tag entity validation
+- ✅ `SeriesTest.java` - Series entity validation
+- ❌ Missing: CollectionTest, ReadingPositionTest, TagAliasTest
+
+**Repository Tests (3):**
+- ✅ `StoryRepositoryTest.java` - Story persistence
+- ✅ `AuthorRepositoryTest.java` - Author persistence
+- ✅ `BaseRepositoryTest.java` - Base test configuration
+- ❌ Missing: TagRepository, SeriesRepository, CollectionRepository, ReadingPositionRepository
+
+**Service Tests (2):**
+- ✅ `StoryServiceTest.java` - Story business logic
+- ✅ `AuthorServiceTest.java` - Author business logic
+- ❌ Missing: TagService, CollectionService, EPUBImportService, EPUBExportService, HtmlSanitizationService, ImageService, LibraryService, DatabaseManagementService, SeriesService, SearchServiceAdapter, SolrService
+
+**Controller Tests:** ❌ None
+**Frontend Tests:** ❌ None
+
+### Test Coverage Estimate: ~25%
+
+**Missing HIGH Priority Tests:**
+1. CollectionServiceTest - Collections CRUD and search
+2. TagServiceTest - Alias, merge, AI suggestions
+3. EPUBImportServiceTest - Import logic verification
+4. EPUBExportServiceTest - Export format validation
+5. HtmlSanitizationServiceTest - **Security critical**
+6. ImageServiceTest - Image processing and download
+
+**Missing MEDIUM Priority:**
+- SeriesServiceTest
+- LibraryServiceTest
+- DatabaseManagementServiceTest
+- SearchServiceAdapter/SolrServiceTest
+- All controller tests
+- All frontend component tests
+
+**Recommended Action:**
+Create comprehensive test suite with target coverage of 80%+ for services, 70%+ for controllers.
+
+---
+
+## Phase 5: Documentation Review
+
+### Specification Documents ✅
+
+| Document | Status | Notes |
+|----------|--------|-------|
+| storycove-spec.md | ✅ Current | Core specification |
+| DATA_MODEL.md | ✅ Current | 100% implemented |
+| API.md | ⚠️ Needs minor updates | Missing some advanced filter docs |
+| TAG_ENHANCEMENT_SPECIFICATION.md | ✅ Current | 100% implemented |
+| EPUB_IMPORT_EXPORT_SPECIFICATION.md | ✅ Current | Phase 2 complete |
+| storycove-collections-spec.md | ⚠️ Known issue | Search not implemented |
+
+### Implementation Reports ✅
+
+- ✅ `HOUSEKEEPING_PHASE1_REPORT.md` - Detailed assessment
+- ✅ `HOUSEKEEPING_COMPLETE_REPORT.md` - This document
+
+### Recommendations:
+
+1. **Update API.md** to document:
+   - Advanced search filters (15+ parameters)
+   - Random story endpoint with filter support
+   - EPUB import/export endpoints
+   - Image processing endpoints
+
+2. **Add MULTI_LIBRARY_SPEC.md** documenting:
+   - Library isolation architecture
+   - Authentication flow
+   - Database routing
+   - Search index separation
+
+---
+
+## Critical Findings Summary
+
+### 🚨 CRITICAL (Must Fix)
+
+1. **Collections Search Not Implemented**
+   - **Location:** `CollectionService.java:56-61`
+   - **Impact:** GET /api/collections always returns empty results
+   - **Specification:** storycove-collections-spec.md lines 52-61 mandates Solr search
+   - **Estimated Fix:** 4-6 hours
+   - **Steps:**
+     1. Create Solr Collections core with schema
+     2. Implement indexing in SearchServiceAdapter
+     3. Wire up CollectionService.searchCollections()
+     4. Test pagination and filtering
+
+### ⚠️ HIGH Priority (Recommended)
+
+2. **Missing Test Coverage** (~25% vs target 80%)
+   - HtmlSanitizationServiceTest - security critical
+   - CollectionServiceTest - feature verification
+   - TagServiceTest - complex logic (aliases, merge)
+   - EPUBImportServiceTest, EPUBExportServiceTest - file processing
+
+3. **API Documentation Updates**
+   - Advanced filters not fully documented
+   - EPUB endpoints missing from API.md
+
+### 📋 MEDIUM Priority (Optional)
+
+4. **SearchController Minimal**
+   - Only has reindex and health check
+   - Actual search in StoryController
+
+5. **Frontend Test Coverage**
+   - No component tests
+   - No integration tests
+   - Recommend: Jest + React Testing Library
+
+---
+
+## Strengths & Best Practices 🌟
+
+### Architecture Excellence
+1. **Multi-Library Support**
+   - Complete isolation with separate databases
+   - Explicit authentication required
+   - Smart routing with automatic reindexing
+   - Library-aware image paths
+
+2. **Security-First Design**
+   - HTML sanitization with shared backend/frontend config
+   - JWT authentication with httpOnly cookies
+   - BCrypt password encryption
+   - Input validation throughout
+
+3. **Production-Ready Features**
+   - Complete backup/restore system (pg_dump/psql)
+   - Orphaned image cleanup
+   - Async image processing with progress tracking
+   - Reading position tracking with EPUB CFI
+
+### Code Quality
+1. **Proper Separation of Concerns**
+   - Repository anti-patterns avoided
+   - Service layer handles business logic
+   - Controllers are thin and focused
+   - DTOs prevent circular references
+
+2. **Error Handling**
+   - Custom exceptions (ResourceNotFoundException, DuplicateResourceException)
+   - Proper HTTP status codes
+   - Fallback configurations
+
+3. **Performance Optimizations**
+   - Eager loading with JOIN FETCH
+   - Memoized React components
+   - Debounced search and autosave
+   - Config caching
+
+---
+
+## Compliance Matrix
+
+| Feature Area | Spec Compliance | Implementation Quality | Notes |
+|-------------|----------------|----------------------|-------|
+| **Entity Models** | 100% | A+ | Perfect spec match |
+| **Database Layer** | 100% | A+ | Best practices followed |
+| **EPUB Import/Export** | 100% | A | Phase 2 complete |
+| **Tag Enhancement** | 100% | A | Aliases, merge, AI complete |
+| **Collections** | 80% | B | Search not implemented |
+| **HTML Sanitization** | 100% | A+ | Shared config, security-first |
+| **Search** | 95% | A | Missing Collections core |
+| **Multi-Library** | 100% | A | Robust isolation |
+| **Reading Experience** | 100% | A+ | Sophisticated tracking |
+| **Image Processing** | 100% | A | Download, async, cleanup |
+| **Test Coverage** | 25% | C | Needs significant work |
+| **Documentation** | 90% | B+ | Minor updates needed |
+
+---
+
+## Recommendations by Priority
+
+### Immediate (This Sprint)
+1. ✅ **Fix Collections Search** (4-6 hours)
+   - Implement Solr Collections core
+   - Wire up searchCollections()
+   - Test thoroughly
+
+### Short-Term (Next Sprint)
+2. ✅ **Create Critical Tests** (10-12 hours)
+   - HtmlSanitizationServiceTest
+   - CollectionServiceTest
+   - TagServiceTest
+   - EPUBImportServiceTest
+   - EPUBExportServiceTest
+
+3. ✅ **Update API Documentation** (2-3 hours)
+   - Document advanced filters
+   - Add EPUB endpoints
+   - Update examples
+
+### Medium-Term (Next Month)
+4. ✅ **Expand Test Coverage to 80%** (20-25 hours)
+   - ImageServiceTest
+   - LibraryServiceTest
+   - DatabaseManagementServiceTest
+   - Controller tests
+   - Frontend component tests
+
+5. ✅ **Create Multi-Library Spec** (3-4 hours)
+   - Document architecture
+   - Authentication flow
+   - Database routing
+   - Migration guide
+
+---
+
+## Conclusion
+
+StoryCove is a **well-architected, production-ready application** with only one critical blocker (Collections search). The codebase demonstrates:
+
+- ✅ **Excellent architecture** with proper separation of concerns
+- ✅ **Security-first** approach with HTML sanitization and authentication
+- ✅ **Production features** like backup/restore, multi-library, async processing
+- ✅ **Sophisticated UX** with reading progress, TOC, series navigation
+- ⚠️ **Test coverage gap** that should be addressed
+
+### Final Grade: A- (90%)
+
+**Breakdown:**
+- Backend Implementation: A (95%)
+- Frontend Implementation: A (95%)
+- Test Coverage: C (25%)
+- Documentation: B+ (90%)
+- Overall Architecture: A+ (100%)
+
+**Primary Blocker:** Collections search (6 hours to fix)
+**Recommended Focus:** Test coverage (target 80%)
+
+---
+
+*Report Generated: 2025-10-10*
+*Next Review: After Collections search implementation*

HOUSEKEEPING_PHASE1_REPORT.md

@@ -0,0 +1,526 @@
+# StoryCove Housekeeping Report - Phase 1: Documentation & State Assessment
+**Date**: 2025-01-10
+**Completed By**: Claude Code (Housekeeping Analysis)
+
+## Executive Summary
+
+Phase 1 assessment has been completed, providing a comprehensive review of the StoryCove application's current implementation status against specifications. The application is **well-implemented** with most core features working, but there is **1 CRITICAL ISSUE** and several areas requiring attention.
+
+### Critical Finding
+🚨 **Collections Search Not Implemented**: The Collections feature does not use Typesense/Solr for search as mandated by the specification. This is a critical architectural requirement that must be addressed.
+
+### Overall Status
+- **Backend Implementation**: ~85% complete with specification
+- **Entity Models**: ✅ 100% compliant with DATA_MODEL.md
+- **Test Coverage**: ⚠️ 9 tests exist, but many critical services lack tests
+- **Documentation**: ✅ Comprehensive and up-to-date
+
+---
+
+## 1. Implementation Status Matrix
+
+### 1.1 Entity Layer (✅ FULLY COMPLIANT)
+
+| Entity | Specification | Implementation Status | Notes |
+|--------|---------------|----------------------|-------|
+| **Story** | storycove-spec.md | ✅ Complete | All fields match spec including reading position, isRead, lastReadAt |
+| **Author** | storycove-spec.md | ✅ Complete | Includes avatar_image_path, rating, URLs as @ElementCollection |
+| **Tag** | TAG_ENHANCEMENT_SPECIFICATION.md | ✅ Complete | Includes color, description, aliases relationship |
+| **TagAlias** | TAG_ENHANCEMENT_SPECIFICATION.md | ✅ Complete | Implements alias system with createdFromMerge flag |
+| **Series** | storycove-spec.md | ✅ Complete | Basic implementation as specified |
+| **Collection** | storycove-collections-spec.md | ✅ Complete | All fields including isArchived, gap-based positioning |
+| **CollectionStory** | storycove-collections-spec.md | ✅ Complete | Junction entity with position field |
+| **ReadingPosition** | EPUB_IMPORT_EXPORT_SPECIFICATION.md | ✅ Complete | Full EPUB CFI support, chapter tracking, percentage complete |
+| **Library** | (Multi-library support) | ✅ Complete | Implemented for multi-library feature |
+
+**Assessment**: Entity layer is **100% specification-compliant** ✅
+
+---
+
+### 1.2 Repository Layer (⚠️ MOSTLY COMPLIANT)
+
+| Repository | Specification Compliance | Issues |
+|------------|-------------------------|--------|
+| **CollectionRepository** | ⚠️ Partial | Contains only ID-based lookups (correct), has note about Typesense |
+| **TagRepository** | ✅ Complete | Proper query methods, no search anti-patterns |
+| **StoryRepository** | ✅ Complete | Appropriate methods |
+| **AuthorRepository** | ✅ Complete | Appropriate methods |
+| **SeriesRepository** | ✅ Complete | Basic CRUD |
+| **ReadingPositionRepository** | ✅ Complete | Story-based lookups |
+| **TagAliasRepository** | ✅ Complete | Name-based lookups for resolution |
+
+**Key Finding**: CollectionRepository correctly avoids search/filter methods (good architectural design), but the corresponding search implementation in CollectionService is not yet complete.
+
+---
+
+### 1.3 Service Layer (🚨 CRITICAL ISSUE FOUND)
+
+| Service | Status | Specification Match | Critical Issues |
+|---------|--------|---------------------|-----------------|
+| **CollectionService** | 🚨 **INCOMPLETE** | 20% | **Collections search returns empty results** (line 56-61) |
+| **TagService** | ✅ Complete | 100% | Full alias, merging, AI suggestions implemented |
+| **StoryService** | ✅ Complete | 95% | Core features complete |
+| **AuthorService** | ✅ Complete | 95% | Core features complete |
+| **EPUBImportService** | ✅ Complete | 100% | Phase 1 & 2 complete per spec |
+| **EPUBExportService** | ✅ Complete | 100% | Single story & collection export working |
+| **ImageService** | ✅ Complete | 90% | Upload, resize, delete implemented |
+| **HtmlSanitizationService** | ✅ Complete | 100% | Security-critical, appears complete |
+| **SearchServiceAdapter** | ⚠️ Partial | 70% | Solr integration present but Collections not indexed |
+| **ReadingTimeService** | ✅ Complete | 100% | Word count calculations |
+
+#### 🚨 CRITICAL ISSUE Detail: CollectionService.searchCollections()
+
+**File**: `backend/src/main/java/com/storycove/service/CollectionService.java:56-61`
+
+```java
+public SearchResultDto<Collection> searchCollections(String query, List<String> tags, boolean includeArchived, int page, int limit) {
+    // Collections are currently handled at database level, not indexed in search engine
+    // Return empty result for now as collections search is not implemented in Solr
+    logger.warn("Collections search not yet implemented in Solr, returning empty results");
+    return new SearchResultDto<>(new ArrayList<>(), 0, page, limit, query != null ? query : "", 0);
+}
+```
+
+**Impact**:
+- GET /api/collections endpoint always returns 0 results
+- Frontend collections list view will appear empty
+- Violates architectural requirement in storycove-collections-spec.md Section 4.2 and 5.2
+
+**Specification Requirement** (storycove-collections-spec.md:52-61):
+> **IMPORTANT**: This endpoint MUST use Typesense for all search and filtering operations.
+> Do NOT implement search/filter logic using JPA/SQL queries.
+
+---
+
+### 1.4 Controller/API Layer (✅ MOSTLY COMPLIANT)
+
+| Controller | Endpoints | Status | Notes |
+|------------|-----------|--------|-------|
+| **CollectionController** | 13 endpoints | ⚠️ 90% | All endpoints implemented but search returns empty |
+| **StoryController** | ~15 endpoints | ✅ Complete | CRUD, reading progress, EPUB export |
+| **AuthorController** | ~10 endpoints | ✅ Complete | CRUD, avatar management |
+| **TagController** | ~12 endpoints | ✅ Complete | Enhanced features: aliases, merging, suggestions |
+| **SeriesController** | ~6 endpoints | ✅ Complete | Basic CRUD |
+| **AuthController** | 3 endpoints | ✅ Complete | Login, logout, verify |
+| **FileController** | 4 endpoints | ✅ Complete | Image serving and uploads |
+| **SearchController** | 3 endpoints | ✅ Complete | Story/Author search via Solr |
+
+#### Endpoint Verification vs API.md
+
+**Collections Endpoints (storycove-collections-spec.md)**:
+- ✅ GET /api/collections - Implemented (but returns empty due to search issue)
+- ✅ GET /api/collections/{id} - Implemented
+- ✅ POST /api/collections - Implemented (JSON & multipart)
+- ✅ PUT /api/collections/{id} - Implemented
+- ✅ DELETE /api/collections/{id} - Implemented
+- ✅ PUT /api/collections/{id}/archive - Implemented
+- ✅ POST /api/collections/{id}/stories - Implemented
+- ✅ DELETE /api/collections/{id}/stories/{storyId} - Implemented
+- ✅ PUT /api/collections/{id}/stories/order - Implemented
+- ✅ GET /api/collections/{id}/read/{storyId} - Implemented
+- ✅ GET /api/collections/{id}/stats - Implemented
+- ✅ GET /api/collections/{id}/epub - Implemented
+- ✅ POST /api/collections/{id}/epub - Implemented
+
+**Tag Enhancement Endpoints (TAG_ENHANCEMENT_SPECIFICATION.md)**:
+- ✅ POST /api/tags/{tagId}/aliases - Implemented
+- ✅ DELETE /api/tags/{tagId}/aliases/{aliasId} - Implemented
+- ✅ POST /api/tags/merge - Implemented
+- ✅ POST /api/tags/merge/preview - Implemented
+- ✅ POST /api/tags/suggest - Implemented (AI-powered)
+- ✅ GET /api/tags/resolve/{name} - Implemented
+
+---
+
+### 1.5 Advanced Features Status
+
+#### ✅ Tag Enhancement System (COMPLETE)
+**Specification**: TAG_ENHANCEMENT_SPECIFICATION.md (Status: ✅ COMPLETED)
+
+| Feature | Status | Implementation |
+|---------|--------|----------------|
+| Color Tags | ✅ Complete | Tag entity has `color` field (VARCHAR(7) hex) |
+| Tag Descriptions | ✅ Complete | Tag entity has `description` field (VARCHAR(500)) |
+| Tag Aliases | ✅ Complete | TagAlias entity, resolution logic in TagService |
+| Tag Merging | ✅ Complete | Atomic merge with automatic alias creation |
+| AI Tag Suggestions | ✅ Complete | TagService.suggestTags() with confidence scoring |
+| Alias Resolution | ✅ Complete | TagService.resolveTagByName() checks both tags and aliases |
+
+**Code Evidence**:
+- Tag entity: Tag.java:29-34 (color, description fields)
+- TagAlias entity: TagAlias.java (full implementation)
+- Merge logic: TagService.java:284-320
+- AI suggestions: TagService.java:385-491
+
+---
+
+#### ✅ EPUB Import/Export (PHASE 1 & 2 COMPLETE)
+**Specification**: EPUB_IMPORT_EXPORT_SPECIFICATION.md (Status: ✅ COMPLETED)
+
+| Feature | Status | Files |
+|---------|--------|-------|
+| EPUB Import | ✅ Complete | EPUBImportService.java |
+| EPUB Export (Single) | ✅ Complete | EPUBExportService.java |
+| EPUB Export (Collection) | ✅ Complete | EPUBExportService.java, CollectionController:309-383 |
+| Reading Position (CFI) | ✅ Complete | ReadingPosition entity with epubCfi field |
+| Metadata Extraction | ✅ Complete | Cover, tags, author, title extraction |
+| Validation | ✅ Complete | File format and structure validation |
+
+**Frontend Integration**:
+- ✅ Import UI: frontend/src/app/import/epub/page.tsx
+- ✅ Bulk Import: frontend/src/app/import/bulk/page.tsx
+- ✅ Export from Story Detail: (per spec update)
+
+---
+
+#### ⚠️ Collections Feature (MOSTLY COMPLETE, CRITICAL SEARCH ISSUE)
+**Specification**: storycove-collections-spec.md (Status: ⚠️ 85% COMPLETE)
+
+| Feature | Status | Issue |
+|---------|--------|-------|
+| Entity Model | ✅ Complete | Collection, CollectionStory entities |
+| CRUD Operations | ✅ Complete | Create, update, delete, archive |
+| Story Management | ✅ Complete | Add, remove, reorder (gap-based positioning) |
+| Statistics | ✅ Complete | Word count, reading time, tag frequency |
+| EPUB Export | ✅ Complete | Full collection export |
+| **Search/Listing** | 🚨 **NOT IMPLEMENTED** | Returns empty results |
+| Reading Flow | ✅ Complete | Navigation context, previous/next |
+
+**Critical Gap**: SearchServiceAdapter does not index Collections in Solr/Typesense.
+
+---
+
+#### ✅ Reading Position Tracking (COMPLETE)
+| Feature | Status |
+|---------|--------|
+| Character Position | ✅ Complete |
+| Chapter Tracking | ✅ Complete |
+| EPUB CFI Support | ✅ Complete |
+| Percentage Calculation | ✅ Complete |
+| Context Before/After | ✅ Complete |
+
+---
+
+### 1.6 Frontend Implementation (PRESENT BUT NOT FULLY AUDITED)
+
+**Pages Found**:
+- ✅ Collections List: frontend/src/app/collections/page.tsx
+- ✅ Collection Detail: frontend/src/app/collections/[id]/page.tsx
+- ✅ Collection Reading: frontend/src/app/collections/[id]/read/[storyId]/page.tsx
+- ✅ Tag Maintenance: frontend/src/app/settings/tag-maintenance/page.tsx
+- ✅ EPUB Import: frontend/src/app/import/epub/page.tsx
+- ✅ Stories List: frontend/src/app/stories/page.tsx
+- ✅ Authors List: frontend/src/app/authors/page.tsx
+
+**Note**: Full frontend audit deferred to Phase 3.
+
+---
+
+## 2. Test Coverage Assessment
+
+### 2.1 Current Test Inventory
+
+**Total Test Files**: 9
+
+| Test File | Type | Target | Status |
+|-----------|------|--------|--------|
+| BaseRepositoryTest.java | Integration | Database setup | ✅ Present |
+| AuthorRepositoryTest.java | Integration | Author CRUD | ✅ Present |
+| StoryRepositoryTest.java | Integration | Story CRUD | ✅ Present |
+| TagTest.java | Unit | Tag entity | ✅ Present |
+| SeriesTest.java | Unit | Series entity | ✅ Present |
+| AuthorTest.java | Unit | Author entity | ✅ Present |
+| StoryTest.java | Unit | Story entity | ✅ Present |
+| AuthorServiceTest.java | Integration | Author service | ✅ Present |
+| StoryServiceTest.java | Integration | Story service | ✅ Present |
+
+### 2.2 Missing Critical Tests
+
+**Priority 1 (Critical Features)**:
+- ❌ CollectionServiceTest - **CRITICAL** (for search implementation verification)
+- ❌ TagServiceTest - Aliases, merging, AI suggestions
+- ❌ EPUBImportServiceTest - Import validation, metadata extraction
+- ❌ EPUBExportServiceTest - Export generation, collection EPUB
+
+**Priority 2 (Core Services)**:
+- ❌ ImageServiceTest - Upload, resize, security
+- ❌ HtmlSanitizationServiceTest - **SECURITY CRITICAL**
+- ❌ SearchServiceAdapterTest - Solr integration
+- ❌ ReadingPositionServiceTest (if exists) - CFI handling
+
+**Priority 3 (Controllers)**:
+- ❌ CollectionControllerTest
+- ❌ TagControllerTest
+- ❌ EPUBControllerTest
+
+### 2.3 Test Coverage Estimate
+- **Current Coverage**: ~25% of service layer
+- **Target Coverage**: 80%+ for service layer
+- **Gap**: ~55% (approximately 15-20 test classes needed)
+
+---
+
+## 3. Specification Compliance Summary
+
+| Specification Document | Compliance | Issues |
+|------------------------|------------|--------|
+| **storycove-spec.md** | 95% | Core features complete, minor gaps |
+| **DATA_MODEL.md** | 100% | Perfect match ✅ |
+| **API.md** | 90% | Most endpoints match, need verification |
+| **TAG_ENHANCEMENT_SPECIFICATION.md** | 100% | Fully implemented ✅ |
+| **EPUB_IMPORT_EXPORT_SPECIFICATION.md** | 100% | Phase 1 & 2 complete ✅ |
+| **storycove-collections-spec.md** | 85% | Search not implemented 🚨 |
+| **storycove-scraper-spec.md** | ❓ | Not assessed (separate feature) |
+
+---
+
+## 4. Database Schema Verification
+
+### 4.1 Tables vs Specification
+
+| Table | Specification | Implementation | Match |
+|-------|---------------|----------------|-------|
+| stories | DATA_MODEL.md | Story.java | ✅ 100% |
+| authors | DATA_MODEL.md | Author.java | ✅ 100% |
+| tags | DATA_MODEL.md + TAG_ENHANCEMENT | Tag.java | ✅ 100% |
+| tag_aliases | TAG_ENHANCEMENT | TagAlias.java | ✅ 100% |
+| series | DATA_MODEL.md | Series.java | ✅ 100% |
+| collections | storycove-collections-spec.md | Collection.java | ✅ 100% |
+| collection_stories | storycove-collections-spec.md | CollectionStory.java | ✅ 100% |
+| collection_tags | storycove-collections-spec.md | @JoinTable in Collection | ✅ 100% |
+| story_tags | DATA_MODEL.md | @JoinTable in Story | ✅ 100% |
+| reading_positions | EPUB_IMPORT_EXPORT | ReadingPosition.java | ✅ 100% |
+| libraries | (Multi-library) | Library.java | ✅ Present |
+
+**Assessment**: Database schema is **100% specification-compliant** ✅
+
+### 4.2 Indexes Verification
+
+| Index | Required By Spec | Implementation | Status |
+|-------|------------------|----------------|--------|
+| idx_collections_archived | Collections spec | Collection entity | ✅ |
+| idx_collection_stories_position | Collections spec | CollectionStory entity | ✅ |
+| idx_reading_position_story | EPUB spec | ReadingPosition entity | ✅ |
+| idx_tag_aliases_name | TAG_ENHANCEMENT | Unique constraint on alias_name | ✅ |
+
+---
+
+## 5. Architecture Compliance
+
+### 5.1 Search Integration Architecture
+
+**Specification Requirement** (storycove-collections-spec.md):
+> All search, filtering, and listing operations MUST use Typesense as the primary data source.
+
+**Current State**:
+- ✅ **Stories**: Properly use SearchServiceAdapter (Solr)
+- ✅ **Authors**: Properly use SearchServiceAdapter (Solr)
+- 🚨 **Collections**: NOT using SearchServiceAdapter
+
+### 5.2 Anti-Pattern Verification
+
+**Collections Repository** (CollectionRepository.java): ✅ CORRECT
+- Contains ONLY findById methods
+- Has explicit note: "For search/filter/list operations, use TypesenseService instead"
+- No search anti-patterns present
+
+**Comparison with Spec Anti-Patterns** (storycove-collections-spec.md:663-689):
+```java
+// ❌ WRONG patterns NOT FOUND in codebase ✅
+// CollectionRepository correctly avoids:
+// - findByNameContaining()
+// - findByTagsIn()
+// - findByNameContainingAndArchived()
+```
+
+**Issue**: While the repository layer is correctly designed, the service layer implementation is incomplete.
+
+---
+
+## 6. Code Quality Observations
+
+### 6.1 Positive Findings
+1. ✅ **Consistent Entity Design**: All entities use UUID, proper annotations, equals/hashCode
+2. ✅ **Transaction Management**: @Transactional used appropriately
+3. ✅ **Logging**: Comprehensive SLF4J logging throughout
+4. ✅ **Validation**: Jakarta validation annotations used
+5. ✅ **DTOs**: Proper separation between entities and DTOs
+6. ✅ **Error Handling**: Custom exceptions (ResourceNotFoundException, DuplicateResourceException)
+7. ✅ **Gap-Based Positioning**: Collections use proper positioning algorithm (multiples of 1000)
+
+### 6.2 Areas for Improvement
+1. ⚠️ **Test Coverage**: Major gap in service layer tests
+2. 🚨 **Collections Search**: Critical feature not implemented
+3. ⚠️ **Security Tests**: No dedicated tests for HtmlSanitizationService
+4. ⚠️ **Integration Tests**: Limited E2E testing
+
+---
+
+## 7. Dependencies & Technology Stack
+
+### 7.1 Key Dependencies (Observed)
+- ✅ Spring Boot (Jakarta EE)
+- ✅ Hibernate/JPA
+- ✅ PostgreSQL
+- ✅ Solr (in place of Typesense, acceptable alternative)
+- ✅ EPUBLib (for EPUB handling)
+- ✅ Jsoup (for HTML sanitization)
+- ✅ JWT (authentication)
+
+### 7.2 Search Engine Note
+**Specification**: Calls for Typesense
+**Implementation**: Uses Solr (Apache Solr)
+**Assessment**: ✅ Acceptable - Solr provides equivalent functionality
+
+---
+
+## 8. Documentation Status
+
+### 8.1 Specification Documents
+| Document | Status | Notes |
+|----------|--------|-------|
+| storycove-spec.md | ✅ Current | Comprehensive main spec |
+| DATA_MODEL.md | ✅ Current | Matches implementation |
+| API.md | ⚠️ Needs minor updates | Most endpoints documented |
+| TAG_ENHANCEMENT_SPECIFICATION.md | ✅ Current | Marked as completed |
+| EPUB_IMPORT_EXPORT_SPECIFICATION.md | ✅ Current | Phase 1 & 2 marked complete |
+| storycove-collections-spec.md | ⚠️ Needs update | Should note search not implemented |
+| CLAUDE.md | ✅ Current | Good project guidance |
+
+### 8.2 Code Documentation
+- ✅ Controllers: Well documented with Javadoc
+- ✅ Services: Good inline comments
+- ✅ Entities: Adequate field documentation
+- ⚠️ Tests: Limited documentation
+
+---
+
+## 9. Phase 1 Conclusions
+
+### 9.1 Summary
+StoryCove is a **well-architected application** with strong entity design, comprehensive feature implementation, and good adherence to specifications. The codebase demonstrates professional-quality development practices.
+
+### 9.2 Critical Finding
+**Collections Search**: The most critical issue is the incomplete Collections search implementation, which violates a mandatory architectural requirement and renders the Collections list view non-functional.
+
+### 9.3 Test Coverage Gap
+With only 9 test files covering the basics, there is a significant testing gap that needs to be addressed to ensure code quality and prevent regressions.
+
+### 9.4 Overall Assessment
+**Grade**: B+ (85%)
+- **Entity & Database**: A+ (100%)
+- **Service Layer**: B (85%)
+- **API Layer**: A- (90%)
+- **Test Coverage**: C (25%)
+- **Documentation**: A (95%)
+
+---
+
+## 10. Next Steps (Phase 2 & Beyond)
+
+### Phase 2: Backend Audit (NEXT)
+1. 🚨 **URGENT**: Implement Collections search in SearchServiceAdapter/SolrService
+2. Deep dive into each service for business logic verification
+3. Review transaction boundaries and error handling
+4. Verify security measures (authentication, authorization, sanitization)
+
+### Phase 3: Frontend Audit
+1. Verify UI components match UI/UX specifications
+2. Check Collections pagination implementation
+3. Review theme implementation (light/dark mode)
+4. Test responsive design
+
+### Phase 4: Test Coverage
+1. Create CollectionServiceTest (PRIORITY 1)
+2. Create TagServiceTest with alias and merge tests
+3. Create EPUBImportServiceTest and EPUBExportServiceTest
+4. Create security-critical HtmlSanitizationServiceTest
+5. Add integration tests for search flows
+
+### Phase 5: Documentation Updates
+1. Update API.md with any missing endpoints
+2. Update storycove-collections-spec.md with current status
+3. Create TESTING.md with coverage report
+
+### Phase 6: Code Quality
+1. Run static analysis tools (SonarQube, SpotBugs)
+2. Review security vulnerabilities
+3. Performance profiling
+
+---
+
+## 11. Priority Action Items
+
+### 🚨 CRITICAL (Must Fix Immediately)
+1. **Implement Collections Search** in SearchServiceAdapter
+   - File: backend/src/main/java/com/storycove/service/SearchServiceAdapter.java
+   - Add Solr indexing for Collections
+   - Update CollectionService.searchCollections() to use search engine
+   - Est. Time: 4-6 hours
+
+### ⚠️ HIGH PRIORITY (Fix Soon)
+2. **Create CollectionServiceTest**
+   - Verify CRUD operations
+   - Test search functionality once implemented
+   - Est. Time: 3-4 hours
+
+3. **Create HtmlSanitizationServiceTest**
+   - Security-critical testing
+   - XSS prevention verification
+   - Est. Time: 2-3 hours
+
+4. **Create TagServiceTest**
+   - Alias resolution
+   - Merge operations
+   - AI suggestions
+   - Est. Time: 4-5 hours
+
+### 📋 MEDIUM PRIORITY (Next Sprint)
+5. **EPUB Service Tests**
+   - EPUBImportServiceTest
+   - EPUBExportServiceTest
+   - Est. Time: 5-6 hours
+
+6. **Frontend Audit**
+   - Verify Collections pagination
+   - Check UI/UX compliance
+   - Est. Time: 4-6 hours
+
+### 📝 DOCUMENTATION (Ongoing)
+7. **Update API Documentation**
+   - Verify all endpoints documented
+   - Add missing examples
+   - Est. Time: 2-3 hours
+
+---
+
+## 12. Appendix: File Structure
+
+### Backend Structure
+```
+backend/src/main/java/com/storycove/
+├── controller/      (12 controllers - all implemented)
+├── service/         (20 services - 1 incomplete)
+├── entity/          (10 entities - all complete)
+├── repository/      (8 repositories - all appropriate)
+├── dto/             (~20 DTOs)
+├── exception/       (Custom exceptions)
+├── config/          (Security, DB, Solr config)
+└── security/        (JWT authentication)
+```
+
+### Test Structure
+```
+backend/src/test/java/com/storycove/
+├── entity/          (4 entity tests)
+├── repository/      (3 repository tests)
+└── service/         (2 service tests)
+```
+
+---
+
+**Phase 1 Assessment Complete** ✅
+
+**Next Phase**: Backend Audit (focusing on Collections search implementation)
+
+**Estimated Total Time to Address All Issues**: 30-40 hours

OPENSEARCH_MIGRATION_SPECIFICATION.md

@@ -1,889 +0,0 @@
-# StoryCove Search Migration Specification: Typesense to OpenSearch
-
-## Executive Summary
-
-This document specifies the migration from Typesense to OpenSearch for the StoryCove application. The migration will be implemented using a parallel approach, maintaining Typesense functionality while gradually transitioning to OpenSearch, ensuring zero downtime and the ability to rollback if needed.
-
-**Migration Goals:**
-- Solve random query reliability issues
-- Improve complex filtering performance
-- Maintain feature parity during transition
-- Zero downtime migration
-- Improved developer experience
-
----
-
-## Current State Analysis
-
-### Typesense Implementation Overview
-
-**Service Architecture:**
-- `TypesenseService.java` (~2000 lines) - Primary search service
-- 3 search indexes: Stories, Authors, Collections
-- Multi-library support with dynamic collection names
-- Integration with Spring Boot backend
-
-**Core Functionality:**
-1. **Full-text Search**: Stories, Authors with complex query building
-2. **Random Story Selection**: `_rand()` function with fallback logic
-3. **Advanced Filtering**: 15+ filter conditions with boolean logic
-4. **Faceting**: Tag aggregations and counts
-5. **Autocomplete**: Search suggestions with typeahead
-6. **CRUD Operations**: Index/update/delete for all entity types
-
-**Current Issues Identified:**
-- `_rand()` function unreliability requiring complex fallback logic
-- Complex filter query building with escaping issues
-- Limited aggregation capabilities
-- Inconsistent API behavior across query patterns
-- Multi-collection management complexity
-
-### Data Models and Schema
-
-**Story Index Fields:**
-```java
-// Core fields
-UUID id, String title, String description, String sourceUrl
-Integer wordCount, Integer rating, Integer volume
-Boolean isRead, LocalDateTime lastReadAt, Integer readingPosition
-
-// Relationships
-UUID authorId, String authorName
-UUID seriesId, String seriesName
-List<String> tagNames
-
-// Metadata
-LocalDateTime createdAt, LocalDateTime updatedAt
-String coverPath, String sourceDomain
-```
-
-**Author Index Fields:**
-```java
-UUID id, String name, String notes
-Integer authorRating, Double averageStoryRating, Integer storyCount
-List<String> urls, String avatarImagePath
-LocalDateTime createdAt, LocalDateTime updatedAt
-```
-
-**Collection Index Fields:**
-```java
-UUID id, String name, String description
-List<String> tagNames, Boolean archived
-LocalDateTime createdAt, LocalDateTime updatedAt
-Integer storyCount, Integer currentPosition
-```
-
-### API Endpoints Current State
-
-**Search Endpoints Analysis:**
-
-**✅ USED by Frontend (Must Implement):**
-- `GET /api/stories/search` - Main story search with complex filtering (CRITICAL)
-- `GET /api/stories/random` - Random story selection with filters (CRITICAL)
-- `GET /api/authors/search-typesense` - Author search (HIGH)
-- `GET /api/tags/autocomplete` - Tag suggestions (MEDIUM)
-- `POST /api/stories/reindex-typesense` - Admin reindex operations (MEDIUM)
-- `POST /api/authors/reindex-typesense` - Admin reindex operations (MEDIUM)
-- `POST /api/stories/recreate-typesense-collection` - Admin recreate (MEDIUM)
-- `POST /api/authors/recreate-typesense-collection` - Admin recreate (MEDIUM)
-
-**❌ UNUSED by Frontend (Skip Implementation):**
-- `GET /api/stories/search/suggestions` - Not used by frontend
-- `GET /api/authors/search` - Superseded by typesense version
-- `GET /api/series/search` - Not used by frontend
-- `GET /api/tags/search` - Superseded by autocomplete
-- `POST /api/search/reindex` - Not used by frontend
-- `GET /api/search/health` - Not used by frontend
-
-**Scope Reduction: ~40% fewer endpoints to implement**
-
-**Search Parameters (Stories):**
-```
-query, page, size, authors[], tags[], minRating, maxRating
-sortBy, sortDir, facetBy[]
-minWordCount, maxWordCount, createdAfter, createdBefore
-lastReadAfter, lastReadBefore, unratedOnly, readingStatus
-hasReadingProgress, hasCoverImage, sourceDomain, seriesFilter
-minTagCount, popularOnly, hiddenGemsOnly
-```
-
----
-
-## Target OpenSearch Architecture
-
-### Service Layer Design
-
-**New Components:**
-```
-OpenSearchService.java        - Primary search service (mirrors TypesenseService API)
-OpenSearchConfig.java         - Configuration and client setup
-SearchMigrationService.java   - Handles parallel operation during migration
-SearchServiceAdapter.java     - Abstraction layer for service switching
-```
-
-**Index Strategy:**
-- **Single-node deployment** for development/small installations
-- **Index-per-library** approach: `stories-{libraryId}`, `authors-{libraryId}`, `collections-{libraryId}`
-- **Index templates** for consistent mapping across libraries
-- **Aliases** for easy switching and zero-downtime updates
-
-### OpenSearch Index Mappings
-
-**Stories Index Mapping:**
-```json
-{
-  "settings": {
-    "number_of_shards": 1,
-    "number_of_replicas": 0,
-    "analysis": {
-      "analyzer": {
-        "story_analyzer": {
-          "type": "custom",
-          "tokenizer": "standard",
-          "filter": ["lowercase", "stop", "snowball"]
-        }
-      }
-    }
-  },
-  "mappings": {
-    "properties": {
-      "id": {"type": "keyword"},
-      "title": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {"keyword": {"type": "keyword"}}
-      },
-      "description": {
-        "type": "text",
-        "analyzer": "story_analyzer"
-      },
-      "authorName": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {"keyword": {"type": "keyword"}}
-      },
-      "seriesName": {
-        "type": "text",
-        "fields": {"keyword": {"type": "keyword"}}
-      },
-      "tagNames": {"type": "keyword"},
-      "wordCount": {"type": "integer"},
-      "rating": {"type": "integer"},
-      "volume": {"type": "integer"},
-      "isRead": {"type": "boolean"},
-      "readingPosition": {"type": "integer"},
-      "lastReadAt": {"type": "date"},
-      "createdAt": {"type": "date"},
-      "updatedAt": {"type": "date"},
-      "coverPath": {"type": "keyword"},
-      "sourceUrl": {"type": "keyword"},
-      "sourceDomain": {"type": "keyword"}
-    }
-  }
-}
-```
-
-**Authors Index Mapping:**
-```json
-{
-  "mappings": {
-    "properties": {
-      "id": {"type": "keyword"},
-      "name": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {"keyword": {"type": "keyword"}}
-      },
-      "notes": {"type": "text"},
-      "authorRating": {"type": "integer"},
-      "averageStoryRating": {"type": "float"},
-      "storyCount": {"type": "integer"},
-      "urls": {"type": "keyword"},
-      "avatarImagePath": {"type": "keyword"},
-      "createdAt": {"type": "date"},
-      "updatedAt": {"type": "date"}
-    }
-  }
-}
-```
-
-**Collections Index Mapping:**
-```json
-{
-  "mappings": {
-    "properties": {
-      "id": {"type": "keyword"},
-      "name": {
-        "type": "text",
-        "fields": {"keyword": {"type": "keyword"}}
-      },
-      "description": {"type": "text"},
-      "tagNames": {"type": "keyword"},
-      "archived": {"type": "boolean"},
-      "storyCount": {"type": "integer"},
-      "currentPosition": {"type": "integer"},
-      "createdAt": {"type": "date"},
-      "updatedAt": {"type": "date"}
-    }
-  }
-}
-```
-
-### Query Translation Strategy
-
-**Random Story Queries:**
-```java
-// Typesense (problematic)
-String sortBy = seed != null ? "_rand(" + seed + ")" : "_rand()";
-
-// OpenSearch (reliable)
-QueryBuilder randomQuery = QueryBuilders.functionScoreQuery(
-    QueryBuilders.boolQuery().must(filters),
-    ScoreFunctionBuilders.randomFunction(seed != null ? seed.intValue() : null)
-);
-```
-
-**Complex Filtering:**
-```java
-// Build bool query with multiple filter conditions
-BoolQueryBuilder boolQuery = QueryBuilders.boolQuery()
-    .must(QueryBuilders.multiMatchQuery(query, "title", "description", "authorName"))
-    .filter(QueryBuilders.termsQuery("tagNames", tags))
-    .filter(QueryBuilders.rangeQuery("wordCount").gte(minWords).lte(maxWords))
-    .filter(QueryBuilders.rangeQuery("rating").gte(minRating).lte(maxRating));
-```
-
-**Faceting/Aggregations:**
-```java
-// Tags aggregation
-AggregationBuilder tagsAgg = AggregationBuilders
-    .terms("tags")
-    .field("tagNames")
-    .size(100);
-
-// Rating ranges
-AggregationBuilder ratingRanges = AggregationBuilders
-    .range("rating_ranges")
-    .field("rating")
-    .addRange("unrated", 0, 1)
-    .addRange("low", 1, 3)
-    .addRange("high", 4, 6);
-```
-
----
-
-## Revised Implementation Phases (Scope Reduced by 40%)
-
-### Phase 1: Infrastructure Setup (Week 1)
-
-**Objectives:**
-- Add OpenSearch to Docker Compose
-- Create basic OpenSearch service
-- Establish index templates and mappings
-- **Focus**: Only stories, authors, and tags indexes (skip series, collections)
-
-**Deliverables:**
-1. **Docker Compose Updates:**
-```yaml
-opensearch:
-  image: opensearchproject/opensearch:2.11.0
-  environment:
-    - discovery.type=single-node
-    - DISABLE_SECURITY_PLUGIN=true
-    - OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx1g
-  ports:
-    - "9200:9200"
-  volumes:
-    - opensearch_data:/usr/share/opensearch/data
-```
-
-2. **OpenSearchConfig.java:**
-```java
-@Configuration
-@ConditionalOnProperty(name = "storycove.opensearch.enabled", havingValue = "true")
-public class OpenSearchConfig {
-    @Bean
-    public OpenSearchClient openSearchClient() {
-        // Client configuration
-    }
-}
-```
-
-3. **Basic Index Creation:**
-   - Create index templates for stories, authors, collections
-   - Implement index creation with proper mappings
-   - Add health check endpoint
-
-**Success Criteria:**
-- OpenSearch container starts successfully
-- Basic connectivity established
-- Index templates created and validated
-
-### Phase 2: Core Service Implementation (Week 2)
-
-**Objectives:**
-- Implement OpenSearchService with core functionality
-- Create service abstraction layer
-- Implement basic search operations
-- **Focus**: Only critical endpoints (stories search, random, authors)
-
-**Deliverables:**
-1. **OpenSearchService.java** - Core service implementing:
-   - `indexStory()`, `updateStory()`, `deleteStory()`
-   - `searchStories()` with basic query support (CRITICAL)
-   - `getRandomStoryId()` with reliable seed support (CRITICAL)
-   - `indexAuthor()`, `updateAuthor()`, `deleteAuthor()`
-   - `searchAuthors()` for authors page (HIGH)
-   - `bulkIndexStories()`, `bulkIndexAuthors()` for initial data loading
-
-2. **SearchServiceAdapter.java** - Abstraction layer:
-```java
-@Service
-public class SearchServiceAdapter {
-    @Autowired(required = false)
-    private TypesenseService typesenseService;
-
-    @Autowired(required = false)
-    private OpenSearchService openSearchService;
-
-    @Value("${storycove.search.provider:typesense}")
-    private String searchProvider;
-
-    public SearchResultDto<StorySearchDto> searchStories(...) {
-        return "opensearch".equals(searchProvider)
-            ? openSearchService.searchStories(...)
-            : typesenseService.searchStories(...);
-    }
-}
-```
-
-3. **Basic Query Implementation:**
-   - Full-text search across title/description/author
-   - Basic filtering (tags, rating, word count)
-   - Pagination and sorting
-
-**Success Criteria:**
-- Basic search functionality working
-- Service abstraction layer functional
-- Can switch between Typesense and OpenSearch via configuration
-
-### Phase 3: Advanced Features Implementation (Week 3)
-
-**Objectives:**
-- Implement complex filtering (all 15+ filter types)
-- Add random story functionality
-- Implement faceting/aggregations
-- Add autocomplete/suggestions
-
-**Deliverables:**
-1. **Complex Query Builder:**
-   - All filter conditions from original implementation
-   - Date range filtering with proper timezone handling
-   - Boolean logic for reading status, coverage, series filters
-
-2. **Random Story Implementation:**
-```java
-public Optional<UUID> getRandomStoryId(String searchQuery, List<String> tags, Long seed, ...) {
-    BoolQueryBuilder baseQuery = buildFilterQuery(searchQuery, tags, ...);
-
-    QueryBuilder randomQuery = QueryBuilders.functionScoreQuery(
-        baseQuery,
-        ScoreFunctionBuilders.randomFunction(seed != null ? seed.intValue() : null)
-    );
-
-    SearchRequest request = new SearchRequest("stories-" + getCurrentLibraryId())
-        .source(new SearchSourceBuilder()
-            .query(randomQuery)
-            .size(1)
-            .fetchSource(new String[]{"id"}, null));
-
-    // Execute and return result
-}
-```
-
-3. **Faceting Implementation:**
-   - Tag aggregations with counts
-   - Rating range aggregations
-   - Author aggregations
-   - Custom facet builders
-
-4. **Autocomplete Service:**
-   - Suggest-based implementation using completion fields
-   - Prefix matching for story titles and author names
-
-**Success Criteria:**
-- All filter conditions working correctly
-- Random story selection reliable with seed support
-- Faceting returns accurate counts
-- Autocomplete responsive and accurate
-
-### Phase 4: Data Migration & Parallel Operation (Week 4)
-
-**Objectives:**
-- Implement bulk data migration from database
-- Enable parallel operation (write to both systems)
-- Comprehensive testing of OpenSearch functionality
-
-**Deliverables:**
-1. **Migration Service:**
-```java
-@Service
-public class SearchMigrationService {
-    public void performFullMigration() {
-        // Migrate all libraries
-        List<Library> libraries = libraryService.findAll();
-        for (Library library : libraries) {
-            migrateLibraryData(library);
-        }
-    }
-
-    private void migrateLibraryData(Library library) {
-        // Create indexes for library
-        // Bulk load stories, authors, collections
-        // Verify data integrity
-    }
-}
-```
-
-2. **Dual-Write Implementation:**
-   - Modify all entity update operations to write to both systems
-   - Add configuration flag for dual-write mode
-   - Error handling for partial failures
-
-3. **Data Validation Tools:**
-   - Compare search result counts between systems
-   - Validate random story selection consistency
-   - Check faceting accuracy
-
-**Success Criteria:**
-- Complete data migration with 100% accuracy
-- Dual-write operations working without errors
-- Search result parity between systems verified
-
-### Phase 5: API Integration & Testing (Week 5)
-
-**Objectives:**
-- Update controller endpoints to use OpenSearch
-- Comprehensive integration testing
-- Performance testing and optimization
-
-**Deliverables:**
-1. **Controller Updates:**
-   - Modify controllers to use SearchServiceAdapter
-   - Add migration controls for gradual rollout
-   - Implement A/B testing capability
-
-2. **Integration Tests:**
-```java
-@SpringBootTest
-@TestMethodOrder(OrderAnnotation.class)
-public class OpenSearchIntegrationTest {
-    @Test
-    @Order(1)
-    void testBasicSearch() {
-        // Test basic story search functionality
-    }
-
-    @Test
-    @Order(2)
-    void testComplexFiltering() {
-        // Test all 15+ filter conditions
-    }
-
-    @Test
-    @Order(3)
-    void testRandomStory() {
-        // Test random story with and without seed
-    }
-
-    @Test
-    @Order(4)
-    void testFaceting() {
-        // Test aggregation accuracy
-    }
-}
-```
-
-3. **Performance Testing:**
-   - Load testing with realistic data volumes
-   - Query performance benchmarking
-   - Memory usage monitoring
-
-**Success Criteria:**
-- All integration tests passing
-- Performance meets or exceeds Typesense baseline
-- Memory usage within acceptable limits (< 2GB)
-
-### Phase 6: Production Rollout & Monitoring (Week 6)
-
-**Objectives:**
-- Production deployment with feature flags
-- Gradual user migration with monitoring
-- Rollback capability testing
-
-**Deliverables:**
-1. **Feature Flag Implementation:**
-```java
-@Component
-public class SearchFeatureFlags {
-    @Value("${storycove.search.opensearch.enabled:false}")
-    private boolean openSearchEnabled;
-
-    @Value("${storycove.search.opensearch.percentage:0}")
-    private int rolloutPercentage;
-
-    public boolean shouldUseOpenSearch(String userId) {
-        if (!openSearchEnabled) return false;
-        return userId.hashCode() % 100 < rolloutPercentage;
-    }
-}
-```
-
-2. **Monitoring & Alerting:**
-   - Query performance metrics
-   - Error rate monitoring
-   - Search result accuracy validation
-   - User experience metrics
-
-3. **Rollback Procedures:**
-   - Immediate rollback to Typesense capability
-   - Data consistency verification
-   - Performance rollback triggers
-
-**Success Criteria:**
-- Successful production deployment
-- Zero user-facing issues during rollout
-- Monitoring showing improved performance
-- Rollback procedures validated
-
-### Phase 7: Cleanup & Documentation (Week 7)
-
-**Objectives:**
-- Remove Typesense dependencies
-- Update documentation
-- Performance optimization
-
-**Deliverables:**
-1. **Code Cleanup:**
-   - Remove TypesenseService and related classes
-   - Clean up Docker Compose configuration
-   - Remove unused dependencies
-
-2. **Documentation Updates:**
-   - Update deployment documentation
-   - Search API documentation
-   - Troubleshooting guides
-
-3. **Performance Tuning:**
-   - Index optimization
-   - Query performance tuning
-   - Resource allocation optimization
-
-**Success Criteria:**
-- Typesense completely removed
-- Documentation up to date
-- Optimized performance in production
-
----
-
-## Data Migration Strategy
-
-### Pre-Migration Validation
-
-**Data Integrity Checks:**
-1. Count validation: Ensure all stories/authors/collections are present
-2. Field validation: Verify all required fields are populated
-3. Relationship validation: Check author-story and series-story relationships
-4. Library separation: Ensure proper multi-library data isolation
-
-**Migration Process:**
-
-1. **Index Creation:**
-```java
-// Create indexes with proper mappings for each library
-for (Library library : libraries) {
-    String storiesIndex = "stories-" + library.getId();
-    createIndexWithMapping(storiesIndex, getStoriesMapping());
-    createIndexWithMapping("authors-" + library.getId(), getAuthorsMapping());
-    createIndexWithMapping("collections-" + library.getId(), getCollectionsMapping());
-}
-```
-
-2. **Bulk Data Loading:**
-```java
-// Load in batches to manage memory usage
-int batchSize = 1000;
-List<Story> allStories = storyService.findByLibraryId(libraryId);
-
-for (int i = 0; i < allStories.size(); i += batchSize) {
-    List<Story> batch = allStories.subList(i, Math.min(i + batchSize, allStories.size()));
-    List<StoryDocument> documents = batch.stream()
-        .map(this::convertToSearchDocument)
-        .collect(Collectors.toList());
-
-    bulkIndexStories(documents, "stories-" + libraryId);
-}
-```
-
-3. **Post-Migration Validation:**
-   - Count comparison between database and OpenSearch
-   - Spot-check random records for field accuracy
-   - Test search functionality with known queries
-   - Verify faceting counts match expected values
-
-### Rollback Strategy
-
-**Immediate Rollback Triggers:**
-- Search error rate > 1%
-- Query performance degradation > 50%
-- Data inconsistency detected
-- Memory usage > 4GB sustained
-
-**Rollback Process:**
-1. Update feature flag to disable OpenSearch
-2. Verify Typesense still operational
-3. Clear OpenSearch indexes to free resources
-4. Investigate and document issues
-
-**Data Consistency During Rollback:**
-- Continue dual-write during investigation
-- Re-sync any missed updates to OpenSearch
-- Validate data integrity before retry
-
----
-
-## Testing Strategy
-
-### Unit Tests
-
-**OpenSearchService Unit Tests:**
-```java
-@ExtendWith(MockitoExtension.class)
-class OpenSearchServiceTest {
-    @Mock private OpenSearchClient client;
-    @InjectMocks private OpenSearchService service;
-
-    @Test
-    void testSearchStoriesBasicQuery() {
-        // Mock OpenSearch response
-        // Test basic search functionality
-    }
-
-    @Test
-    void testComplexFilterQuery() {
-        // Test complex boolean query building
-    }
-
-    @Test
-    void testRandomStorySelection() {
-        // Test random query with seed
-    }
-}
-```
-
-**Query Builder Tests:**
-- Test all 15+ filter conditions
-- Validate query structure and parameters
-- Test edge cases and null handling
-
-### Integration Tests
-
-**Full Search Integration:**
-```java
-@SpringBootTest
-@Testcontainers
-class OpenSearchIntegrationTest {
-    @Container
-    static OpenSearchContainer opensearch = new OpenSearchContainer("opensearchproject/opensearch:2.11.0");
-
-    @Test
-    void testEndToEndStorySearch() {
-        // Insert test data
-        // Perform search via controller
-        // Validate results
-    }
-}
-```
-
-### Performance Tests
-
-**Load Testing Scenarios:**
-1. **Concurrent Search Load:**
-   - 50 concurrent users performing searches
-   - Mixed query complexity
-   - Duration: 10 minutes
-
-2. **Bulk Indexing Performance:**
-   - Index 10,000 stories in batches
-   - Measure throughput and memory usage
-
-3. **Random Query Performance:**
-   - 1000 random story requests with different seeds
-   - Compare with Typesense baseline
-
-### Acceptance Tests
-
-**Functional Requirements:**
-- All existing search functionality preserved
-- Random story selection improved reliability
-- Faceting accuracy maintained
-- Multi-library separation working
-
-**Performance Requirements:**
-- Search response time < 100ms for 95th percentile
-- Random story selection < 50ms
-- Index update operations < 10ms
-- Memory usage < 2GB in production
-
----
-
-## Risk Analysis & Mitigation
-
-### Technical Risks
-
-**Risk: OpenSearch Memory Usage**
-- *Probability: Medium*
-- *Impact: High*
-- *Mitigation: Resource monitoring, index optimization, container limits*
-
-**Risk: Query Performance Regression**
-- *Probability: Low*
-- *Impact: High*
-- *Mitigation: Performance testing, query optimization, caching layer*
-
-**Risk: Data Migration Accuracy**
-- *Probability: Low*
-- *Impact: Critical*
-- *Mitigation: Comprehensive validation, dual-write verification, rollback procedures*
-
-**Risk: Complex Filter Compatibility**
-- *Probability: Medium*
-- *Impact: Medium*
-- *Mitigation: Extensive testing, gradual rollout, feature flags*
-
-### Operational Risks
-
-**Risk: Production Deployment Issues**
-- *Probability: Medium*
-- *Impact: High*
-- *Mitigation: Staging environment testing, gradual rollout, immediate rollback capability*
-
-**Risk: Team Learning Curve**
-- *Probability: High*
-- *Impact: Low*
-- *Mitigation: Documentation, training, gradual responsibility transfer*
-
-### Business Continuity
-
-**Zero-Downtime Requirements:**
-- Maintain Typesense during entire migration
-- Feature flag-based switching
-- Immediate rollback capability
-- Health monitoring with automated alerts
-
----
-
-## Success Criteria
-
-### Functional Requirements ✅
-- [ ] All search functionality migrated successfully
-- [ ] Random story selection working reliably with seeds
-- [ ] Complex filtering (15+ conditions) working accurately
-- [ ] Faceting/aggregation results match expected values
-- [ ] Multi-library support maintained
-- [ ] Autocomplete functionality preserved
-
-### Performance Requirements ✅
-- [ ] Search response time ≤ 100ms (95th percentile)
-- [ ] Random story selection ≤ 50ms
-- [ ] Index operations ≤ 10ms
-- [ ] Memory usage ≤ 2GB sustained
-- [ ] Zero search downtime during migration
-
-### Technical Requirements ✅
-- [ ] Code quality maintained (test coverage ≥ 80%)
-- [ ] Documentation updated and comprehensive
-- [ ] Monitoring and alerting implemented
-- [ ] Rollback procedures tested and validated
-- [ ] Typesense dependencies cleanly removed
-
----
-
-## Timeline Summary
-
-| Phase | Duration | Key Deliverables | Risk Level |
-|-------|----------|------------------|------------|
-| 1. Infrastructure | 1 week | Docker setup, basic service | Low |
-| 2. Core Service | 1 week | Basic search operations | Medium |
-| 3. Advanced Features | 1 week | Complex filtering, random queries | High |
-| 4. Data Migration | 1 week | Full data migration, dual-write | High |
-| 5. API Integration | 1 week | Controller updates, testing | Medium |
-| 6. Production Rollout | 1 week | Gradual deployment, monitoring | High |
-| 7. Cleanup | 1 week | Remove Typesense, documentation | Low |
-
-**Total Estimated Duration: 7 weeks**
-
----
-
-## Configuration Management
-
-### Environment Variables
-
-```bash
-# OpenSearch Configuration
-OPENSEARCH_HOST=opensearch
-OPENSEARCH_PORT=9200
-OPENSEARCH_USERNAME=admin
-OPENSEARCH_PASSWORD=${OPENSEARCH_PASSWORD}
-
-# Feature Flags
-STORYCOVE_OPENSEARCH_ENABLED=true
-STORYCOVE_SEARCH_PROVIDER=opensearch
-STORYCOVE_SEARCH_DUAL_WRITE=true
-STORYCOVE_OPENSEARCH_ROLLOUT_PERCENTAGE=100
-
-# Performance Tuning
-OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx2g
-STORYCOVE_SEARCH_BATCH_SIZE=1000
-STORYCOVE_SEARCH_TIMEOUT=30s
-```
-
-### Docker Compose Updates
-
-```yaml
-# Add to docker-compose.yml
-opensearch:
-  image: opensearchproject/opensearch:2.11.0
-  environment:
-    - discovery.type=single-node
-    - DISABLE_SECURITY_PLUGIN=true
-    - OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx2g
-  volumes:
-    - opensearch_data:/usr/share/opensearch/data
-  networks:
-    - storycove-network
-
-volumes:
-  opensearch_data:
-```
-
----
-
-## Conclusion
-
-This specification provides a comprehensive roadmap for migrating StoryCove from Typesense to OpenSearch. The phased approach ensures minimal risk while delivering improved reliability and performance, particularly for random story queries.
-
-The parallel implementation strategy allows for thorough validation and provides confidence in the migration while maintaining the ability to rollback if issues arise. Upon successful completion, StoryCove will have a more robust and scalable search infrastructure that better supports its growth and feature requirements.
-
-**Next Steps:**
-1. Review and approve this specification
-2. Set up development environment with OpenSearch
-3. Begin Phase 1 implementation
-4. Establish monitoring and success metrics
-5. Execute migration according to timeline
-
----
-
-*Document Version: 1.0*
-*Last Updated: 2025-01-17*
-*Author: Claude Code Assistant*

PORTABLE_TEXT_SETUP.md

@@ -0,0 +1,118 @@
+# Portable Text Editor Setup Instructions
+
+## Current Status
+
+⚠️ **Temporarily Reverted to Original Editor**
+
+Due to npm cache permission issues preventing Docker builds, I've temporarily reverted the imports back to `RichTextEditor`. The Portable Text implementation is complete and ready to activate once the npm issue is resolved.
+
+## Files Ready for Portable Text
+
+- ✅ `PortableTextEditor.tsx` - Complete implementation
+- ✅ `schema.ts` - Portable Text schema
+- ✅ `conversion.ts` - HTML ↔ Portable Text conversion
+- ✅ `package.json.with-portabletext` - Updated dependencies
+
+## Docker Build Issue Resolution
+
+The error `npm ci` requires `package-lock.json` but npm cache permissions prevent generating it.
+
+### Solution Steps:
+
+1. **Fix npm permissions:**
+```bash
+sudo chown -R $(whoami) ~/.npm
+```
+
+2. **Switch to Portable Text setup:**
+```bash
+cd frontend
+mv package.json package.json.original
+mv package.json.with-portabletext package.json
+npm install  # This will generate package-lock.json
+```
+
+3. **Update component imports** (change RichTextEditor → PortableTextEditor):
+```typescript
+// In src/app/add-story/page.tsx and src/app/stories/[id]/edit/page.tsx
+import PortableTextEditor from '../../components/stories/PortableTextEditor';
+// And update the JSX to use <PortableTextEditor ... />
+```
+
+4. **Build and test:**
+```bash
+npm run build
+docker-compose build
+```
+
+## Implementation Complete
+
+✅ **Portable Text Schema** - Defines formatting options matching the original editor
+✅ **HTML ↔ Portable Text Conversion** - Seamless conversion between formats
+✅ **Sanitization Integration** - Uses existing sanitization strategy
+✅ **Component Replacement** - PortableTextEditor replaces RichTextEditor
+✅ **Image Processing** - Maintains existing image processing functionality
+✅ **Toolbar** - All formatting buttons from original editor
+✅ **Keyboard Shortcuts** - Ctrl+B, Ctrl+I, Ctrl+Shift+1-6
+
+## Features Maintained
+
+### 1. **Formatting Options**
+- Bold, Italic, Underline, Strike, Code
+- Headings H1-H6
+- Paragraphs and Blockquotes
+- All original toolbar buttons
+
+### 2. **Visual & HTML Modes**
+- Visual mode: Structured Portable Text editing
+- HTML mode: Direct HTML editing (fallback)
+- Live preview in HTML mode
+
+### 3. **Image Processing**
+- Existing image processing pipeline maintained
+- Background image download and conversion
+- Processing status indicators
+- Warning system
+
+### 4. **Paste Handling**
+- Rich text paste from websites
+- Image processing during paste
+- HTML sanitization
+- Structured content conversion
+
+### 5. **Maximization & Resizing**
+- Fullscreen editing mode
+- Resizable editor height
+- Keyboard shortcuts (Escape to exit)
+
+## Benefits of Portable Text
+
+1. **Structured Content** - Content is stored as JSON, not just HTML
+2. **Future-Proof** - Easy to export/migrate content
+3. **Better Search** - Structured content works better with Typesense
+4. **Extensible** - Easy to add custom block types (images, etc.)
+5. **Sanitization** - Inherently safer than HTML parsing
+
+## Next Steps
+
+1. Install the npm packages using one of the methods above
+2. Test the editor functionality
+3. Verify image processing works correctly
+4. Optional: Add custom image block types for enhanced image handling
+
+## File Structure
+
+```
+frontend/src/
+├── components/stories/
+│   ├── PortableTextEditor.tsx      # New editor component
+│   └── RichTextEditor.tsx          # Original (can be removed after testing)
+├── lib/portabletext/
+│   ├── schema.ts                   # Portable Text schema and types
+│   └── conversion.ts               # HTML ↔ Portable Text conversion
+└── app/
+    ├── add-story/page.tsx          # Updated to use PortableTextEditor
+    └── stories/[id]/edit/page.tsx  # Updated to use PortableTextEditor
+```
+
+The implementation is backward compatible and maintains all existing functionality while providing the benefits of structured content editing.

REFRESH_TOKEN_IMPLEMENTATION.md

@@ -0,0 +1,269 @@
+# Refresh Token Implementation
+
+## Overview
+
+This document describes the refresh token functionality implemented for StoryCove, allowing users to stay authenticated for up to 2 weeks with automatic token refresh.
+
+## Architecture
+
+### Token Types
+
+1. **Access Token (JWT)**
+   - Lifetime: 24 hours
+   - Stored in: httpOnly cookie + localStorage
+   - Used for: API authentication
+   - Format: JWT with subject and libraryId claims
+
+2. **Refresh Token**
+   - Lifetime: 14 days (2 weeks)
+   - Stored in: httpOnly cookie + database
+   - Used for: Generating new access tokens
+   - Format: Secure random 256-bit token (Base64 encoded)
+
+### Token Flow
+
+1. **Login**
+   - User provides password
+   - Backend validates password
+   - Backend generates both access token and refresh token
+   - Both tokens sent as httpOnly cookies
+   - Access token also returned in response body for localStorage
+
+2. **API Request**
+   - Frontend sends access token via Authorization header and cookie
+   - Backend validates access token
+   - If valid: Request proceeds
+   - If expired: Frontend attempts token refresh
+
+3. **Token Refresh**
+   - Frontend detects 401/403 response
+   - Frontend automatically calls `/api/auth/refresh`
+   - Backend validates refresh token from cookie
+   - If valid: New access token generated and returned
+   - If invalid/expired: User redirected to login
+
+4. **Logout**
+   - Frontend calls `/api/auth/logout`
+   - Backend revokes refresh token in database
+   - Both cookies cleared
+   - User redirected to login page
+
+## Backend Implementation
+
+### New Files
+
+1. **`RefreshToken.java`** - Entity class
+   - Fields: id, token, expiresAt, createdAt, revokedAt, libraryId, userAgent, ipAddress
+   - Helper methods: isExpired(), isRevoked(), isValid()
+
+2. **`RefreshTokenRepository.java`** - Repository interface
+   - findByToken(String)
+   - deleteExpiredTokens(LocalDateTime)
+   - revokeAllByLibraryId(String, LocalDateTime)
+   - revokeAll(LocalDateTime)
+
+3. **`RefreshTokenService.java`** - Service class
+   - createRefreshToken(libraryId, userAgent, ipAddress)
+   - verifyRefreshToken(token)
+   - revokeToken(token)
+   - revokeAllByLibraryId(libraryId)
+   - cleanupExpiredTokens() - Scheduled daily at 3 AM
+
+### Modified Files
+
+1. **`JwtUtil.java`**
+   - Added `refreshExpiration` property (14 days)
+   - Added `generateRefreshToken()` method
+   - Added `getRefreshExpirationMs()` method
+
+2. **`AuthController.java`**
+   - Updated `/login` endpoint to create and return refresh token
+   - Added `/refresh` endpoint to handle token refresh
+   - Updated `/logout` endpoint to revoke refresh token
+   - Added helper methods: `getRefreshTokenFromCookies()`, `getClientIpAddress()`
+
+3. **`SecurityConfig.java`**
+   - Added `/api/auth/refresh` to public endpoints
+
+4. **`application.yml`**
+   - Added `storycove.jwt.refresh-expiration: 1209600000` (14 days)
+
+## Frontend Implementation
+
+### Modified Files
+
+1. **`api.ts`**
+   - Added automatic token refresh logic in response interceptor
+   - Added request queuing during token refresh
+   - Prevents multiple simultaneous refresh attempts
+   - Automatically retries failed requests after refresh
+
+### Token Refresh Logic
+
+```typescript
+// On 401/403 response:
+1. Check if already retrying -> if yes, queue request
+2. Check if refresh/login endpoint -> if yes, logout
+3. Attempt token refresh via /api/auth/refresh
+4. If successful:
+   - Update localStorage with new token
+   - Retry original request
+   - Process queued requests
+5. If failed:
+   - Clear token
+   - Redirect to login
+   - Reject queued requests
+```
+
+## Security Features
+
+1. **httpOnly Cookies**: Prevents XSS attacks
+2. **Token Revocation**: Refresh tokens can be revoked
+3. **Database Storage**: Refresh tokens stored server-side
+4. **Expiration Tracking**: Tokens have strict expiration dates
+5. **IP & User Agent Tracking**: Stored for security auditing
+6. **Library Isolation**: Tokens scoped to specific library
+
+## Database Schema
+
+```sql
+CREATE TABLE refresh_tokens (
+    id UUID PRIMARY KEY,
+    token VARCHAR(255) UNIQUE NOT NULL,
+    expires_at TIMESTAMP NOT NULL,
+    created_at TIMESTAMP NOT NULL,
+    revoked_at TIMESTAMP,
+    library_id VARCHAR(255),
+    user_agent VARCHAR(255) NOT NULL,
+    ip_address VARCHAR(255) NOT NULL
+);
+
+CREATE INDEX idx_refresh_token ON refresh_tokens(token);
+CREATE INDEX idx_expires_at ON refresh_tokens(expires_at);
+```
+
+## Configuration
+
+### Backend (`application.yml`)
+
+```yaml
+storycove:
+  jwt:
+    expiration: 86400000        # 24 hours (access token)
+    refresh-expiration: 1209600000  # 14 days (refresh token)
+```
+
+### Environment Variables
+
+No new environment variables required. Existing `JWT_SECRET` is used.
+
+## Testing
+
+Comprehensive test suite in `RefreshTokenServiceTest.java`:
+- Token creation
+- Token validation
+- Expired token handling
+- Revoked token handling
+- Token revocation
+- Cleanup operations
+
+Run tests:
+```bash
+cd backend
+mvn test -Dtest=RefreshTokenServiceTest
+```
+
+## Maintenance
+
+### Automated Cleanup
+
+Expired tokens are automatically cleaned up daily at 3 AM via scheduled task in `RefreshTokenService.cleanupExpiredTokens()`.
+
+### Manual Revocation
+
+```java
+// Revoke all tokens for a library
+refreshTokenService.revokeAllByLibraryId("library-id");
+
+// Revoke all tokens (logout all users)
+refreshTokenService.revokeAll();
+```
+
+## User Experience
+
+1. **Seamless Authentication**: Users stay logged in for 2 weeks
+2. **Automatic Refresh**: Token refresh happens transparently
+3. **No Interruptions**: API calls succeed even when access token expires
+4. **Backend Restart**: Users must re-login (JWT secret rotates on startup)
+5. **Cross-Device Library Switching**: Automatic library switching when using different devices with different libraries
+
+## Cross-Device Library Switching
+
+### Feature Overview
+
+The system automatically detects and switches libraries when you use different devices authenticated to different libraries. This ensures you always see the correct library's data.
+
+### How It Works
+
+**Scenario 1: Active Access Token (within 24 hours)**
+1. Request comes in with valid JWT access token
+2. `JwtAuthenticationFilter` extracts `libraryId` from token
+3. Compares with `currentLibraryId` in backend
+4. **If different**: Automatically switches to token's library
+5. **If same**: Early return (no overhead, just string comparison)
+6. Request proceeds with correct library
+
+**Scenario 2: Token Refresh (after 24 hours)**
+1. Access token expired, refresh token still valid
+2. `/api/auth/refresh` endpoint validates refresh token
+3. Extracts `libraryId` from refresh token
+4. Compares with `currentLibraryId` in backend
+5. **If different**: Automatically switches to token's library
+6. **If same**: Early return (no overhead)
+7. Generates new access token with correct `libraryId`
+
+**Scenario 3: After Backend Restart**
+1. `currentLibraryId` is null (no active library)
+2. First request with any token automatically switches to that token's library
+3. Subsequent requests use early return optimization
+
+### Performance
+
+**When libraries match** (most common case):
+- Simple string comparison: `libraryId.equals(currentLibraryId)`
+- Immediate return - zero overhead
+- No datasource changes, no reindexing
+
+**When libraries differ** (switching devices):
+- Synchronized library switch
+- Datasource routing updated instantly
+- Solr reindex runs asynchronously (doesn't block request)
+- Takes 2-3 seconds in background
+
+### Edge Cases
+
+**Multi-device simultaneous use:**
+- If two devices with different libraries are used simultaneously
+- Last request "wins" and switches backend to its library
+- Not recommended but handled gracefully
+- Each device corrects itself on next request
+
+**Library doesn't exist:**
+- If token contains invalid `libraryId`
+- Library switch fails with error
+- Request is rejected with 500 error
+- User must re-login with valid credentials
+
+## Future Enhancements
+
+Potential improvements:
+1. Persistent JWT secret (survive backend restarts)
+2. Sliding refresh token expiration (extend on use)
+3. Multiple device management (view/revoke sessions)
+4. Configurable token lifetimes via environment variables
+5. Token rotation (new refresh token on each use)
+6. Thread-local library context for true stateless operation
+
+## Summary
+
+The refresh token implementation provides a robust, secure authentication system that balances user convenience (2-week sessions) with security (short-lived access tokens, automatic refresh). The implementation follows industry best practices and provides a solid foundation for future enhancements.

SOLR_LIBRARY_MIGRATION.md

@@ -0,0 +1,244 @@
+# Solr Library Separation Migration Guide
+
+This guide explains how to migrate existing StoryCove deployments to support proper library separation in Solr search.
+
+## What Changed
+
+The Solr service has been enhanced to support multi-tenant library separation by:
+- Adding a `libraryId` field to all Solr documents
+- Filtering all search queries by the current library context
+- Ensuring complete data isolation between libraries
+
+## Migration Options
+
+### Option 1: Docker Volume Reset (Recommended for Docker)
+
+**Best for**: Development, staging, and Docker-based deployments where data loss is acceptable.
+
+```bash
+# Stop the application
+docker-compose down
+
+# Remove only the Solr data volume (preserves database and images)
+docker volume rm storycove_solr_data
+
+# Restart - Solr will recreate cores with new schema
+docker-compose up -d
+
+# Wait for services to start, then trigger reindex via admin panel
+```
+
+**Pros**: Clean, simple, guaranteed to work
+**Cons**: Requires downtime, loses existing search index
+
+### Option 2: Schema API Migration (Production Safe)
+
+**Best for**: Production environments where you need to preserve uptime.
+
+**Method A: Automatic (Recommended)**
+```bash
+# Single endpoint that adds field and migrates data
+curl -X POST "http://your-app-host/api/admin/search/solr/migrate-library-schema" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+**Method B: Manual Steps**
+```bash
+# Step 1: Add libraryId field via app API
+curl -X POST "http://your-app-host/api/admin/search/solr/add-library-field" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+
+# Step 2: Run migration
+curl -X POST "http://your-app-host/api/admin/search/solr/migrate-library-schema" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+**Method C: Direct Solr API (if app API fails)**
+```bash
+# Add libraryId field to stories core
+curl -X POST "http://your-solr-host:8983/solr/storycove_stories/schema" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "add-field": {
+      "name": "libraryId",
+      "type": "string",
+      "indexed": true,
+      "stored": true,
+      "required": false
+    }
+  }'
+
+# Add libraryId field to authors core
+curl -X POST "http://your-solr-host:8983/solr/storycove_authors/schema" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "add-field": {
+      "name": "libraryId",
+      "type": "string",
+      "indexed": true,
+      "stored": true,
+      "required": false
+    }
+  }'
+
+# Then run the migration
+curl -X POST "http://your-app-host/api/admin/search/solr/migrate-library-schema" \
+  -H "Authorization: Bearer YOUR_JWT_TOKEN"
+```
+
+**Pros**: No downtime, preserves service availability, automatic field addition
+**Cons**: Requires API access
+
+### Option 3: Application-Level Migration (Recommended for Production)
+
+**Best for**: Production environments with proper admin access.
+
+1. **Deploy the code changes** to your environment
+2. **Access the admin panel** of your application
+3. **Navigate to search settings**
+4. **Use the "Migrate Library Schema" button** or API endpoint:
+   ```
+   POST /api/admin/search/solr/migrate-library-schema
+   ```
+
+**Pros**: User-friendly, handles all complexity internally
+**Cons**: Requires admin access to application
+
+## Step-by-Step Migration Process
+
+### For Docker Deployments
+
+1. **Backup your data** (optional but recommended):
+   ```bash
+   # Backup database
+   docker-compose exec postgres pg_dump -U storycove storycove > backup.sql
+   ```
+
+2. **Pull the latest code** with library separation fixes
+
+3. **Choose migration approach**:
+   - **Quick & Clean**: Use Option 1 (volume reset)
+   - **Production**: Use Option 2 or 3
+
+4. **Verify migration**:
+   - Log in with different library passwords
+   - Perform searches to confirm isolation
+   - Check that new content gets indexed with library IDs
+
+### For Kubernetes/Production Deployments
+
+1. **Update your deployment** with the new container images
+
+2. **Add the libraryId field** to Solr schema using Option 2
+
+3. **Use the migration endpoint** (Option 3):
+   ```bash
+   kubectl exec -it deployment/storycove-backend -- \
+     curl -X POST http://localhost:8080/api/admin/search/solr/migrate-library-schema
+   ```
+
+4. **Monitor logs** for successful migration
+
+## Verification Steps
+
+After migration, verify that library separation is working:
+
+1. **Test with multiple libraries**:
+   - Log in with Library A password
+   - Add/search content
+   - Log in with Library B password
+   - Confirm Library A content is not visible
+
+2. **Check Solr directly** (if accessible):
+   ```bash
+   # Should show documents with libraryId field
+   curl "http://solr:8983/solr/storycove_stories/select?q=*:*&fl=id,title,libraryId&rows=5"
+   ```
+
+3. **Monitor application logs** for any library separation errors
+
+## Troubleshooting
+
+### "unknown field 'libraryId'" Error
+
+**Problem**: `ERROR: [doc=xxx] unknown field 'libraryId'`
+
+**Cause**: The Solr schema doesn't have the libraryId field yet.
+
+**Solutions**:
+
+1. **Use the automated migration** (adds field automatically):
+   ```bash
+   curl -X POST "http://your-app/api/admin/search/solr/migrate-library-schema"
+   ```
+
+2. **Add field manually first**:
+   ```bash
+   # Add field via app API
+   curl -X POST "http://your-app/api/admin/search/solr/add-library-field"
+
+   # Then run migration
+   curl -X POST "http://your-app/api/admin/search/solr/migrate-library-schema"
+   ```
+
+3. **Direct Solr API** (if app API fails):
+   ```bash
+   # Add to both cores
+   curl -X POST "http://solr:8983/solr/storycove_stories/schema" \
+     -H "Content-Type: application/json" \
+     -d '{"add-field":{"name":"libraryId","type":"string","indexed":true,"stored":true}}'
+
+   curl -X POST "http://solr:8983/solr/storycove_authors/schema" \
+     -H "Content-Type: application/json" \
+     -d '{"add-field":{"name":"libraryId","type":"string","indexed":true,"stored":true}}'
+   ```
+
+4. **For development**: Use Option 1 (volume reset) for clean restart
+
+### Migration Endpoint Returns Error
+
+Common causes:
+- Solr is not available (check connectivity)
+- No active library context (ensure user is authenticated)
+- Insufficient permissions (check JWT token/authentication)
+
+### Search Results Still Mixed
+
+This indicates incomplete migration:
+- Clear all Solr data and reindex completely
+- Verify that all documents have libraryId field
+- Check that search queries include library filters
+
+## Environment-Specific Notes
+
+### Development
+- Use Option 1 (volume reset) for simplicity
+- Data loss is acceptable in dev environments
+
+### Staging
+- Use Option 2 or 3 to test production migration procedures
+- Verify migration process before applying to production
+
+### Production
+- **Always backup data first**
+- Use Option 2 (Schema API) or Option 3 (Admin endpoint)
+- Plan for brief performance impact during reindexing
+- Monitor system resources during bulk reindexing
+
+## Performance Considerations
+
+- **Reindexing time**: Depends on data size (typically 1000 docs/second)
+- **Memory usage**: May increase during bulk indexing
+- **Search performance**: Minimal impact from library filtering
+- **Storage**: Slight increase due to libraryId field
+
+## Rollback Plan
+
+If issues occur:
+
+1. **Immediate**: Restart Solr to previous state (if using Option 1)
+2. **Schema revert**: Remove libraryId field via Schema API
+3. **Code rollback**: Deploy previous version without library separation
+4. **Data restore**: Restore from backup if necessary
+
+This migration enables proper multi-tenant isolation while maintaining search performance and functionality.

apply_migration_production.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+
+# Run this script on your production server to apply the backup_jobs table migration
+# to all library databases
+
+echo "Applying backup_jobs table migration to all databases..."
+echo ""
+
+# Apply to each database
+for DB in storycove storycove_afterdark storycove_clas storycove_secret; do
+    echo "Applying to $DB..."
+    docker-compose exec -T postgres psql -U storycove -d "$DB" <<'SQL'
+CREATE TABLE IF NOT EXISTS backup_jobs (
+    id UUID PRIMARY KEY,
+    library_id VARCHAR(255) NOT NULL,
+    type VARCHAR(50) NOT NULL CHECK (type IN ('DATABASE_ONLY', 'COMPLETE')),
+    status VARCHAR(50) NOT NULL CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'EXPIRED')),
+    file_path VARCHAR(1000),
+    file_size_bytes BIGINT,
+    progress_percent INTEGER,
+    error_message VARCHAR(1000),
+    created_at TIMESTAMP NOT NULL,
+    started_at TIMESTAMP,
+    completed_at TIMESTAMP,
+    expires_at TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_library_id ON backup_jobs(library_id);
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_status ON backup_jobs(status);
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_expires_at ON backup_jobs(expires_at);
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_created_at ON backup_jobs(created_at DESC);
+SQL
+    echo "✓ Done with $DB"
+    echo ""
+done
+
+echo "Migration complete! Verifying..."
+echo ""
+
+# Verify tables exist
+for DB in storycove storycove_afterdark storycove_clas storycove_secret; do
+    echo "Checking $DB:"
+    docker-compose exec -T postgres psql -U storycove -d "$DB" -c "\d backup_jobs" 2>&1 | grep -E "Table|does not exist" || echo "  ✓ Table exists"
+    echo ""
+done

backend/Dockerfile

@@ -1,9 +1,14 @@
-FROM openjdk:17-jdk-slim
+FROM eclipse-temurin:17-jdk-jammy
 
 WORKDIR /app
 
-# Install Maven
+# Install Maven and PostgreSQL 15 client tools
-RUN apt-get update && apt-get install -y maven && rm -rf /var/lib/apt/lists/*
+RUN apt-get update && apt-get install -y wget ca-certificates gnupg maven && \
+    wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg && \
+    echo "deb http://apt.postgresql.org/pub/repos/apt/ jammy-pgdg main" > /etc/apt/sources.list.d/pgdg.list && \
+    apt-get update && \
+    apt-get install -y postgresql-client-15 && \
+    rm -rf /var/lib/apt/lists/*
 
 # Copy source code
 COPY . .

backend/apply_backup_jobs_migration.sh

@@ -0,0 +1,54 @@
+#!/bin/bash
+
+# Script to apply backup_jobs table migration to all library databases
+# This should be run from the backend directory
+
+set -e
+
+# Use full docker path
+DOCKER="/usr/local/bin/docker"
+
+echo "Applying backup_jobs table migration..."
+
+# Get database connection details from environment or use defaults
+DB_HOST="${POSTGRES_HOST:-postgres}"
+DB_PORT="${POSTGRES_PORT:-5432}"
+DB_USER="${POSTGRES_USER:-storycove}"
+DB_PASSWORD="${POSTGRES_PASSWORD:-password}"
+
+# List of databases to update
+DATABASES=("storycove" "storycove_afterdark")
+
+for DB_NAME in "${DATABASES[@]}"; do
+    echo ""
+    echo "Applying migration to database: $DB_NAME"
+
+    # Check if database exists
+    if $DOCKER exec storycove-postgres-1 psql -U "$DB_USER" -lqt | cut -d \| -f 1 | grep -qw "$DB_NAME"; then
+        echo "Database $DB_NAME exists, applying migration..."
+
+        # Apply migration
+        $DOCKER exec -i storycove-postgres-1 psql -U "$DB_USER" -d "$DB_NAME" < create_backup_jobs_table.sql
+
+        if [ $? -eq 0 ]; then
+            echo "✓ Migration applied successfully to $DB_NAME"
+        else
+            echo "✗ Failed to apply migration to $DB_NAME"
+            exit 1
+        fi
+    else
+        echo "⚠ Database $DB_NAME does not exist, skipping..."
+    fi
+done
+
+echo ""
+echo "Migration complete!"
+echo ""
+echo "Verifying table creation..."
+for DB_NAME in "${DATABASES[@]}"; do
+    if $DOCKER exec storycove-postgres-1 psql -U "$DB_USER" -lqt | cut -d \| -f 1 | grep -qw "$DB_NAME"; then
+        echo ""
+        echo "Checking $DB_NAME:"
+        $DOCKER exec storycove-postgres-1 psql -U "$DB_USER" -d "$DB_NAME" -c "\d backup_jobs" 2>/dev/null || echo "  Table not found in $DB_NAME"
+    fi
+done

backend/create_backup_jobs_table.sql

@@ -0,0 +1,29 @@
+-- Create backup_jobs table for async backup job tracking
+-- This should be run on all library databases (default and afterdark)
+
+CREATE TABLE IF NOT EXISTS backup_jobs (
+    id UUID PRIMARY KEY,
+    library_id VARCHAR(255) NOT NULL,
+    type VARCHAR(50) NOT NULL CHECK (type IN ('DATABASE_ONLY', 'COMPLETE')),
+    status VARCHAR(50) NOT NULL CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'EXPIRED')),
+    file_path VARCHAR(1000),
+    file_size_bytes BIGINT,
+    progress_percent INTEGER,
+    error_message VARCHAR(1000),
+    created_at TIMESTAMP NOT NULL,
+    started_at TIMESTAMP,
+    completed_at TIMESTAMP,
+    expires_at TIMESTAMP
+);
+
+-- Create index on library_id for faster lookups
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_library_id ON backup_jobs(library_id);
+
+-- Create index on status for cleanup queries
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_status ON backup_jobs(status);
+
+-- Create index on expires_at for cleanup queries
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_expires_at ON backup_jobs(expires_at);
+
+-- Create index on created_at for ordering
+CREATE INDEX IF NOT EXISTS idx_backup_jobs_created_at ON backup_jobs(created_at DESC);

backend/pom.xml

@@ -84,9 +84,25 @@
             <artifactId>httpclient5</artifactId>
         </dependency>
         <dependency>
-            <groupId>org.opensearch.client</groupId>
+            <groupId>org.apache.solr</groupId>
-            <artifactId>opensearch-java</artifactId>
+            <artifactId>solr-solrj</artifactId>
-            <version>3.2.0</version>
+            <version>9.9.0</version>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-client</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-util</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-http</artifactId>
+        </dependency>
+        <dependency>
+            <groupId>org.eclipse.jetty</groupId>
+            <artifactId>jetty-io</artifactId>
         </dependency>
         <dependency>
             <groupId>org.apache.httpcomponents.core5</groupId>
@@ -101,7 +117,12 @@
             <artifactId>epublib-core</artifactId>
             <version>3.1</version>
         </dependency>
-        
+        <dependency>
+            <groupId>org.apache.pdfbox</groupId>
+            <artifactId>pdfbox</artifactId>
+            <version>3.0.3</version>
+        </dependency>
+
         <!-- Test dependencies -->
         <dependency>
             <groupId>org.springframework.boot</groupId>

backend/src/main/java/com/storycove/StoryCoveApplication.java

@@ -2,10 +2,12 @@ package com.storycove;
 
 import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
+import org.springframework.scheduling.annotation.EnableAsync;
 import org.springframework.scheduling.annotation.EnableScheduling;
 
 @SpringBootApplication
 @EnableScheduling
+@EnableAsync
 public class StoryCoveApplication {
 
     public static void main(String[] args) {

backend/src/main/java/com/storycove/config/DatabaseMigrationRunner.java

@@ -0,0 +1,111 @@
+package com.storycove.config;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.boot.CommandLineRunner;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+
+import javax.sql.DataSource;
+import java.sql.Connection;
+import java.sql.Statement;
+import java.util.Arrays;
+import java.util.List;
+
+/**
+ * Runs database migrations on application startup.
+ * This ensures all library databases have the required schema,
+ * particularly for tables like backup_jobs that were added after initial deployment.
+ */
+@Component
+@Order(1) // Run early in startup sequence
+public class DatabaseMigrationRunner implements CommandLineRunner {
+
+    private static final Logger logger = LoggerFactory.getLogger(DatabaseMigrationRunner.class);
+
+    @Autowired
+    private DataSource dataSource;
+
+    @Value("${spring.datasource.username}")
+    private String dbUsername;
+
+    @Value("${spring.datasource.password}")
+    private String dbPassword;
+
+    // List of all library databases that need migrations
+    private static final List<String> LIBRARY_DATABASES = Arrays.asList(
+        "storycove",           // default database
+        "storycove_afterdark",
+        "storycove_clas",
+        "storycove_secret"
+    );
+
+    // SQL for backup_jobs table migration (idempotent)
+    private static final String BACKUP_JOBS_MIGRATION = """
+        CREATE TABLE IF NOT EXISTS backup_jobs (
+            id UUID PRIMARY KEY,
+            library_id VARCHAR(255) NOT NULL,
+            type VARCHAR(50) NOT NULL CHECK (type IN ('DATABASE_ONLY', 'COMPLETE')),
+            status VARCHAR(50) NOT NULL CHECK (status IN ('PENDING', 'IN_PROGRESS', 'COMPLETED', 'FAILED', 'EXPIRED')),
+            file_path VARCHAR(1000),
+            file_size_bytes BIGINT,
+            progress_percent INTEGER,
+            error_message VARCHAR(1000),
+            created_at TIMESTAMP NOT NULL,
+            started_at TIMESTAMP,
+            completed_at TIMESTAMP,
+            expires_at TIMESTAMP
+        );
+
+        CREATE INDEX IF NOT EXISTS idx_backup_jobs_library_id ON backup_jobs(library_id);
+        CREATE INDEX IF NOT EXISTS idx_backup_jobs_status ON backup_jobs(status);
+        CREATE INDEX IF NOT EXISTS idx_backup_jobs_expires_at ON backup_jobs(expires_at);
+        CREATE INDEX IF NOT EXISTS idx_backup_jobs_created_at ON backup_jobs(created_at DESC);
+        """;
+
+    @Override
+    public void run(String... args) throws Exception {
+        logger.info("🗄️  Starting database migrations...");
+
+        for (String database : LIBRARY_DATABASES) {
+            try {
+                applyMigrations(database);
+                logger.info("✅ Successfully applied migrations to database: {}", database);
+            } catch (Exception e) {
+                // Log error but don't fail startup if database doesn't exist yet
+                if (e.getMessage() != null && e.getMessage().contains("does not exist")) {
+                    logger.warn("⚠️  Database {} does not exist yet, skipping migrations", database);
+                } else {
+                    logger.error("❌ Failed to apply migrations to database: {}", database, e);
+                    // Don't throw - allow application to start even if some migrations fail
+                }
+            }
+        }
+
+        logger.info("✅ Database migrations completed");
+    }
+
+    private void applyMigrations(String database) throws Exception {
+        // We need to connect directly to each database, not through SmartRoutingDataSource
+        // Build connection URL from the default datasource URL
+        String originalUrl = dataSource.getConnection().getMetaData().getURL();
+        String baseUrl = originalUrl.substring(0, originalUrl.lastIndexOf('/'));
+        String targetUrl = baseUrl + "/" + database;
+
+        // Connect directly to target database using credentials from application properties
+        try (Connection conn = java.sql.DriverManager.getConnection(
+                targetUrl,
+                dbUsername,
+                dbPassword
+        )) {
+            // Apply backup_jobs migration
+            try (Statement stmt = conn.createStatement()) {
+                stmt.execute(BACKUP_JOBS_MIGRATION);
+            }
+
+            logger.debug("Applied backup_jobs migration to {}", database);
+        }
+    }
+}

backend/src/main/java/com/storycove/config/OpenSearchConfig.java

@@ -1,211 +0,0 @@
-package com.storycove.config;
-
-import com.fasterxml.jackson.databind.ObjectMapper;
-import com.fasterxml.jackson.datatype.jsr310.JavaTimeModule;
-import org.apache.hc.client5.http.auth.AuthScope;
-import org.apache.hc.client5.http.auth.UsernamePasswordCredentials;
-import org.apache.hc.client5.http.impl.auth.BasicCredentialsProvider;
-import org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManager;
-import org.apache.hc.client5.http.impl.nio.PoolingAsyncClientConnectionManagerBuilder;
-import org.apache.hc.client5.http.ssl.ClientTlsStrategyBuilder;
-import org.apache.hc.core5.http.HttpHost;
-import org.apache.hc.core5.util.Timeout;
-import org.opensearch.client.json.jackson.JacksonJsonpMapper;
-import org.opensearch.client.opensearch.OpenSearchClient;
-import org.opensearch.client.transport.OpenSearchTransport;
-import org.opensearch.client.transport.httpclient5.ApacheHttpClient5TransportBuilder;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Qualifier;
-import org.springframework.context.annotation.Bean;
-import org.springframework.context.annotation.Configuration;
-
-import javax.net.ssl.SSLContext;
-import javax.net.ssl.TrustManager;
-import javax.net.ssl.X509TrustManager;
-import java.io.FileInputStream;
-import java.security.KeyStore;
-import java.security.cert.X509Certificate;
-
-@Configuration
-public class OpenSearchConfig {
-
-    private static final Logger logger = LoggerFactory.getLogger(OpenSearchConfig.class);
-
-    private final OpenSearchProperties properties;
-
-    public OpenSearchConfig(@Qualifier("openSearchProperties") OpenSearchProperties properties) {
-        this.properties = properties;
-    }
-
-    @Bean
-    public OpenSearchClient openSearchClient() throws Exception {
-        logger.info("Initializing OpenSearch client for profile: {}", properties.getProfile());
-
-        // Create credentials provider
-        BasicCredentialsProvider credentialsProvider = createCredentialsProvider();
-
-        // Create SSL context based on environment
-        SSLContext sslContext = createSSLContext();
-
-        // Create connection manager with pooling
-        PoolingAsyncClientConnectionManager connectionManager = createConnectionManager(sslContext);
-
-        // Create custom ObjectMapper for proper date serialization
-        ObjectMapper objectMapper = new ObjectMapper();
-        objectMapper.registerModule(new JavaTimeModule());
-        objectMapper.disable(com.fasterxml.jackson.databind.SerializationFeature.WRITE_DATES_AS_TIMESTAMPS);
-
-        // Create the transport with all configurations and custom Jackson mapper
-        OpenSearchTransport transport = ApacheHttpClient5TransportBuilder
-            .builder(new HttpHost(properties.getScheme(), properties.getHost(), properties.getPort()))
-            .setMapper(new JacksonJsonpMapper(objectMapper))
-            .setHttpClientConfigCallback(httpClientBuilder -> {
-                // Only set credentials provider if authentication is configured
-                if (properties.getUsername() != null && !properties.getUsername().isEmpty() &&
-                    properties.getPassword() != null && !properties.getPassword().isEmpty()) {
-                    httpClientBuilder.setDefaultCredentialsProvider(credentialsProvider);
-                }
-
-                httpClientBuilder.setConnectionManager(connectionManager);
-
-                // Set timeouts
-                httpClientBuilder.setDefaultRequestConfig(
-                    org.apache.hc.client5.http.config.RequestConfig.custom()
-                        .setConnectionRequestTimeout(Timeout.ofMilliseconds(properties.getConnection().getTimeout()))
-                        .setResponseTimeout(Timeout.ofMilliseconds(properties.getConnection().getSocketTimeout()))
-                        .build()
-                );
-
-                return httpClientBuilder;
-            })
-            .build();
-
-        OpenSearchClient client = new OpenSearchClient(transport);
-
-        // Test connection
-        testConnection(client);
-
-        return client;
-    }
-
-    private BasicCredentialsProvider createCredentialsProvider() {
-        BasicCredentialsProvider credentialsProvider = new BasicCredentialsProvider();
-
-        // Only set credentials if username and password are provided
-        if (properties.getUsername() != null && !properties.getUsername().isEmpty() &&
-            properties.getPassword() != null && !properties.getPassword().isEmpty()) {
-            credentialsProvider.setCredentials(
-                new AuthScope(properties.getHost(), properties.getPort()),
-                new UsernamePasswordCredentials(
-                    properties.getUsername(),
-                    properties.getPassword().toCharArray()
-                )
-            );
-            logger.info("OpenSearch credentials configured for user: {}", properties.getUsername());
-        } else {
-            logger.info("OpenSearch running without authentication (no credentials configured)");
-        }
-
-        return credentialsProvider;
-    }
-
-    private SSLContext createSSLContext() throws Exception {
-        SSLContext sslContext;
-
-        if (isProduction() && !properties.getSecurity().isTrustAllCertificates()) {
-            // Production SSL configuration with proper certificate validation
-            sslContext = createProductionSSLContext();
-        } else {
-            // Development SSL configuration (trust all certificates)
-            sslContext = createDevelopmentSSLContext();
-        }
-
-        return sslContext;
-    }
-
-    private SSLContext createProductionSSLContext() throws Exception {
-        logger.info("Configuring production SSL context with certificate validation");
-
-        SSLContext sslContext = SSLContext.getInstance("TLS");
-
-        // Load custom keystore/truststore if provided
-        if (properties.getSecurity().getTruststorePath() != null) {
-            KeyStore trustStore = KeyStore.getInstance("JKS");
-            try (FileInputStream fis = new FileInputStream(properties.getSecurity().getTruststorePath())) {
-                trustStore.load(fis, properties.getSecurity().getTruststorePassword().toCharArray());
-            }
-
-            javax.net.ssl.TrustManagerFactory tmf =
-                javax.net.ssl.TrustManagerFactory.getInstance(javax.net.ssl.TrustManagerFactory.getDefaultAlgorithm());
-            tmf.init(trustStore);
-
-            sslContext.init(null, tmf.getTrustManagers(), null);
-        } else {
-            // Use default system SSL context for production
-            sslContext.init(null, null, null);
-        }
-
-        return sslContext;
-    }
-
-    private SSLContext createDevelopmentSSLContext() throws Exception {
-        logger.warn("Configuring development SSL context - TRUSTING ALL CERTIFICATES (not for production!)");
-
-        SSLContext sslContext = SSLContext.getInstance("TLS");
-        sslContext.init(null, new TrustManager[] {
-            new X509TrustManager() {
-                public X509Certificate[] getAcceptedIssuers() { return null; }
-                public void checkClientTrusted(X509Certificate[] certs, String authType) {}
-                public void checkServerTrusted(X509Certificate[] certs, String authType) {}
-            }
-        }, null);
-
-        return sslContext;
-    }
-
-    private PoolingAsyncClientConnectionManager createConnectionManager(SSLContext sslContext) {
-        PoolingAsyncClientConnectionManagerBuilder builder = PoolingAsyncClientConnectionManagerBuilder.create();
-
-        // Configure TLS strategy
-        if (properties.getScheme().equals("https")) {
-            if (isProduction() && properties.getSecurity().isSslVerification()) {
-                // Production TLS with hostname verification
-                builder.setTlsStrategy(ClientTlsStrategyBuilder.create()
-                    .setSslContext(sslContext)
-                    .build());
-            } else {
-                // Development TLS without hostname verification
-                builder.setTlsStrategy(ClientTlsStrategyBuilder.create()
-                    .setSslContext(sslContext)
-                    .setHostnameVerifier((hostname, session) -> true)
-                    .build());
-            }
-        }
-
-        PoolingAsyncClientConnectionManager connectionManager = builder.build();
-
-        // Configure connection pool settings
-        connectionManager.setMaxTotal(properties.getConnection().getMaxConnectionsTotal());
-        connectionManager.setDefaultMaxPerRoute(properties.getConnection().getMaxConnectionsPerRoute());
-
-        return connectionManager;
-    }
-
-    private boolean isProduction() {
-        return "production".equalsIgnoreCase(properties.getProfile());
-    }
-
-    private void testConnection(OpenSearchClient client) {
-        try {
-            var response = client.info();
-            logger.info("OpenSearch connection successful - Version: {}, Cluster: {}",
-                response.version().number(),
-                response.clusterName());
-        } catch (Exception e) {
-            logger.warn("OpenSearch connection test failed during initialization: {}", e.getMessage());
-            logger.debug("OpenSearch connection test full error", e);
-            // Don't throw exception here - let the client be created and handle failures in service methods
-        }
-    }
-}

backend/src/main/java/com/storycove/config/OpenSearchProperties.java

@@ -1,164 +0,0 @@
-package com.storycove.config;
-
-import org.springframework.boot.context.properties.ConfigurationProperties;
-import org.springframework.stereotype.Component;
-
-@Component
-@ConfigurationProperties(prefix = "storycove.opensearch")
-public class OpenSearchProperties {
-
-    private String host = "localhost";
-    private int port = 9200;
-    private String scheme = "https";
-    private String username = "admin";
-    private String password;
-    private String profile = "development";
-
-    private Security security = new Security();
-    private Connection connection = new Connection();
-    private Indices indices = new Indices();
-    private Bulk bulk = new Bulk();
-    private Health health = new Health();
-
-    // Getters and setters
-    public String getHost() { return host; }
-    public void setHost(String host) { this.host = host; }
-
-    public int getPort() { return port; }
-    public void setPort(int port) { this.port = port; }
-
-    public String getScheme() { return scheme; }
-    public void setScheme(String scheme) { this.scheme = scheme; }
-
-    public String getUsername() { return username; }
-    public void setUsername(String username) { this.username = username; }
-
-    public String getPassword() { return password; }
-    public void setPassword(String password) { this.password = password; }
-
-    public String getProfile() { return profile; }
-    public void setProfile(String profile) { this.profile = profile; }
-
-    public Security getSecurity() { return security; }
-    public void setSecurity(Security security) { this.security = security; }
-
-    public Connection getConnection() { return connection; }
-    public void setConnection(Connection connection) { this.connection = connection; }
-
-    public Indices getIndices() { return indices; }
-    public void setIndices(Indices indices) { this.indices = indices; }
-
-    public Bulk getBulk() { return bulk; }
-    public void setBulk(Bulk bulk) { this.bulk = bulk; }
-
-    public Health getHealth() { return health; }
-    public void setHealth(Health health) { this.health = health; }
-
-    public static class Security {
-        private boolean sslVerification = false;
-        private boolean trustAllCertificates = true;
-        private String keystorePath;
-        private String keystorePassword;
-        private String truststorePath;
-        private String truststorePassword;
-
-        // Getters and setters
-        public boolean isSslVerification() { return sslVerification; }
-        public void setSslVerification(boolean sslVerification) { this.sslVerification = sslVerification; }
-
-        public boolean isTrustAllCertificates() { return trustAllCertificates; }
-        public void setTrustAllCertificates(boolean trustAllCertificates) { this.trustAllCertificates = trustAllCertificates; }
-
-        public String getKeystorePath() { return keystorePath; }
-        public void setKeystorePath(String keystorePath) { this.keystorePath = keystorePath; }
-
-        public String getKeystorePassword() { return keystorePassword; }
-        public void setKeystorePassword(String keystorePassword) { this.keystorePassword = keystorePassword; }
-
-        public String getTruststorePath() { return truststorePath; }
-        public void setTruststorePath(String truststorePath) { this.truststorePath = truststorePath; }
-
-        public String getTruststorePassword() { return truststorePassword; }
-        public void setTruststorePassword(String truststorePassword) { this.truststorePassword = truststorePassword; }
-    }
-
-    public static class Connection {
-        private int timeout = 30000;
-        private int socketTimeout = 60000;
-        private int maxConnectionsPerRoute = 10;
-        private int maxConnectionsTotal = 30;
-        private boolean retryOnFailure = true;
-        private int maxRetries = 3;
-
-        // Getters and setters
-        public int getTimeout() { return timeout; }
-        public void setTimeout(int timeout) { this.timeout = timeout; }
-
-        public int getSocketTimeout() { return socketTimeout; }
-        public void setSocketTimeout(int socketTimeout) { this.socketTimeout = socketTimeout; }
-
-        public int getMaxConnectionsPerRoute() { return maxConnectionsPerRoute; }
-        public void setMaxConnectionsPerRoute(int maxConnectionsPerRoute) { this.maxConnectionsPerRoute = maxConnectionsPerRoute; }
-
-        public int getMaxConnectionsTotal() { return maxConnectionsTotal; }
-        public void setMaxConnectionsTotal(int maxConnectionsTotal) { this.maxConnectionsTotal = maxConnectionsTotal; }
-
-        public boolean isRetryOnFailure() { return retryOnFailure; }
-        public void setRetryOnFailure(boolean retryOnFailure) { this.retryOnFailure = retryOnFailure; }
-
-        public int getMaxRetries() { return maxRetries; }
-        public void setMaxRetries(int maxRetries) { this.maxRetries = maxRetries; }
-    }
-
-    public static class Indices {
-        private int defaultShards = 1;
-        private int defaultReplicas = 0;
-        private String refreshInterval = "1s";
-
-        // Getters and setters
-        public int getDefaultShards() { return defaultShards; }
-        public void setDefaultShards(int defaultShards) { this.defaultShards = defaultShards; }
-
-        public int getDefaultReplicas() { return defaultReplicas; }
-        public void setDefaultReplicas(int defaultReplicas) { this.defaultReplicas = defaultReplicas; }
-
-        public String getRefreshInterval() { return refreshInterval; }
-        public void setRefreshInterval(String refreshInterval) { this.refreshInterval = refreshInterval; }
-    }
-
-    public static class Bulk {
-        private int actions = 1000;
-        private long size = 5242880; // 5MB
-        private int timeout = 10000;
-        private int concurrentRequests = 1;
-
-        // Getters and setters
-        public int getActions() { return actions; }
-        public void setActions(int actions) { this.actions = actions; }
-
-        public long getSize() { return size; }
-        public void setSize(long size) { this.size = size; }
-
-        public int getTimeout() { return timeout; }
-        public void setTimeout(int timeout) { this.timeout = timeout; }
-
-        public int getConcurrentRequests() { return concurrentRequests; }
-        public void setConcurrentRequests(int concurrentRequests) { this.concurrentRequests = concurrentRequests; }
-    }
-
-    public static class Health {
-        private int checkInterval = 30000;
-        private int slowQueryThreshold = 5000;
-        private boolean enableMetrics = true;
-
-        // Getters and setters
-        public int getCheckInterval() { return checkInterval; }
-        public void setCheckInterval(int checkInterval) { this.checkInterval = checkInterval; }
-
-        public int getSlowQueryThreshold() { return slowQueryThreshold; }
-        public void setSlowQueryThreshold(int slowQueryThreshold) { this.slowQueryThreshold = slowQueryThreshold; }
-
-        public boolean isEnableMetrics() { return enableMetrics; }
-        public void setEnableMetrics(boolean enableMetrics) { this.enableMetrics = enableMetrics; }
-    }
-}

backend/src/main/java/com/storycove/config/SecurityConfig.java

@@ -40,6 +40,8 @@ public class SecurityConfig {
             .sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
             .authorizeHttpRequests(authz -> authz
                 // Public endpoints
+                .requestMatchers("/api/auth/login").permitAll()
+                .requestMatchers("/api/auth/refresh").permitAll() // Allow refresh without access token
                 .requestMatchers("/api/auth/**").permitAll()
                 .requestMatchers("/api/files/images/**").permitAll() // Public image serving
                 .requestMatchers("/api/config/**").permitAll() // Public configuration endpoints

backend/src/main/java/com/storycove/config/SolrConfig.java

@@ -0,0 +1,57 @@
+package com.storycove.config;
+
+import org.apache.solr.client.solrj.SolrClient;
+import org.apache.solr.client.solrj.impl.HttpSolrClient;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@ConditionalOnProperty(
+    value = "storycove.search.engine",
+    havingValue = "solr",
+    matchIfMissing = false
+)
+public class SolrConfig {
+
+    private static final Logger logger = LoggerFactory.getLogger(SolrConfig.class);
+
+    private final SolrProperties properties;
+
+    public SolrConfig(SolrProperties properties) {
+        this.properties = properties;
+    }
+
+    @Bean
+    public SolrClient solrClient() {
+        logger.info("Initializing Solr client with URL: {}", properties.getUrl());
+
+        HttpSolrClient.Builder builder = new HttpSolrClient.Builder(properties.getUrl())
+            .withConnectionTimeout(properties.getConnection().getTimeout())
+            .withSocketTimeout(properties.getConnection().getSocketTimeout());
+
+        SolrClient client = builder.build();
+
+        logger.info("Solr running without authentication");
+
+        // Test connection
+        testConnection(client);
+
+        return client;
+    }
+
+    private void testConnection(SolrClient client) {
+        try {
+            // Test connection by pinging the server
+            var response = client.ping();
+            logger.info("Solr connection successful - Response time: {}ms",
+                response.getElapsedTime());
+        } catch (Exception e) {
+            logger.warn("Solr connection test failed during initialization: {}", e.getMessage());
+            logger.debug("Solr connection test full error", e);
+            // Don't throw exception here - let the client be created and handle failures in service methods
+        }
+    }
+}

backend/src/main/java/com/storycove/config/SolrProperties.java

@@ -0,0 +1,144 @@
+package com.storycove.config;
+
+import org.springframework.boot.context.properties.ConfigurationProperties;
+import org.springframework.stereotype.Component;
+
+@Component
+@ConfigurationProperties(prefix = "storycove.solr")
+public class SolrProperties {
+
+    private String url = "http://localhost:8983/solr";
+    private String username;
+    private String password;
+
+    private Cores cores = new Cores();
+    private Connection connection = new Connection();
+    private Query query = new Query();
+    private Commit commit = new Commit();
+    private Health health = new Health();
+
+    // Getters and setters
+    public String getUrl() { return url; }
+    public void setUrl(String url) { this.url = url; }
+
+    public String getUsername() { return username; }
+    public void setUsername(String username) { this.username = username; }
+
+    public String getPassword() { return password; }
+    public void setPassword(String password) { this.password = password; }
+
+    public Cores getCores() { return cores; }
+    public void setCores(Cores cores) { this.cores = cores; }
+
+    public Connection getConnection() { return connection; }
+    public void setConnection(Connection connection) { this.connection = connection; }
+
+    public Query getQuery() { return query; }
+    public void setQuery(Query query) { this.query = query; }
+
+    public Commit getCommit() { return commit; }
+    public void setCommit(Commit commit) { this.commit = commit; }
+
+    public Health getHealth() { return health; }
+    public void setHealth(Health health) { this.health = health; }
+
+    public static class Cores {
+        private String stories = "storycove_stories";
+        private String authors = "storycove_authors";
+        private String collections = "storycove_collections";
+
+        // Getters and setters
+        public String getStories() { return stories; }
+        public void setStories(String stories) { this.stories = stories; }
+
+        public String getAuthors() { return authors; }
+        public void setAuthors(String authors) { this.authors = authors; }
+
+        public String getCollections() { return collections; }
+        public void setCollections(String collections) { this.collections = collections; }
+    }
+
+    public static class Connection {
+        private int timeout = 30000;
+        private int socketTimeout = 60000;
+        private int maxConnectionsPerRoute = 10;
+        private int maxConnectionsTotal = 30;
+        private boolean retryOnFailure = true;
+        private int maxRetries = 3;
+
+        // Getters and setters
+        public int getTimeout() { return timeout; }
+        public void setTimeout(int timeout) { this.timeout = timeout; }
+
+        public int getSocketTimeout() { return socketTimeout; }
+        public void setSocketTimeout(int socketTimeout) { this.socketTimeout = socketTimeout; }
+
+        public int getMaxConnectionsPerRoute() { return maxConnectionsPerRoute; }
+        public void setMaxConnectionsPerRoute(int maxConnectionsPerRoute) { this.maxConnectionsPerRoute = maxConnectionsPerRoute; }
+
+        public int getMaxConnectionsTotal() { return maxConnectionsTotal; }
+        public void setMaxConnectionsTotal(int maxConnectionsTotal) { this.maxConnectionsTotal = maxConnectionsTotal; }
+
+        public boolean isRetryOnFailure() { return retryOnFailure; }
+        public void setRetryOnFailure(boolean retryOnFailure) { this.retryOnFailure = retryOnFailure; }
+
+        public int getMaxRetries() { return maxRetries; }
+        public void setMaxRetries(int maxRetries) { this.maxRetries = maxRetries; }
+    }
+
+    public static class Query {
+        private int defaultRows = 10;
+        private int maxRows = 1000;
+        private String defaultOperator = "AND";
+        private boolean highlight = true;
+        private boolean facets = true;
+
+        // Getters and setters
+        public int getDefaultRows() { return defaultRows; }
+        public void setDefaultRows(int defaultRows) { this.defaultRows = defaultRows; }
+
+        public int getMaxRows() { return maxRows; }
+        public void setMaxRows(int maxRows) { this.maxRows = maxRows; }
+
+        public String getDefaultOperator() { return defaultOperator; }
+        public void setDefaultOperator(String defaultOperator) { this.defaultOperator = defaultOperator; }
+
+        public boolean isHighlight() { return highlight; }
+        public void setHighlight(boolean highlight) { this.highlight = highlight; }
+
+        public boolean isFacets() { return facets; }
+        public void setFacets(boolean facets) { this.facets = facets; }
+    }
+
+    public static class Commit {
+        private boolean softCommit = true;
+        private int commitWithin = 1000;
+        private boolean waitSearcher = false;
+
+        // Getters and setters
+        public boolean isSoftCommit() { return softCommit; }
+        public void setSoftCommit(boolean softCommit) { this.softCommit = softCommit; }
+
+        public int getCommitWithin() { return commitWithin; }
+        public void setCommitWithin(int commitWithin) { this.commitWithin = commitWithin; }
+
+        public boolean isWaitSearcher() { return waitSearcher; }
+        public void setWaitSearcher(boolean waitSearcher) { this.waitSearcher = waitSearcher; }
+    }
+
+    public static class Health {
+        private int checkInterval = 30000;
+        private int slowQueryThreshold = 5000;
+        private boolean enableMetrics = true;
+
+        // Getters and setters
+        public int getCheckInterval() { return checkInterval; }
+        public void setCheckInterval(int checkInterval) { this.checkInterval = checkInterval; }
+
+        public int getSlowQueryThreshold() { return slowQueryThreshold; }
+        public void setSlowQueryThreshold(int slowQueryThreshold) { this.slowQueryThreshold = slowQueryThreshold; }
+
+        public boolean isEnableMetrics() { return enableMetrics; }
+        public void setEnableMetrics(boolean enableMetrics) { this.enableMetrics = enableMetrics; }
+    }
+}

backend/src/main/java/com/storycove/config/StartupIndexingRunner.java

@@ -0,0 +1,102 @@
+package com.storycove.config;
+
+import com.storycove.entity.Author;
+import com.storycove.entity.Collection;
+import com.storycove.entity.Story;
+import com.storycove.repository.AuthorRepository;
+import com.storycove.repository.CollectionRepository;
+import com.storycove.repository.StoryRepository;
+import com.storycove.service.SearchServiceAdapter;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.ApplicationArguments;
+import org.springframework.boot.ApplicationRunner;
+import org.springframework.stereotype.Component;
+
+import java.util.List;
+
+/**
+ * Automatically performs bulk reindexing of all entities on application startup.
+ * This ensures that the search index is always in sync with the database,
+ * especially after Solr volume recreation during deployment.
+ */
+@Component
+public class StartupIndexingRunner implements ApplicationRunner {
+
+    private static final Logger logger = LoggerFactory.getLogger(StartupIndexingRunner.class);
+
+    @Autowired
+    private SearchServiceAdapter searchServiceAdapter;
+
+    @Autowired
+    private StoryRepository storyRepository;
+
+    @Autowired
+    private AuthorRepository authorRepository;
+
+    @Autowired
+    private CollectionRepository collectionRepository;
+
+    @Override
+    public void run(ApplicationArguments args) throws Exception {
+        logger.info("========================================");
+        logger.info("Starting automatic bulk reindexing...");
+        logger.info("========================================");
+
+        try {
+            // Check if search service is available
+            if (!searchServiceAdapter.isSearchServiceAvailable()) {
+                logger.warn("Search service (Solr) is not available. Skipping bulk reindexing.");
+                logger.warn("Make sure Solr is running and accessible.");
+                return;
+            }
+
+            long startTime = System.currentTimeMillis();
+
+            // Index all stories
+            logger.info("📚 Indexing stories...");
+            List<Story> stories = storyRepository.findAllWithAssociations();
+            if (!stories.isEmpty()) {
+                searchServiceAdapter.bulkIndexStories(stories);
+                logger.info("✅ Indexed {} stories", stories.size());
+            } else {
+                logger.info("ℹ️  No stories to index");
+            }
+
+            // Index all authors
+            logger.info("👤 Indexing authors...");
+            List<Author> authors = authorRepository.findAll();
+            if (!authors.isEmpty()) {
+                searchServiceAdapter.bulkIndexAuthors(authors);
+                logger.info("✅ Indexed {} authors", authors.size());
+            } else {
+                logger.info("ℹ️  No authors to index");
+            }
+
+            // Index all collections
+            logger.info("📂 Indexing collections...");
+            List<Collection> collections = collectionRepository.findAllWithTags();
+            if (!collections.isEmpty()) {
+                searchServiceAdapter.bulkIndexCollections(collections);
+                logger.info("✅ Indexed {} collections", collections.size());
+            } else {
+                logger.info("ℹ️  No collections to index");
+            }
+
+            long duration = System.currentTimeMillis() - startTime;
+            logger.info("========================================");
+            logger.info("✅ Bulk reindexing completed successfully in {}ms", duration);
+            logger.info("📊 Total indexed: {} stories, {} authors, {} collections",
+                stories.size(), authors.size(), collections.size());
+            logger.info("========================================");
+
+        } catch (Exception e) {
+            logger.error("========================================");
+            logger.error("❌ Bulk reindexing failed", e);
+            logger.error("========================================");
+            // Don't throw the exception - let the application start even if indexing fails
+            // This allows the application to be functional even with search issues
+        }
+    }
+}

backend/src/main/java/com/storycove/controller/AdminSearchController.java

@@ -3,7 +3,7 @@ package com.storycove.controller;
 import com.storycove.entity.Author;
 import com.storycove.entity.Story;
 import com.storycove.service.AuthorService;
-import com.storycove.service.OpenSearchService;
+import com.storycove.service.SolrService;
 import com.storycove.service.SearchServiceAdapter;
 import com.storycove.service.StoryService;
 import org.slf4j.Logger;
@@ -16,7 +16,7 @@ import java.util.List;
 import java.util.Map;
 
 /**
- * Admin controller for managing OpenSearch operations.
+ * Admin controller for managing Solr operations.
  * Provides endpoints for reindexing and index management.
  */
 @RestController
@@ -35,7 +35,7 @@ public class AdminSearchController {
     private AuthorService authorService;
 
     @Autowired(required = false)
-    private OpenSearchService openSearchService;
+    private SolrService solrService;
 
     /**
      * Get current search status
@@ -48,7 +48,7 @@ public class AdminSearchController {
             return ResponseEntity.ok(Map.of(
                 "primaryEngine", status.getPrimaryEngine(),
                 "dualWrite", status.isDualWrite(),
-                "openSearchAvailable", status.isOpenSearchAvailable()
+                "solrAvailable", status.isSolrAvailable()
             ));
         } catch (Exception e) {
             logger.error("Error getting search status", e);
@@ -59,17 +59,17 @@ public class AdminSearchController {
     }
 
     /**
-     * Reindex all data in OpenSearch
+     * Reindex all data in Solr
      */
-    @PostMapping("/opensearch/reindex")
+    @PostMapping("/solr/reindex")
-    public ResponseEntity<Map<String, Object>> reindexOpenSearch() {
+    public ResponseEntity<Map<String, Object>> reindexSolr() {
         try {
-            logger.info("Starting OpenSearch full reindex");
+            logger.info("Starting Solr full reindex");
 
             if (!searchServiceAdapter.isSearchServiceAvailable()) {
                 return ResponseEntity.badRequest().body(Map.of(
                     "success", false,
-                    "error", "OpenSearch is not available or healthy"
+                    "error", "Solr is not available or healthy"
                 ));
             }
 
@@ -77,14 +77,14 @@ public class AdminSearchController {
             List<Story> allStories = storyService.findAllWithAssociations();
             List<Author> allAuthors = authorService.findAllWithStories();
 
-            // Bulk index directly in OpenSearch
+            // Bulk index directly in Solr
-            if (openSearchService != null) {
+            if (solrService != null) {
-                openSearchService.bulkIndexStories(allStories);
+                solrService.bulkIndexStories(allStories);
-                openSearchService.bulkIndexAuthors(allAuthors);
+                solrService.bulkIndexAuthors(allAuthors);
             } else {
                 return ResponseEntity.badRequest().body(Map.of(
                     "success", false,
-                    "error", "OpenSearch service not available"
+                    "error", "Solr service not available"
                 ));
             }
 
@@ -92,7 +92,7 @@ public class AdminSearchController {
 
             return ResponseEntity.ok(Map.of(
                 "success", true,
-                "message", String.format("Reindexed %d stories and %d authors in OpenSearch",
+                "message", String.format("Reindexed %d stories and %d authors in Solr",
                     allStories.size(), allAuthors.size()),
                 "storiesCount", allStories.size(),
                 "authorsCount", allAuthors.size(),
@@ -100,36 +100,36 @@ public class AdminSearchController {
             ));
 
         } catch (Exception e) {
-            logger.error("Error during OpenSearch reindex", e);
+            logger.error("Error during Solr reindex", e);
             return ResponseEntity.internalServerError().body(Map.of(
                 "success", false,
-                "error", "OpenSearch reindex failed: " + e.getMessage()
+                "error", "Solr reindex failed: " + e.getMessage()
             ));
         }
     }
 
     /**
-     * Recreate OpenSearch indices
+     * Recreate Solr indices
      */
-    @PostMapping("/opensearch/recreate")
+    @PostMapping("/solr/recreate")
-    public ResponseEntity<Map<String, Object>> recreateOpenSearchIndices() {
+    public ResponseEntity<Map<String, Object>> recreateSolrIndices() {
         try {
-            logger.info("Starting OpenSearch indices recreation");
+            logger.info("Starting Solr indices recreation");
 
             if (!searchServiceAdapter.isSearchServiceAvailable()) {
                 return ResponseEntity.badRequest().body(Map.of(
                     "success", false,
-                    "error", "OpenSearch is not available or healthy"
+                    "error", "Solr is not available or healthy"
                 ));
             }
 
             // Recreate indices
-            if (openSearchService != null) {
+            if (solrService != null) {
-                openSearchService.recreateIndices();
+                solrService.recreateIndices();
             } else {
                 return ResponseEntity.badRequest().body(Map.of(
                     "success", false,
-                    "error", "OpenSearch service not available"
+                    "error", "Solr service not available"
                 ));
             }
 
@@ -138,14 +138,14 @@ public class AdminSearchController {
             List<Author> allAuthors = authorService.findAllWithStories();
 
             // Bulk index after recreation
-            openSearchService.bulkIndexStories(allStories);
+            solrService.bulkIndexStories(allStories);
-            openSearchService.bulkIndexAuthors(allAuthors);
+            solrService.bulkIndexAuthors(allAuthors);
 
             int totalIndexed = allStories.size() + allAuthors.size();
 
             return ResponseEntity.ok(Map.of(
                 "success", true,
-                "message", String.format("Recreated OpenSearch indices and indexed %d stories and %d authors",
+                "message", String.format("Recreated Solr indices and indexed %d stories and %d authors",
                     allStories.size(), allAuthors.size()),
                 "storiesCount", allStories.size(),
                 "authorsCount", allAuthors.size(),
@@ -153,10 +153,156 @@ public class AdminSearchController {
             ));
 
         } catch (Exception e) {
-            logger.error("Error during OpenSearch indices recreation", e);
+            logger.error("Error during Solr indices recreation", e);
             return ResponseEntity.internalServerError().body(Map.of(
                 "success", false,
-                "error", "OpenSearch indices recreation failed: " + e.getMessage()
+                "error", "Solr indices recreation failed: " + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * Add libraryId field to Solr schema via Schema API.
+     * This is a prerequisite for library-aware indexing.
+     */
+    @PostMapping("/solr/add-library-field")
+    public ResponseEntity<Map<String, Object>> addLibraryField() {
+        try {
+            logger.info("Starting Solr libraryId field addition");
+
+            if (!searchServiceAdapter.isSearchServiceAvailable()) {
+                return ResponseEntity.badRequest().body(Map.of(
+                    "success", false,
+                    "error", "Solr is not available or healthy"
+                ));
+            }
+
+            if (solrService == null) {
+                return ResponseEntity.badRequest().body(Map.of(
+                    "success", false,
+                    "error", "Solr service not available"
+                ));
+            }
+
+            // Add the libraryId field to the schema
+            try {
+                solrService.addLibraryIdField();
+                logger.info("libraryId field added successfully to schema");
+
+                return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "libraryId field added successfully to both stories and authors cores",
+                    "note", "You can now run the library schema migration"
+                ));
+
+            } catch (Exception e) {
+                logger.error("Failed to add libraryId field to schema", e);
+                return ResponseEntity.internalServerError().body(Map.of(
+                    "success", false,
+                    "error", "Failed to add libraryId field to schema: " + e.getMessage(),
+                    "details", "Check that Solr is accessible and schema is modifiable"
+                ));
+            }
+
+        } catch (Exception e) {
+            logger.error("Error during libraryId field addition", e);
+            return ResponseEntity.internalServerError().body(Map.of(
+                "success", false,
+                "error", "libraryId field addition failed: " + e.getMessage()
+            ));
+        }
+    }
+
+    /**
+     * Migrate to library-aware Solr schema.
+     * This endpoint handles the migration from non-library-aware to library-aware indexing.
+     * It clears existing data and reindexes with library context.
+     */
+    @PostMapping("/solr/migrate-library-schema")
+    public ResponseEntity<Map<String, Object>> migrateLibrarySchema() {
+        try {
+            logger.info("Starting Solr library schema migration");
+
+            if (!searchServiceAdapter.isSearchServiceAvailable()) {
+                return ResponseEntity.badRequest().body(Map.of(
+                    "success", false,
+                    "error", "Solr is not available or healthy"
+                ));
+            }
+
+            if (solrService == null) {
+                return ResponseEntity.badRequest().body(Map.of(
+                    "success", false,
+                    "error", "Solr service not available"
+                ));
+            }
+
+            logger.info("Adding libraryId field to Solr schema");
+
+            // First, add the libraryId field to the schema via Schema API
+            try {
+                solrService.addLibraryIdField();
+                logger.info("libraryId field added successfully to schema");
+            } catch (Exception e) {
+                logger.error("Failed to add libraryId field to schema", e);
+                return ResponseEntity.badRequest().body(Map.of(
+                    "success", false,
+                    "error", "Failed to add libraryId field to schema: " + e.getMessage(),
+                    "details", "The schema must support the libraryId field before migration"
+                ));
+            }
+
+            logger.info("Clearing existing Solr data for library schema migration");
+
+            // Clear existing data that doesn't have libraryId
+            try {
+                solrService.recreateIndices();
+            } catch (Exception e) {
+                logger.warn("Could not recreate indices (expected in production): {}", e.getMessage());
+                // In production, just clear the data instead
+                try {
+                    solrService.clearAllDocuments();
+                    logger.info("Cleared all documents from Solr cores");
+                } catch (Exception clearError) {
+                    logger.error("Failed to clear documents", clearError);
+                    return ResponseEntity.badRequest().body(Map.of(
+                        "success", false,
+                        "error", "Failed to clear existing data: " + clearError.getMessage()
+                    ));
+                }
+            }
+
+            // Get all data and reindex with library context
+            List<Story> allStories = storyService.findAllWithAssociations();
+            List<Author> allAuthors = authorService.findAllWithStories();
+
+            logger.info("Reindexing {} stories and {} authors with library context",
+                allStories.size(), allAuthors.size());
+
+            // Bulk index everything (will now include libraryId from current library context)
+            solrService.bulkIndexStories(allStories);
+            solrService.bulkIndexAuthors(allAuthors);
+
+            int totalIndexed = allStories.size() + allAuthors.size();
+
+            logger.info("Solr library schema migration completed successfully");
+
+            return ResponseEntity.ok(Map.of(
+                "success", true,
+                "message", String.format("Library schema migration completed. Reindexed %d stories and %d authors with library context.",
+                    allStories.size(), allAuthors.size()),
+                "storiesCount", allStories.size(),
+                "authorsCount", allAuthors.size(),
+                "totalCount", totalIndexed,
+                "note", "Ensure libraryId field exists in Solr schema before running this migration"
+            ));
+
+        } catch (Exception e) {
+            logger.error("Error during Solr library schema migration", e);
+            return ResponseEntity.internalServerError().body(Map.of(
+                "success", false,
+                "error", "Library schema migration failed: " + e.getMessage(),
+                "details", "Make sure the libraryId field has been added to both stories and authors Solr cores"
             ));
         }
     }

backend/src/main/java/com/storycove/controller/AuthController.java

@@ -1,11 +1,17 @@
 package com.storycove.controller;
 
+import com.storycove.entity.RefreshToken;
 import com.storycove.service.LibraryService;
 import com.storycove.service.PasswordAuthenticationService;
+import com.storycove.service.RefreshTokenService;
 import com.storycove.util.JwtUtil;
+import jakarta.servlet.http.Cookie;
+import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
 import jakarta.validation.Valid;
 import jakarta.validation.constraints.NotBlank;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.http.HttpHeaders;
 import org.springframework.http.ResponseCookie;
 import org.springframework.http.ResponseEntity;
@@ -13,59 +19,154 @@ import org.springframework.security.core.Authentication;
 import org.springframework.web.bind.annotation.*;
 
 import java.time.Duration;
+import java.util.Arrays;
+import java.util.Optional;
 
 @RestController
 @RequestMapping("/api/auth")
 public class AuthController {
-    
+
+    private static final Logger logger = LoggerFactory.getLogger(AuthController.class);
+
     private final PasswordAuthenticationService passwordService;
     private final LibraryService libraryService;
     private final JwtUtil jwtUtil;
-    
+    private final RefreshTokenService refreshTokenService;
-    public AuthController(PasswordAuthenticationService passwordService, LibraryService libraryService, JwtUtil jwtUtil) {
+
+    public AuthController(PasswordAuthenticationService passwordService, LibraryService libraryService, JwtUtil jwtUtil, RefreshTokenService refreshTokenService) {
         this.passwordService = passwordService;
         this.libraryService = libraryService;
         this.jwtUtil = jwtUtil;
+        this.refreshTokenService = refreshTokenService;
     }
     
     @PostMapping("/login")
-    public ResponseEntity<?> login(@Valid @RequestBody LoginRequest request, HttpServletResponse response) {
+    public ResponseEntity<?> login(@Valid @RequestBody LoginRequest request, HttpServletRequest httpRequest, HttpServletResponse response) {
         // Use new library-aware authentication
         String token = passwordService.authenticateAndSwitchLibrary(request.getPassword());
-        
+
         if (token != null) {
-            // Set httpOnly cookie
+            // Get library ID from JWT token
-            ResponseCookie cookie = ResponseCookie.from("token", token)
+            String libraryId = jwtUtil.getLibraryIdFromToken(token);
+
+            // Get user agent and IP address for refresh token
+            String userAgent = httpRequest.getHeader("User-Agent");
+            String ipAddress = getClientIpAddress(httpRequest);
+
+            // Create refresh token
+            RefreshToken refreshToken = refreshTokenService.createRefreshToken(libraryId, userAgent, ipAddress);
+
+            // Set access token cookie (24 hours)
+            ResponseCookie accessCookie = ResponseCookie.from("token", token)
                     .httpOnly(true)
                     .secure(false) // Set to true in production with HTTPS
                     .path("/")
                     .maxAge(Duration.ofDays(1))
                     .build();
-            
+
-            response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
+            // Set refresh token cookie (14 days)
-            
+            ResponseCookie refreshCookie = ResponseCookie.from("refreshToken", refreshToken.getToken())
+                    .httpOnly(true)
+                    .secure(false) // Set to true in production with HTTPS
+                    .path("/")
+                    .maxAge(Duration.ofDays(14))
+                    .build();
+
+            response.addHeader(HttpHeaders.SET_COOKIE, accessCookie.toString());
+            response.addHeader(HttpHeaders.SET_COOKIE, refreshCookie.toString());
+
             String libraryInfo = passwordService.getCurrentLibraryInfo();
             return ResponseEntity.ok(new LoginResponse("Authentication successful - " + libraryInfo, token));
         } else {
             return ResponseEntity.status(401).body(new ErrorResponse("Invalid password"));
         }
     }
+
+    @PostMapping("/refresh")
+    public ResponseEntity<?> refresh(HttpServletRequest request, HttpServletResponse response) {
+        // Get refresh token from cookie
+        String refreshTokenString = getRefreshTokenFromCookies(request);
+
+        if (refreshTokenString == null) {
+            return ResponseEntity.status(401).body(new ErrorResponse("Refresh token not found"));
+        }
+
+        // Verify refresh token
+        Optional<RefreshToken> refreshTokenOpt = refreshTokenService.verifyRefreshToken(refreshTokenString);
+
+        if (refreshTokenOpt.isEmpty()) {
+            return ResponseEntity.status(401).body(new ErrorResponse("Invalid or expired refresh token"));
+        }
+
+        RefreshToken refreshToken = refreshTokenOpt.get();
+        String tokenLibraryId = refreshToken.getLibraryId();
+
+        // Check if we need to switch libraries based on refresh token's library ID
+        try {
+            String currentLibraryId = libraryService.getCurrentLibraryId();
+
+            // Switch library if refresh token's library differs from current library
+            // This handles cross-device library switching on token refresh
+            if (tokenLibraryId != null && !tokenLibraryId.equals(currentLibraryId)) {
+                logger.info("Refresh token library '{}' differs from current library '{}', switching libraries",
+                        tokenLibraryId, currentLibraryId);
+                libraryService.switchToLibraryAfterAuthentication(tokenLibraryId);
+            } else if (currentLibraryId == null && tokenLibraryId != null) {
+                // Handle case after backend restart where no library is active
+                logger.info("No active library on refresh, switching to refresh token's library: {}", tokenLibraryId);
+                libraryService.switchToLibraryAfterAuthentication(tokenLibraryId);
+            }
+        } catch (Exception e) {
+            logger.error("Failed to switch library during token refresh: {}", e.getMessage());
+            return ResponseEntity.status(500).body(new ErrorResponse("Failed to switch library: " + e.getMessage()));
+        }
+
+        // Generate new access token
+        String newAccessToken = jwtUtil.generateToken("user", tokenLibraryId);
+
+        // Set new access token cookie
+        ResponseCookie cookie = ResponseCookie.from("token", newAccessToken)
+                .httpOnly(true)
+                .secure(false) // Set to true in production with HTTPS
+                .path("/")
+                .maxAge(Duration.ofDays(1))
+                .build();
+
+        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
+
+        return ResponseEntity.ok(new LoginResponse("Token refreshed successfully", newAccessToken));
+    }
     
     @PostMapping("/logout")
-    public ResponseEntity<?> logout(HttpServletResponse response) {
+    public ResponseEntity<?> logout(HttpServletRequest request, HttpServletResponse response) {
         // Clear authentication state
         libraryService.clearAuthentication();
-        
+
-        // Clear the cookie
+        // Revoke refresh token if present
-        ResponseCookie cookie = ResponseCookie.from("token", "")
+        String refreshTokenString = getRefreshTokenFromCookies(request);
+        if (refreshTokenString != null) {
+            refreshTokenService.findByToken(refreshTokenString).ifPresent(refreshTokenService::revokeToken);
+        }
+
+        // Clear the access token cookie
+        ResponseCookie accessCookie = ResponseCookie.from("token", "")
                 .httpOnly(true)
                 .secure(false)
                 .path("/")
                 .maxAge(Duration.ZERO)
                 .build();
-        
+
-        response.addHeader(HttpHeaders.SET_COOKIE, cookie.toString());
+        // Clear the refresh token cookie
-        
+        ResponseCookie refreshCookie = ResponseCookie.from("refreshToken", "")
+                .httpOnly(true)
+                .secure(false)
+                .path("/")
+                .maxAge(Duration.ZERO)
+                .build();
+
+        response.addHeader(HttpHeaders.SET_COOKIE, accessCookie.toString());
+        response.addHeader(HttpHeaders.SET_COOKIE, refreshCookie.toString());
+
         return ResponseEntity.ok(new MessageResponse("Logged out successfully"));
     }
     
@@ -77,7 +178,34 @@ public class AuthController {
             return ResponseEntity.status(401).body(new ErrorResponse("Token is invalid or expired"));
         }
     }
-    
+
+    // Helper methods
+    private String getRefreshTokenFromCookies(HttpServletRequest request) {
+        if (request.getCookies() == null) {
+            return null;
+        }
+
+        return Arrays.stream(request.getCookies())
+                .filter(cookie -> "refreshToken".equals(cookie.getName()))
+                .map(Cookie::getValue)
+                .findFirst()
+                .orElse(null);
+    }
+
+    private String getClientIpAddress(HttpServletRequest request) {
+        String xForwardedFor = request.getHeader("X-Forwarded-For");
+        if (xForwardedFor != null && !xForwardedFor.isEmpty()) {
+            return xForwardedFor.split(",")[0].trim();
+        }
+
+        String xRealIp = request.getHeader("X-Real-IP");
+        if (xRealIp != null && !xRealIp.isEmpty()) {
+            return xRealIp;
+        }
+
+        return request.getRemoteAddr();
+    }
+
     // DTOs
     public static class LoginRequest {
         @NotBlank(message = "Password is required")

backend/src/main/java/com/storycove/controller/CollectionController.java

@@ -291,7 +291,7 @@ public class CollectionController {
             // Collections are not indexed in search engine yet
             return ResponseEntity.ok(Map.of(
                 "success", true,
-                "message", "Collections indexing not yet implemented in OpenSearch",
+                "message", "Collections indexing not yet implemented in Solr",
                 "count", allCollections.size()
             ));
         } catch (Exception e) {

backend/src/main/java/com/storycove/controller/ConfigController.java

@@ -3,27 +3,43 @@ package com.storycove.controller;
 import com.storycove.dto.HtmlSanitizationConfigDto;
 import com.storycove.service.HtmlSanitizationService;
 import com.storycove.service.ImageService;
+import com.storycove.service.StoryService;
+import com.storycove.entity.Story;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.http.ResponseEntity;
 import org.springframework.web.bind.annotation.*;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 
 import java.util.Map;
+import java.util.List;
+import java.util.HashMap;
+import java.util.Optional;
+import java.util.UUID;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.nio.file.Files;
+import java.io.IOException;
 
 @RestController
 @RequestMapping("/api/config")
 public class ConfigController {
 
+    private static final Logger logger = LoggerFactory.getLogger(ConfigController.class);
+
     private final HtmlSanitizationService htmlSanitizationService;
     private final ImageService imageService;
+    private final StoryService storyService;
 
     @Value("${app.reading.speed.default:200}")
     private int defaultReadingSpeed;
 
     @Autowired
-    public ConfigController(HtmlSanitizationService htmlSanitizationService, ImageService imageService) {
+    public ConfigController(HtmlSanitizationService htmlSanitizationService, ImageService imageService, StoryService storyService) {
         this.htmlSanitizationService = htmlSanitizationService;
         this.imageService = imageService;
+        this.storyService = storyService;
     }
 
     /**
@@ -61,27 +77,55 @@ public class ConfigController {
     @PostMapping("/cleanup/images/preview")
     public ResponseEntity<Map<String, Object>> previewImageCleanup() {
         try {
+            logger.info("Starting image cleanup preview");
             ImageService.ContentImageCleanupResult result = imageService.cleanupOrphanedContentImages(true);
 
-            Map<String, Object> response = Map.of(
+            // Create detailed file information with story relationships
-                "success", true,
+            logger.info("Processing {} orphaned files for detailed information", result.getOrphanedImages().size());
-                "orphanedCount", result.getOrphanedImages().size(),
+            List<Map<String, Object>> orphanedFiles = result.getOrphanedImages().stream()
-                "totalSizeBytes", result.getTotalSizeBytes(),
+                .map(filePath -> {
-                "formattedSize", result.getFormattedSize(),
+                    try {
-                "foldersToDelete", result.getFoldersToDelete(),
+                        return createFileInfo(filePath);
-                "referencedImagesCount", result.getTotalReferencedImages(),
+                    } catch (Exception e) {
-                "errors", result.getErrors(),
+                        logger.error("Error processing file {}: {}", filePath, e.getMessage());
-                "hasErrors", result.hasErrors(),
+                        // Return a basic error entry instead of failing completely
-                "dryRun", true
+                        Map<String, Object> errorEntry = new HashMap<>();
-            );
+                        errorEntry.put("filePath", filePath);
+                        errorEntry.put("fileName", Paths.get(filePath).getFileName().toString());
+                        errorEntry.put("fileSize", 0L);
+                        errorEntry.put("formattedSize", "0 B");
+                        errorEntry.put("storyId", "error");
+                        errorEntry.put("storyTitle", null);
+                        errorEntry.put("storyExists", false);
+                        errorEntry.put("canAccessStory", false);
+                        errorEntry.put("error", e.getMessage());
+                        return errorEntry;
+                    }
+                })
+                .toList();
 
+            // Use HashMap to avoid Map.of() null value issues
+            Map<String, Object> response = new HashMap<>();
+            response.put("success", true);
+            response.put("orphanedCount", result.getOrphanedImages().size());
+            response.put("totalSizeBytes", result.getTotalSizeBytes());
+            response.put("formattedSize", result.getFormattedSize());
+            response.put("foldersToDelete", result.getFoldersToDelete());
+            response.put("referencedImagesCount", result.getTotalReferencedImages());
+            response.put("errors", result.getErrors());
+            response.put("hasErrors", result.hasErrors());
+            response.put("dryRun", true);
+            response.put("orphanedFiles", orphanedFiles);
+
+            logger.info("Image cleanup preview completed successfully");
             return ResponseEntity.ok(response);
 
         } catch (Exception e) {
-            return ResponseEntity.status(500).body(Map.of(
+            logger.error("Failed to preview image cleanup", e);
-                "success", false,
+            Map<String, Object> errorResponse = new HashMap<>();
-                "error", "Failed to preview image cleanup: " + e.getMessage()
+            errorResponse.put("success", false);
-            ));
+            errorResponse.put("error", "Failed to preview image cleanup: " + (e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName()));
+            return ResponseEntity.status(500).body(errorResponse);
         }
     }
 
@@ -114,4 +158,89 @@ public class ConfigController {
             ));
         }
     }
+
+    /**
+     * Create detailed file information for orphaned image including story relationship
+     */
+    private Map<String, Object> createFileInfo(String filePath) {
+        try {
+            Path path = Paths.get(filePath);
+            String fileName = path.getFileName().toString();
+            long fileSize = Files.exists(path) ? Files.size(path) : 0;
+
+            // Extract story UUID from the path (content images are stored in /content/{storyId}/)
+            String storyId = extractStoryIdFromPath(filePath);
+
+            // Look up the story if we have a valid UUID
+            Story relatedStory = null;
+            if (storyId != null) {
+                try {
+                    UUID storyUuid = UUID.fromString(storyId);
+                    relatedStory = storyService.findById(storyUuid);
+                } catch (Exception e) {
+                    logger.debug("Could not find story with ID {}: {}", storyId, e.getMessage());
+                }
+            }
+
+            Map<String, Object> fileInfo = new HashMap<>();
+            fileInfo.put("filePath", filePath);
+            fileInfo.put("fileName", fileName);
+            fileInfo.put("fileSize", fileSize);
+            fileInfo.put("formattedSize", formatBytes(fileSize));
+            fileInfo.put("storyId", storyId != null ? storyId : "unknown");
+            fileInfo.put("storyTitle", relatedStory != null ? relatedStory.getTitle() : null);
+            fileInfo.put("storyExists", relatedStory != null);
+            fileInfo.put("canAccessStory", relatedStory != null);
+
+            return fileInfo;
+        } catch (Exception e) {
+            logger.error("Error creating file info for {}: {}", filePath, e.getMessage());
+            Map<String, Object> errorInfo = new HashMap<>();
+            errorInfo.put("filePath", filePath);
+            errorInfo.put("fileName", Paths.get(filePath).getFileName().toString());
+            errorInfo.put("fileSize", 0L);
+            errorInfo.put("formattedSize", "0 B");
+            errorInfo.put("storyId", "error");
+            errorInfo.put("storyTitle", null);
+            errorInfo.put("storyExists", false);
+            errorInfo.put("canAccessStory", false);
+            errorInfo.put("error", e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName());
+            return errorInfo;
+        }
+    }
+
+    /**
+     * Extract story ID from content image file path
+     */
+    private String extractStoryIdFromPath(String filePath) {
+        try {
+            // Content images are stored in: /path/to/uploads/content/{storyId}/filename.ext
+            Path path = Paths.get(filePath);
+            Path parent = path.getParent();
+            if (parent != null) {
+                String potentialUuid = parent.getFileName().toString();
+                // Basic UUID validation (36 characters with dashes in right places)
+                if (potentialUuid.length() == 36 &&
+                    potentialUuid.charAt(8) == '-' &&
+                    potentialUuid.charAt(13) == '-' &&
+                    potentialUuid.charAt(18) == '-' &&
+                    potentialUuid.charAt(23) == '-') {
+                    return potentialUuid;
+                }
+            }
+        } catch (Exception e) {
+            // Invalid path or other error
+        }
+        return null;
+    }
+
+    /**
+     * Format file size in human readable format
+     */
+    private String formatBytes(long bytes) {
+        if (bytes < 1024) return bytes + " B";
+        if (bytes < 1024 * 1024) return String.format("%.1f KB", bytes / 1024.0);
+        if (bytes < 1024 * 1024 * 1024) return String.format("%.1f MB", bytes / (1024.0 * 1024.0));
+        return String.format("%.1f GB", bytes / (1024.0 * 1024.0 * 1024.0));
+    }
 }

backend/src/main/java/com/storycove/controller/DatabaseController.java

@@ -1,6 +1,8 @@
 package com.storycove.controller;
 
+import com.storycove.service.AsyncBackupService;
 import com.storycove.service.DatabaseManagementService;
+import com.storycove.service.LibraryService;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.core.io.Resource;
 import org.springframework.http.HttpHeaders;
@@ -12,6 +14,7 @@ import org.springframework.web.multipart.MultipartFile;
 import java.io.IOException;
 import java.time.LocalDateTime;
 import java.time.format.DateTimeFormatter;
+import java.util.List;
 import java.util.Map;
 
 @RestController
@@ -21,6 +24,12 @@ public class DatabaseController {
     @Autowired
     private DatabaseManagementService databaseManagementService;
 
+    @Autowired
+    private AsyncBackupService asyncBackupService;
+
+    @Autowired
+    private LibraryService libraryService;
+
     @PostMapping("/backup")
     public ResponseEntity<Resource> backupDatabase() {
         try {
@@ -83,19 +92,141 @@ public class DatabaseController {
     }
 
     @PostMapping("/backup-complete")
-    public ResponseEntity<Resource> backupComplete() {
+    public ResponseEntity<Map<String, Object>> backupCompleteAsync() {
         try {
-            Resource backup = databaseManagementService.createCompleteBackup();
+            String libraryId = libraryService.getCurrentLibraryId();
-            
+            if (libraryId == null) {
-            String timestamp = LocalDateTime.now().format(DateTimeFormatter.ofPattern("yyyy-MM-dd_HH-mm-ss"));
+                return ResponseEntity.badRequest()
-            String filename = "storycove_complete_backup_" + timestamp + ".zip";
+                        .body(Map.of("success", false, "message", "No library selected"));
-            
+            }
+
+            // Start backup job asynchronously
+            com.storycove.entity.BackupJob job = asyncBackupService.startBackupJob(
+                    libraryId,
+                    com.storycove.entity.BackupJob.BackupType.COMPLETE
+            );
+
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "Backup started",
+                    "jobId", job.getId().toString(),
+                    "status", job.getStatus().toString()
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.internalServerError()
+                    .body(Map.of("success", false, "message", "Failed to start backup: " + e.getMessage()));
+        }
+    }
+
+    @GetMapping("/backup-status/{jobId}")
+    public ResponseEntity<Map<String, Object>> getBackupStatus(@PathVariable String jobId) {
+        try {
+            java.util.UUID uuid = java.util.UUID.fromString(jobId);
+            java.util.Optional<com.storycove.entity.BackupJob> jobOpt = asyncBackupService.getJobStatus(uuid);
+
+            if (jobOpt.isEmpty()) {
+                return ResponseEntity.notFound().build();
+            }
+
+            com.storycove.entity.BackupJob job = jobOpt.get();
+
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "jobId", job.getId().toString(),
+                    "status", job.getStatus().toString(),
+                    "progress", job.getProgressPercent(),
+                    "fileSizeBytes", job.getFileSizeBytes() != null ? job.getFileSizeBytes() : 0,
+                    "createdAt", job.getCreatedAt().toString(),
+                    "completedAt", job.getCompletedAt() != null ? job.getCompletedAt().toString() : "",
+                    "errorMessage", job.getErrorMessage() != null ? job.getErrorMessage() : ""
+            ));
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest()
+                    .body(Map.of("success", false, "message", "Invalid job ID"));
+        }
+    }
+
+    @GetMapping("/backup-download/{jobId}")
+    public ResponseEntity<Resource> downloadBackup(@PathVariable String jobId) {
+        try {
+            java.util.UUID uuid = java.util.UUID.fromString(jobId);
+            Resource backup = asyncBackupService.getBackupFile(uuid);
+
+            java.util.Optional<com.storycove.entity.BackupJob> jobOpt = asyncBackupService.getJobStatus(uuid);
+            if (jobOpt.isEmpty()) {
+                return ResponseEntity.notFound().build();
+            }
+
+            com.storycove.entity.BackupJob job = jobOpt.get();
+            String timestamp = job.getCreatedAt().format(DateTimeFormatter.ofPattern("yyyy-MM-dd_HH-mm-ss"));
+            String extension = job.getType() == com.storycove.entity.BackupJob.BackupType.COMPLETE ? "zip" : "sql";
+            String filename = "storycove_backup_" + timestamp + "." + extension;
+
             return ResponseEntity.ok()
                     .header(HttpHeaders.CONTENT_DISPOSITION, "attachment; filename=\"" + filename + "\"")
-                    .header(HttpHeaders.CONTENT_TYPE, "application/zip")
+                    .header(HttpHeaders.CONTENT_TYPE,
+                            job.getType() == com.storycove.entity.BackupJob.BackupType.COMPLETE
+                                    ? "application/zip"
+                                    : "application/sql")
                     .body(backup);
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest().build();
         } catch (Exception e) {
-            throw new RuntimeException("Failed to create complete backup: " + e.getMessage(), e);
+            throw new RuntimeException("Failed to download backup: " + e.getMessage(), e);
+        }
+    }
+
+    @GetMapping("/backup-list")
+    public ResponseEntity<Map<String, Object>> listBackups() {
+        try {
+            String libraryId = libraryService.getCurrentLibraryId();
+            if (libraryId == null) {
+                return ResponseEntity.badRequest()
+                        .body(Map.of("success", false, "message", "No library selected"));
+            }
+
+            List<com.storycove.entity.BackupJob> jobs = asyncBackupService.listBackupJobs(libraryId);
+
+            List<Map<String, Object>> jobsList = jobs.stream()
+                    .map(job -> {
+                        Map<String, Object> jobMap = new java.util.HashMap<>();
+                        jobMap.put("jobId", job.getId().toString());
+                        jobMap.put("type", job.getType().toString());
+                        jobMap.put("status", job.getStatus().toString());
+                        jobMap.put("progress", job.getProgressPercent());
+                        jobMap.put("fileSizeBytes", job.getFileSizeBytes() != null ? job.getFileSizeBytes() : 0L);
+                        jobMap.put("createdAt", job.getCreatedAt().toString());
+                        jobMap.put("completedAt", job.getCompletedAt() != null ? job.getCompletedAt().toString() : "");
+                        return jobMap;
+                    })
+                    .collect(java.util.stream.Collectors.toList());
+
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "backups", jobsList
+            ));
+        } catch (Exception e) {
+            return ResponseEntity.internalServerError()
+                    .body(Map.of("success", false, "message", "Failed to list backups: " + e.getMessage()));
+        }
+    }
+
+    @DeleteMapping("/backup/{jobId}")
+    public ResponseEntity<Map<String, Object>> deleteBackup(@PathVariable String jobId) {
+        try {
+            java.util.UUID uuid = java.util.UUID.fromString(jobId);
+            asyncBackupService.deleteBackupJob(uuid);
+
+            return ResponseEntity.ok(Map.of(
+                    "success", true,
+                    "message", "Backup deleted successfully"
+            ));
+        } catch (IllegalArgumentException e) {
+            return ResponseEntity.badRequest()
+                    .body(Map.of("success", false, "message", "Invalid job ID"));
+        } catch (Exception e) {
+            return ResponseEntity.internalServerError()
+                    .body(Map.of("success", false, "message", "Failed to delete backup: " + e.getMessage()));
         }
     }
 

backend/src/main/java/com/storycove/controller/FileController.java

@@ -2,6 +2,8 @@ package com.storycove.controller;
 
 import com.storycove.service.ImageService;
 import com.storycove.service.LibraryService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.core.io.FileSystemResource;
 import org.springframework.core.io.Resource;
 import org.springframework.http.HttpHeaders;
@@ -21,6 +23,7 @@ import java.util.Map;
 @RestController
 @RequestMapping("/api/files")
 public class FileController {
+    private static final Logger log = LoggerFactory.getLogger(FileController.class);
     
     private final ImageService imageService;
     private final LibraryService libraryService;
@@ -32,7 +35,7 @@ public class FileController {
     
     private String getCurrentLibraryId() {
         String libraryId = libraryService.getCurrentLibraryId();
-        System.out.println("FileController - Current Library ID: " + libraryId);
+        log.debug("FileController - Current Library ID: {}", libraryId);
         return libraryId != null ? libraryId : "default";
     }
     
@@ -48,7 +51,7 @@ public class FileController {
             String imageUrl = "/api/files/images/" + currentLibraryId + "/" + imagePath;
             response.put("url", imageUrl);
             
-            System.out.println("Upload response - path: " + imagePath + ", url: " + imageUrl);
+            log.debug("Upload response - path: {}, url: {}", imagePath, imageUrl);
             
             return ResponseEntity.ok(response);
         } catch (IllegalArgumentException e) {

backend/src/main/java/com/storycove/controller/LibraryStatisticsController.java

@@ -0,0 +1,183 @@
+package com.storycove.controller;
+
+import com.storycove.dto.LibraryOverviewStatsDto;
+import com.storycove.service.LibraryService;
+import com.storycove.service.LibraryStatisticsService;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.http.ResponseEntity;
+import org.springframework.web.bind.annotation.*;
+
+@RestController
+@RequestMapping("/api/libraries/{libraryId}/statistics")
+public class LibraryStatisticsController {
+
+    private static final Logger logger = LoggerFactory.getLogger(LibraryStatisticsController.class);
+
+    @Autowired
+    private LibraryStatisticsService statisticsService;
+
+    @Autowired
+    private LibraryService libraryService;
+
+    /**
+     * Get overview statistics for a library
+     */
+    @GetMapping("/overview")
+    public ResponseEntity<?> getOverviewStatistics(@PathVariable String libraryId) {
+        try {
+            // Verify library exists
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            LibraryOverviewStatsDto stats = statisticsService.getOverviewStatistics(libraryId);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get overview statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get top tags statistics
+     */
+    @GetMapping("/top-tags")
+    public ResponseEntity<?> getTopTagsStatistics(
+            @PathVariable String libraryId,
+            @RequestParam(defaultValue = "20") int limit) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getTopTagsStatistics(libraryId, limit);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get top tags statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get top authors statistics
+     */
+    @GetMapping("/top-authors")
+    public ResponseEntity<?> getTopAuthorsStatistics(
+            @PathVariable String libraryId,
+            @RequestParam(defaultValue = "10") int limit) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getTopAuthorsStatistics(libraryId, limit);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get top authors statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get rating statistics
+     */
+    @GetMapping("/ratings")
+    public ResponseEntity<?> getRatingStatistics(@PathVariable String libraryId) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getRatingStatistics(libraryId);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get rating statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get source domain statistics
+     */
+    @GetMapping("/source-domains")
+    public ResponseEntity<?> getSourceDomainStatistics(
+            @PathVariable String libraryId,
+            @RequestParam(defaultValue = "10") int limit) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getSourceDomainStatistics(libraryId, limit);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get source domain statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get reading progress statistics
+     */
+    @GetMapping("/reading-progress")
+    public ResponseEntity<?> getReadingProgressStatistics(@PathVariable String libraryId) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getReadingProgressStatistics(libraryId);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get reading progress statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    /**
+     * Get reading activity statistics (last week)
+     */
+    @GetMapping("/reading-activity")
+    public ResponseEntity<?> getReadingActivityStatistics(@PathVariable String libraryId) {
+        try {
+            if (libraryService.getLibraryById(libraryId) == null) {
+                return ResponseEntity.notFound().build();
+            }
+
+            var stats = statisticsService.getReadingActivityStatistics(libraryId);
+            return ResponseEntity.ok(stats);
+
+        } catch (Exception e) {
+            logger.error("Failed to get reading activity statistics for library: {}", libraryId, e);
+            return ResponseEntity.internalServerError()
+                    .body(new ErrorResponse("Failed to retrieve statistics: " + e.getMessage()));
+        }
+    }
+
+    // Error response DTO
+    private static class ErrorResponse {
+        private String error;
+
+        public ErrorResponse(String error) {
+            this.error = error;
+        }
+
+        public String getError() {
+            return error;
+        }
+    }
+}

backend/src/main/java/com/storycove/controller/StoryController.java

@@ -12,9 +12,7 @@ import com.storycove.service.*;
 import jakarta.validation.Valid;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.data.domain.Page;
-import org.springframework.data.domain.PageImpl;
 import org.springframework.data.domain.PageRequest;
 import org.springframework.data.domain.Pageable;
 import org.springframework.data.domain.Sort;
@@ -46,17 +44,25 @@ public class StoryController {
     private final ReadingTimeService readingTimeService;
     private final EPUBImportService epubImportService;
     private final EPUBExportService epubExportService;
+    private final PDFImportService pdfImportService;
+    private final ZIPImportService zipImportService;
+    private final AsyncImageProcessingService asyncImageProcessingService;
+    private final ImageProcessingProgressService progressService;
     
-    public StoryController(StoryService storyService, 
+    public StoryController(StoryService storyService,
                           AuthorService authorService,
-                          SeriesService seriesService, 
+                          SeriesService seriesService,
                           HtmlSanitizationService sanitizationService,
                           ImageService imageService,
                           CollectionService collectionService,
                           SearchServiceAdapter searchServiceAdapter,
                           ReadingTimeService readingTimeService,
                           EPUBImportService epubImportService,
-                          EPUBExportService epubExportService) {
+                          EPUBExportService epubExportService,
+                          PDFImportService pdfImportService,
+                          ZIPImportService zipImportService,
+                          AsyncImageProcessingService asyncImageProcessingService,
+                          ImageProcessingProgressService progressService) {
         this.storyService = storyService;
         this.authorService = authorService;
         this.seriesService = seriesService;
@@ -67,6 +73,10 @@ public class StoryController {
         this.readingTimeService = readingTimeService;
         this.epubImportService = epubImportService;
         this.epubExportService = epubExportService;
+        this.pdfImportService = pdfImportService;
+        this.zipImportService = zipImportService;
+        this.asyncImageProcessingService = asyncImageProcessingService;
+        this.progressService = progressService;
     }
     
     @GetMapping
@@ -144,25 +154,33 @@ public class StoryController {
         logger.info("Creating new story: {}", request.getTitle());
         Story story = new Story();
         updateStoryFromRequest(story, request);
-        
+
         Story savedStory = storyService.createWithTagNames(story, request.getTagNames());
+
+        // Process external images in content after saving
+        savedStory = processExternalImagesIfNeeded(savedStory);
+
         logger.info("Successfully created story: {} (ID: {})", savedStory.getTitle(), savedStory.getId());
         return ResponseEntity.status(HttpStatus.CREATED).body(convertToDto(savedStory));
     }
     
     @PutMapping("/{id}")
-    public ResponseEntity<StoryDto> updateStory(@PathVariable UUID id, 
+    public ResponseEntity<StoryDto> updateStory(@PathVariable UUID id,
                                                @Valid @RequestBody UpdateStoryRequest request) {
         logger.info("Updating story: {} (ID: {})", request.getTitle(), id);
-        
+
         // Handle author creation/lookup at controller level before calling service
         if (request.getAuthorName() != null && !request.getAuthorName().trim().isEmpty() && request.getAuthorId() == null) {
             Author author = findOrCreateAuthor(request.getAuthorName().trim());
             request.setAuthorId(author.getId());
             request.setAuthorName(null); // Clear author name since we now have the ID
         }
-        
+
         Story updatedStory = storyService.updateWithTagNames(id, request);
+
+        // Process external images in content after saving
+        updatedStory = processExternalImagesIfNeeded(updatedStory);
+
         logger.info("Successfully updated story: {}", updatedStory.getTitle());
         return ResponseEntity.ok(convertToDto(updatedStory));
     }
@@ -474,7 +492,9 @@ public class StoryController {
             story.setTitle(createReq.getTitle());
             story.setSummary(createReq.getSummary());
             story.setDescription(createReq.getDescription());
+
             story.setContentHtml(sanitizationService.sanitize(createReq.getContentHtml()));
+
             story.setSourceUrl(createReq.getSourceUrl());
             story.setVolume(createReq.getVolume());
             
@@ -577,10 +597,11 @@ public class StoryController {
         dto.setVolume(story.getVolume());
         dto.setCreatedAt(story.getCreatedAt());
         dto.setUpdatedAt(story.getUpdatedAt());
-        
+
         // Reading progress fields
         dto.setIsRead(story.getIsRead());
         dto.setReadingPosition(story.getReadingPosition());
+        dto.setReadingProgressPercentage(calculateReadingProgressPercentage(story));
         dto.setLastReadAt(story.getLastReadAt());
         
         if (story.getAuthor() != null) {
@@ -599,7 +620,27 @@ public class StoryController {
         
         return dto;
     }
-    
+
+    private Integer calculateReadingProgressPercentage(Story story) {
+        if (story.getReadingPosition() == null || story.getReadingPosition() == 0) {
+            return 0;
+        }
+
+        // ALWAYS use contentHtml for consistency (frontend uses contentHtml for position tracking)
+        int totalLength = 0;
+        if (story.getContentHtml() != null && !story.getContentHtml().isEmpty()) {
+            totalLength = story.getContentHtml().length();
+        }
+
+        if (totalLength == 0) {
+            return 0;
+        }
+
+        // Calculate percentage and round to nearest integer
+        int percentage = Math.round((float) story.getReadingPosition() * 100 / totalLength);
+        return Math.min(100, percentage);
+    }
+
     private StoryReadingDto convertToReadingDto(Story story) {
         StoryReadingDto dto = new StoryReadingDto();
         dto.setId(story.getId());
@@ -614,10 +655,11 @@ public class StoryController {
         dto.setVolume(story.getVolume());
         dto.setCreatedAt(story.getCreatedAt());
         dto.setUpdatedAt(story.getUpdatedAt());
-        
+
         // Reading progress fields
         dto.setIsRead(story.getIsRead());
         dto.setReadingPosition(story.getReadingPosition());
+        dto.setReadingProgressPercentage(calculateReadingProgressPercentage(story));
         dto.setLastReadAt(story.getLastReadAt());
         
         if (story.getAuthor() != null) {
@@ -655,8 +697,9 @@ public class StoryController {
         // Reading progress fields
         dto.setIsRead(story.getIsRead());
         dto.setReadingPosition(story.getReadingPosition());
+        dto.setReadingProgressPercentage(calculateReadingProgressPercentage(story));
         dto.setLastReadAt(story.getLastReadAt());
-        
+
         if (story.getAuthor() != null) {
             dto.setAuthorId(story.getAuthor().getId());
             dto.setAuthorName(story.getAuthor().getName());
@@ -706,7 +749,51 @@ public class StoryController {
         
         return dto;
     }
-    
+
+    private Story processExternalImagesIfNeeded(Story story) {
+        try {
+            if (story.getContentHtml() != null && !story.getContentHtml().trim().isEmpty()) {
+                logger.debug("Starting async image processing for story: {}", story.getId());
+
+                // Start async processing - this returns immediately
+                asyncImageProcessingService.processStoryImagesAsync(story.getId(), story.getContentHtml());
+
+                logger.info("Async image processing started for story: {}", story.getId());
+            }
+        } catch (Exception e) {
+            logger.error("Failed to start async image processing for story {}: {}",
+                        story.getId(), e.getMessage(), e);
+            // Don't fail the entire operation if image processing fails
+        }
+
+        return story;
+    }
+
+    @GetMapping("/{id}/image-processing-progress")
+    public ResponseEntity<Map<String, Object>> getImageProcessingProgress(@PathVariable UUID id) {
+        ImageProcessingProgressService.ImageProcessingProgress progress = progressService.getProgress(id);
+
+        if (progress == null) {
+            return ResponseEntity.ok(Map.of(
+                "isProcessing", false,
+                "message", "No active image processing"
+            ));
+        }
+
+        Map<String, Object> response = Map.of(
+            "isProcessing", !progress.isCompleted(),
+            "totalImages", progress.getTotalImages(),
+            "processedImages", progress.getProcessedImages(),
+            "currentImageUrl", progress.getCurrentImageUrl() != null ? progress.getCurrentImageUrl() : "",
+            "status", progress.getStatus(),
+            "progressPercentage", progress.getProgressPercentage(),
+            "completed", progress.isCompleted(),
+            "error", progress.getErrorMessage() != null ? progress.getErrorMessage() : ""
+        );
+
+        return ResponseEntity.ok(response);
+    }
+
     @GetMapping("/check-duplicate")
     public ResponseEntity<Map<String, Object>> checkDuplicate(
             @RequestParam String title,
@@ -826,26 +913,147 @@ public class StoryController {
     @PostMapping("/epub/validate")
     public ResponseEntity<Map<String, Object>> validateEPUBFile(@RequestParam("file") MultipartFile file) {
         logger.info("Validating EPUB file: {}", file.getOriginalFilename());
-        
+
         try {
             List<String> errors = epubImportService.validateEPUBFile(file);
-            
+
             Map<String, Object> response = Map.of(
                 "valid", errors.isEmpty(),
                 "errors", errors,
                 "filename", file.getOriginalFilename(),
                 "size", file.getSize()
             );
-            
+
             return ResponseEntity.ok(response);
-            
+
         } catch (Exception e) {
             logger.error("Error validating EPUB file: {}", e.getMessage(), e);
             return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                 .body(Map.of("error", "Failed to validate EPUB file"));
         }
     }
-    
+
+    // PDF Import endpoint
+    @PostMapping("/pdf/import")
+    public ResponseEntity<FileImportResponse> importPDF(
+            @RequestParam("file") MultipartFile file,
+            @RequestParam(required = false) UUID authorId,
+            @RequestParam(required = false) String authorName,
+            @RequestParam(required = false) UUID seriesId,
+            @RequestParam(required = false) String seriesName,
+            @RequestParam(required = false) Integer seriesVolume,
+            @RequestParam(required = false) List<String> tags,
+            @RequestParam(defaultValue = "true") Boolean createMissingAuthor,
+            @RequestParam(defaultValue = "true") Boolean createMissingSeries,
+            @RequestParam(defaultValue = "true") Boolean extractImages) {
+
+        logger.info("Importing PDF file: {}", file.getOriginalFilename());
+
+        PDFImportRequest request = new PDFImportRequest();
+        request.setPdfFile(file);
+        request.setAuthorId(authorId);
+        request.setAuthorName(authorName);
+        request.setSeriesId(seriesId);
+        request.setSeriesName(seriesName);
+        request.setSeriesVolume(seriesVolume);
+        request.setTags(tags);
+        request.setCreateMissingAuthor(createMissingAuthor);
+        request.setCreateMissingSeries(createMissingSeries);
+        request.setExtractImages(extractImages);
+
+        try {
+            FileImportResponse response = pdfImportService.importPDF(request);
+
+            if (response.isSuccess()) {
+                logger.info("Successfully imported PDF: {} (Story ID: {})",
+                    response.getStoryTitle(), response.getStoryId());
+                return ResponseEntity.ok(response);
+            } else {
+                logger.warn("PDF import failed: {}", response.getMessage());
+                return ResponseEntity.badRequest().body(response);
+            }
+
+        } catch (Exception e) {
+            logger.error("Error importing PDF: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(FileImportResponse.error("Internal server error: " + e.getMessage(), file.getOriginalFilename()));
+        }
+    }
+
+    // Validate PDF file
+    @PostMapping("/pdf/validate")
+    public ResponseEntity<Map<String, Object>> validatePDFFile(@RequestParam("file") MultipartFile file) {
+        logger.info("Validating PDF file: {}", file.getOriginalFilename());
+
+        try {
+            List<String> errors = pdfImportService.validatePDFFile(file);
+
+            Map<String, Object> response = Map.of(
+                "valid", errors.isEmpty(),
+                "errors", errors,
+                "filename", file.getOriginalFilename(),
+                "size", file.getSize()
+            );
+
+            return ResponseEntity.ok(response);
+
+        } catch (Exception e) {
+            logger.error("Error validating PDF file: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(Map.of("error", "Failed to validate PDF file"));
+        }
+    }
+
+    // ZIP Analysis endpoint - Step 1: Upload and analyze ZIP contents
+    @PostMapping("/zip/analyze")
+    public ResponseEntity<ZIPAnalysisResponse> analyzeZIPFile(@RequestParam("file") MultipartFile file) {
+        logger.info("Analyzing ZIP file: {}", file.getOriginalFilename());
+
+        try {
+            ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(file);
+
+            if (response.isSuccess()) {
+                logger.info("Successfully analyzed ZIP file: {} ({} files found)",
+                    file.getOriginalFilename(), response.getTotalFiles());
+                return ResponseEntity.ok(response);
+            } else {
+                logger.warn("ZIP analysis failed: {}", response.getMessage());
+                return ResponseEntity.badRequest().body(response);
+            }
+
+        } catch (Exception e) {
+            logger.error("Error analyzing ZIP file: {}", e.getMessage(), e);
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
+                .body(ZIPAnalysisResponse.error("Internal server error: " + e.getMessage()));
+        }
+    }
+
+    // ZIP Import endpoint - Step 2: Import selected files from analyzed ZIP
+    @PostMapping("/zip/import")
+    public ResponseEntity<ZIPImportResponse> importFromZIP(@Valid @RequestBody ZIPImportRequest request) {
+        logger.info("Importing files from ZIP session: {}", request.getZipSessionId());
+
+        try {
+            ZIPImportResponse response = zipImportService.importFromZIP(request);
+
+            logger.info("ZIP import completed: {} total, {} successful, {} failed",
+                response.getTotalFiles(), response.getSuccessfulImports(), response.getFailedImports());
+
+            if (response.isSuccess()) {
+                return ResponseEntity.ok(response);
+            } else {
+                return ResponseEntity.badRequest().body(response);
+            }
+
+        } catch (Exception e) {
+            logger.error("Error importing from ZIP: {}", e.getMessage(), e);
+            ZIPImportResponse errorResponse = new ZIPImportResponse();
+            errorResponse.setSuccess(false);
+            errorResponse.setMessage("Internal server error: " + e.getMessage());
+            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(errorResponse);
+        }
+    }
+
     // Request DTOs
     public static class CreateStoryRequest {
         private String title;

backend/src/main/java/com/storycove/dto/FileImportResponse.java

@@ -0,0 +1,132 @@
+package com.storycove.dto;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.UUID;
+
+public class FileImportResponse {
+
+    private boolean success;
+    private String message;
+    private UUID storyId;
+    private String storyTitle;
+    private String fileName;
+    private String fileType; // "EPUB" or "PDF"
+    private Integer wordCount;
+    private Integer extractedImages;
+    private List<String> warnings;
+    private List<String> errors;
+
+    public FileImportResponse() {
+        this.warnings = new ArrayList<>();
+        this.errors = new ArrayList<>();
+    }
+
+    public FileImportResponse(boolean success, String message) {
+        this();
+        this.success = success;
+        this.message = message;
+    }
+
+    public static FileImportResponse success(UUID storyId, String storyTitle, String fileType) {
+        FileImportResponse response = new FileImportResponse(true, "File imported successfully");
+        response.setStoryId(storyId);
+        response.setStoryTitle(storyTitle);
+        response.setFileType(fileType);
+        return response;
+    }
+
+    public static FileImportResponse error(String message, String fileName) {
+        FileImportResponse response = new FileImportResponse(false, message);
+        response.setFileName(fileName);
+        return response;
+    }
+
+    public void addWarning(String warning) {
+        this.warnings.add(warning);
+    }
+
+    public void addError(String error) {
+        this.errors.add(error);
+    }
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public void setSuccess(boolean success) {
+        this.success = success;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    public UUID getStoryId() {
+        return storyId;
+    }
+
+    public void setStoryId(UUID storyId) {
+        this.storyId = storyId;
+    }
+
+    public String getStoryTitle() {
+        return storyTitle;
+    }
+
+    public void setStoryTitle(String storyTitle) {
+        this.storyTitle = storyTitle;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public void setFileName(String fileName) {
+        this.fileName = fileName;
+    }
+
+    public String getFileType() {
+        return fileType;
+    }
+
+    public void setFileType(String fileType) {
+        this.fileType = fileType;
+    }
+
+    public Integer getWordCount() {
+        return wordCount;
+    }
+
+    public void setWordCount(Integer wordCount) {
+        this.wordCount = wordCount;
+    }
+
+    public Integer getExtractedImages() {
+        return extractedImages;
+    }
+
+    public void setExtractedImages(Integer extractedImages) {
+        this.extractedImages = extractedImages;
+    }
+
+    public List<String> getWarnings() {
+        return warnings;
+    }
+
+    public void setWarnings(List<String> warnings) {
+        this.warnings = warnings;
+    }
+
+    public List<String> getErrors() {
+        return errors;
+    }
+
+    public void setErrors(List<String> errors) {
+        this.errors = errors;
+    }
+}

backend/src/main/java/com/storycove/dto/FileInfoDto.java

@@ -0,0 +1,76 @@
+package com.storycove.dto;
+
+public class FileInfoDto {
+
+    private String fileName;
+    private String fileType; // "EPUB" or "PDF"
+    private Long fileSize;
+    private String extractedTitle;
+    private String extractedAuthor;
+    private boolean hasMetadata;
+    private String error; // If file couldn't be analyzed
+
+    public FileInfoDto() {}
+
+    public FileInfoDto(String fileName, String fileType, Long fileSize) {
+        this.fileName = fileName;
+        this.fileType = fileType;
+        this.fileSize = fileSize;
+    }
+
+    public String getFileName() {
+        return fileName;
+    }
+
+    public void setFileName(String fileName) {
+        this.fileName = fileName;
+    }
+
+    public String getFileType() {
+        return fileType;
+    }
+
+    public void setFileType(String fileType) {
+        this.fileType = fileType;
+    }
+
+    public Long getFileSize() {
+        return fileSize;
+    }
+
+    public void setFileSize(Long fileSize) {
+        this.fileSize = fileSize;
+    }
+
+    public String getExtractedTitle() {
+        return extractedTitle;
+    }
+
+    public void setExtractedTitle(String extractedTitle) {
+        this.extractedTitle = extractedTitle;
+    }
+
+    public String getExtractedAuthor() {
+        return extractedAuthor;
+    }
+
+    public void setExtractedAuthor(String extractedAuthor) {
+        this.extractedAuthor = extractedAuthor;
+    }
+
+    public boolean isHasMetadata() {
+        return hasMetadata;
+    }
+
+    public void setHasMetadata(boolean hasMetadata) {
+        this.hasMetadata = hasMetadata;
+    }
+
+    public String getError() {
+        return error;
+    }
+
+    public void setError(String error) {
+        this.error = error;
+    }
+}

backend/src/main/java/com/storycove/dto/LibraryOverviewStatsDto.java

@@ -0,0 +1,183 @@
+package com.storycove.dto;
+
+public class LibraryOverviewStatsDto {
+
+    // Collection Overview
+    private long totalStories;
+    private long totalAuthors;
+    private long totalSeries;
+    private long totalTags;
+    private long totalCollections;
+    private long uniqueSourceDomains;
+
+    // Content Metrics
+    private long totalWordCount;
+    private double averageWordsPerStory;
+    private StoryWordCountDto longestStory;
+    private StoryWordCountDto shortestStory;
+
+    // Reading Time (based on 250 words/minute)
+    private long totalReadingTimeMinutes;
+    private double averageReadingTimeMinutes;
+
+    // Constructor
+    public LibraryOverviewStatsDto() {
+    }
+
+    // Getters and Setters
+    public long getTotalStories() {
+        return totalStories;
+    }
+
+    public void setTotalStories(long totalStories) {
+        this.totalStories = totalStories;
+    }
+
+    public long getTotalAuthors() {
+        return totalAuthors;
+    }
+
+    public void setTotalAuthors(long totalAuthors) {
+        this.totalAuthors = totalAuthors;
+    }
+
+    public long getTotalSeries() {
+        return totalSeries;
+    }
+
+    public void setTotalSeries(long totalSeries) {
+        this.totalSeries = totalSeries;
+    }
+
+    public long getTotalTags() {
+        return totalTags;
+    }
+
+    public void setTotalTags(long totalTags) {
+        this.totalTags = totalTags;
+    }
+
+    public long getTotalCollections() {
+        return totalCollections;
+    }
+
+    public void setTotalCollections(long totalCollections) {
+        this.totalCollections = totalCollections;
+    }
+
+    public long getUniqueSourceDomains() {
+        return uniqueSourceDomains;
+    }
+
+    public void setUniqueSourceDomains(long uniqueSourceDomains) {
+        this.uniqueSourceDomains = uniqueSourceDomains;
+    }
+
+    public long getTotalWordCount() {
+        return totalWordCount;
+    }
+
+    public void setTotalWordCount(long totalWordCount) {
+        this.totalWordCount = totalWordCount;
+    }
+
+    public double getAverageWordsPerStory() {
+        return averageWordsPerStory;
+    }
+
+    public void setAverageWordsPerStory(double averageWordsPerStory) {
+        this.averageWordsPerStory = averageWordsPerStory;
+    }
+
+    public StoryWordCountDto getLongestStory() {
+        return longestStory;
+    }
+
+    public void setLongestStory(StoryWordCountDto longestStory) {
+        this.longestStory = longestStory;
+    }
+
+    public StoryWordCountDto getShortestStory() {
+        return shortestStory;
+    }
+
+    public void setShortestStory(StoryWordCountDto shortestStory) {
+        this.shortestStory = shortestStory;
+    }
+
+    public long getTotalReadingTimeMinutes() {
+        return totalReadingTimeMinutes;
+    }
+
+    public void setTotalReadingTimeMinutes(long totalReadingTimeMinutes) {
+        this.totalReadingTimeMinutes = totalReadingTimeMinutes;
+    }
+
+    public double getAverageReadingTimeMinutes() {
+        return averageReadingTimeMinutes;
+    }
+
+    public void setAverageReadingTimeMinutes(double averageReadingTimeMinutes) {
+        this.averageReadingTimeMinutes = averageReadingTimeMinutes;
+    }
+
+    // Nested DTO for story word count info
+    public static class StoryWordCountDto {
+        private String id;
+        private String title;
+        private String authorName;
+        private int wordCount;
+        private long readingTimeMinutes;
+
+        public StoryWordCountDto() {
+        }
+
+        public StoryWordCountDto(String id, String title, String authorName, int wordCount, long readingTimeMinutes) {
+            this.id = id;
+            this.title = title;
+            this.authorName = authorName;
+            this.wordCount = wordCount;
+            this.readingTimeMinutes = readingTimeMinutes;
+        }
+
+        public String getId() {
+            return id;
+        }
+
+        public void setId(String id) {
+            this.id = id;
+        }
+
+        public String getTitle() {
+            return title;
+        }
+
+        public void setTitle(String title) {
+            this.title = title;
+        }
+
+        public String getAuthorName() {
+            return authorName;
+        }
+
+        public void setAuthorName(String authorName) {
+            this.authorName = authorName;
+        }
+
+        public int getWordCount() {
+            return wordCount;
+        }
+
+        public void setWordCount(int wordCount) {
+            this.wordCount = wordCount;
+        }
+
+        public long getReadingTimeMinutes() {
+            return readingTimeMinutes;
+        }
+
+        public void setReadingTimeMinutes(long readingTimeMinutes) {
+            this.readingTimeMinutes = readingTimeMinutes;
+        }
+    }
+}

backend/src/main/java/com/storycove/dto/PDFImportRequest.java

@@ -0,0 +1,113 @@
+package com.storycove.dto;
+
+import jakarta.validation.constraints.NotNull;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.util.List;
+import java.util.UUID;
+
+public class PDFImportRequest {
+
+    @NotNull(message = "PDF file is required")
+    private MultipartFile pdfFile;
+
+    private UUID authorId;
+
+    private String authorName;
+
+    private UUID seriesId;
+
+    private String seriesName;
+
+    private Integer seriesVolume;
+
+    private List<String> tags;
+
+    private Boolean createMissingAuthor = true;
+
+    private Boolean createMissingSeries = true;
+
+    private Boolean extractImages = true;
+
+    public PDFImportRequest() {}
+
+    public MultipartFile getPdfFile() {
+        return pdfFile;
+    }
+
+    public void setPdfFile(MultipartFile pdfFile) {
+        this.pdfFile = pdfFile;
+    }
+
+    public UUID getAuthorId() {
+        return authorId;
+    }
+
+    public void setAuthorId(UUID authorId) {
+        this.authorId = authorId;
+    }
+
+    public String getAuthorName() {
+        return authorName;
+    }
+
+    public void setAuthorName(String authorName) {
+        this.authorName = authorName;
+    }
+
+    public UUID getSeriesId() {
+        return seriesId;
+    }
+
+    public void setSeriesId(UUID seriesId) {
+        this.seriesId = seriesId;
+    }
+
+    public String getSeriesName() {
+        return seriesName;
+    }
+
+    public void setSeriesName(String seriesName) {
+        this.seriesName = seriesName;
+    }
+
+    public Integer getSeriesVolume() {
+        return seriesVolume;
+    }
+
+    public void setSeriesVolume(Integer seriesVolume) {
+        this.seriesVolume = seriesVolume;
+    }
+
+    public List<String> getTags() {
+        return tags;
+    }
+
+    public void setTags(List<String> tags) {
+        this.tags = tags;
+    }
+
+    public Boolean getCreateMissingAuthor() {
+        return createMissingAuthor;
+    }
+
+    public void setCreateMissingAuthor(Boolean createMissingAuthor) {
+        this.createMissingAuthor = createMissingAuthor;
+    }
+
+    public Boolean getCreateMissingSeries() {
+        return createMissingSeries;
+    }
+
+    public void setCreateMissingSeries(Boolean createMissingSeries) {
+        this.createMissingSeries = createMissingSeries;
+    }
+
+    public Boolean getExtractImages() {
+        return extractImages;
+    }
+
+    public void setExtractImages(Boolean extractImages) {
+        this.extractImages = extractImages;
+    }
+}

backend/src/main/java/com/storycove/dto/RatingStatsDto.java

@@ -0,0 +1,45 @@
+package com.storycove.dto;
+
+import java.util.Map;
+
+public class RatingStatsDto {
+    private double averageRating;
+    private long totalRatedStories;
+    private long totalUnratedStories;
+    private Map<Integer, Long> ratingDistribution; // rating (1-5) -> count
+
+    public RatingStatsDto() {
+    }
+
+    public double getAverageRating() {
+        return averageRating;
+    }
+
+    public void setAverageRating(double averageRating) {
+        this.averageRating = averageRating;
+    }
+
+    public long getTotalRatedStories() {
+        return totalRatedStories;
+    }
+
+    public void setTotalRatedStories(long totalRatedStories) {
+        this.totalRatedStories = totalRatedStories;
+    }
+
+    public long getTotalUnratedStories() {
+        return totalUnratedStories;
+    }
+
+    public void setTotalUnratedStories(long totalUnratedStories) {
+        this.totalUnratedStories = totalUnratedStories;
+    }
+
+    public Map<Integer, Long> getRatingDistribution() {
+        return ratingDistribution;
+    }
+
+    public void setRatingDistribution(Map<Integer, Long> ratingDistribution) {
+        this.ratingDistribution = ratingDistribution;
+    }
+}

backend/src/main/java/com/storycove/dto/ReadingActivityStatsDto.java

@@ -0,0 +1,84 @@
+package com.storycove.dto;
+
+import java.util.List;
+
+public class ReadingActivityStatsDto {
+    private long storiesReadLastWeek;
+    private long wordsReadLastWeek;
+    private long readingTimeMinutesLastWeek;
+    private List<DailyActivityDto> dailyActivity;
+
+    public ReadingActivityStatsDto() {
+    }
+
+    public long getStoriesReadLastWeek() {
+        return storiesReadLastWeek;
+    }
+
+    public void setStoriesReadLastWeek(long storiesReadLastWeek) {
+        this.storiesReadLastWeek = storiesReadLastWeek;
+    }
+
+    public long getWordsReadLastWeek() {
+        return wordsReadLastWeek;
+    }
+
+    public void setWordsReadLastWeek(long wordsReadLastWeek) {
+        this.wordsReadLastWeek = wordsReadLastWeek;
+    }
+
+    public long getReadingTimeMinutesLastWeek() {
+        return readingTimeMinutesLastWeek;
+    }
+
+    public void setReadingTimeMinutesLastWeek(long readingTimeMinutesLastWeek) {
+        this.readingTimeMinutesLastWeek = readingTimeMinutesLastWeek;
+    }
+
+    public List<DailyActivityDto> getDailyActivity() {
+        return dailyActivity;
+    }
+
+    public void setDailyActivity(List<DailyActivityDto> dailyActivity) {
+        this.dailyActivity = dailyActivity;
+    }
+
+    public static class DailyActivityDto {
+        private String date; // YYYY-MM-DD format
+        private long storiesRead;
+        private long wordsRead;
+
+        public DailyActivityDto() {
+        }
+
+        public DailyActivityDto(String date, long storiesRead, long wordsRead) {
+            this.date = date;
+            this.storiesRead = storiesRead;
+            this.wordsRead = wordsRead;
+        }
+
+        public String getDate() {
+            return date;
+        }
+
+        public void setDate(String date) {
+            this.date = date;
+        }
+
+        public long getStoriesRead() {
+            return storiesRead;
+        }
+
+        public void setStoriesRead(long storiesRead) {
+            this.storiesRead = storiesRead;
+        }
+
+        public long getWordsRead() {
+            return wordsRead;
+        }
+
+        public void setWordsRead(long wordsRead) {
+            this.wordsRead = wordsRead;
+        }
+    }
+}

backend/src/main/java/com/storycove/dto/ReadingProgressStatsDto.java

@@ -0,0 +1,61 @@
+package com.storycove.dto;
+
+public class ReadingProgressStatsDto {
+    private long totalStories;
+    private long readStories;
+    private long unreadStories;
+    private double percentageRead;
+    private long totalWordsRead;
+    private long totalWordsUnread;
+
+    public ReadingProgressStatsDto() {
+    }
+
+    public long getTotalStories() {
+        return totalStories;
+    }
+
+    public void setTotalStories(long totalStories) {
+        this.totalStories = totalStories;
+    }
+
+    public long getReadStories() {
+        return readStories;
+    }
+
+    public void setReadStories(long readStories) {
+        this.readStories = readStories;
+    }
+
+    public long getUnreadStories() {
+        return unreadStories;
+    }
+
+    public void setUnreadStories(long unreadStories) {
+        this.unreadStories = unreadStories;
+    }
+
+    public double getPercentageRead() {
+        return percentageRead;
+    }
+
+    public void setPercentageRead(double percentageRead) {
+        this.percentageRead = percentageRead;
+    }
+
+    public long getTotalWordsRead() {
+        return totalWordsRead;
+    }
+
+    public void setTotalWordsRead(long totalWordsRead) {
+        this.totalWordsRead = totalWordsRead;
+    }
+
+    public long getTotalWordsUnread() {
+        return totalWordsUnread;
+    }
+
+    public void setTotalWordsUnread(long totalWordsUnread) {
+        this.totalWordsUnread = totalWordsUnread;
+    }
+}

backend/src/main/java/com/storycove/dto/SearchResultDto.java

@@ -33,6 +33,18 @@ public class SearchResultDto<T> {
         this.searchTimeMs = searchTimeMs;
         this.facets = facets;
     }
+
+    // Simple constructor for basic search results with facet list
+    public SearchResultDto(List<T> results, long totalHits, int resultCount, List<FacetCountDto> facetsList) {
+        this.results = results;
+        this.totalHits = totalHits;
+        this.page = 0;
+        this.perPage = resultCount;
+        this.query = "";
+        this.searchTimeMs = 0;
+        // Convert list to map if needed - for now just set empty map
+        this.facets = java.util.Collections.emptyMap();
+    }
     
     // Getters and Setters
     public List<T> getResults() {

backend/src/main/java/com/storycove/dto/SourceDomainStatsDto.java

@@ -0,0 +1,65 @@
+package com.storycove.dto;
+
+import java.util.List;
+
+public class SourceDomainStatsDto {
+    private List<DomainStatsDto> topDomains;
+    private long storiesWithSource;
+    private long storiesWithoutSource;
+
+    public SourceDomainStatsDto() {
+    }
+
+    public List<DomainStatsDto> getTopDomains() {
+        return topDomains;
+    }
+
+    public void setTopDomains(List<DomainStatsDto> topDomains) {
+        this.topDomains = topDomains;
+    }
+
+    public long getStoriesWithSource() {
+        return storiesWithSource;
+    }
+
+    public void setStoriesWithSource(long storiesWithSource) {
+        this.storiesWithSource = storiesWithSource;
+    }
+
+    public long getStoriesWithoutSource() {
+        return storiesWithoutSource;
+    }
+
+    public void setStoriesWithoutSource(long storiesWithoutSource) {
+        this.storiesWithoutSource = storiesWithoutSource;
+    }
+
+    public static class DomainStatsDto {
+        private String domain;
+        private long storyCount;
+
+        public DomainStatsDto() {
+        }
+
+        public DomainStatsDto(String domain, long storyCount) {
+            this.domain = domain;
+            this.storyCount = storyCount;
+        }
+
+        public String getDomain() {
+            return domain;
+        }
+
+        public void setDomain(String domain) {
+            this.domain = domain;
+        }
+
+        public long getStoryCount() {
+            return storyCount;
+        }
+
+        public void setStoryCount(long storyCount) {
+            this.storyCount = storyCount;
+        }
+    }
+}

backend/src/main/java/com/storycove/dto/StoryDto.java

@@ -31,6 +31,7 @@ public class StoryDto {
     // Reading progress fields
     private Boolean isRead;
     private Integer readingPosition;
+    private Integer readingProgressPercentage; // Pre-calculated percentage (0-100)
     private LocalDateTime lastReadAt;
     
     // Related entities as simple references
@@ -146,7 +147,15 @@ public class StoryDto {
     public void setReadingPosition(Integer readingPosition) {
         this.readingPosition = readingPosition;
     }
-    
+
+    public Integer getReadingProgressPercentage() {
+        return readingProgressPercentage;
+    }
+
+    public void setReadingProgressPercentage(Integer readingProgressPercentage) {
+        this.readingProgressPercentage = readingProgressPercentage;
+    }
+
     public LocalDateTime getLastReadAt() {
         return lastReadAt;
     }

backend/src/main/java/com/storycove/dto/StoryReadingDto.java

@@ -25,6 +25,7 @@ public class StoryReadingDto {
     // Reading progress fields
     private Boolean isRead;
     private Integer readingPosition;
+    private Integer readingProgressPercentage; // Pre-calculated percentage (0-100)
     private LocalDateTime lastReadAt;
     
     // Related entities as simple references
@@ -135,7 +136,15 @@ public class StoryReadingDto {
     public void setReadingPosition(Integer readingPosition) {
         this.readingPosition = readingPosition;
     }
-    
+
+    public Integer getReadingProgressPercentage() {
+        return readingProgressPercentage;
+    }
+
+    public void setReadingProgressPercentage(Integer readingProgressPercentage) {
+        this.readingProgressPercentage = readingProgressPercentage;
+    }
+
     public LocalDateTime getLastReadAt() {
         return lastReadAt;
     }

backend/src/main/java/com/storycove/dto/StorySearchDto.java

@@ -18,6 +18,7 @@ public class StorySearchDto {
     // Reading status
     private Boolean isRead;
     private Integer readingPosition;
+    private Integer readingProgressPercentage; // Pre-calculated percentage (0-100)
     private LocalDateTime lastReadAt;
     
     // Author info
@@ -132,7 +133,15 @@ public class StorySearchDto {
     public void setReadingPosition(Integer readingPosition) {
         this.readingPosition = readingPosition;
     }
-    
+
+    public Integer getReadingProgressPercentage() {
+        return readingProgressPercentage;
+    }
+
+    public void setReadingProgressPercentage(Integer readingProgressPercentage) {
+        this.readingProgressPercentage = readingProgressPercentage;
+    }
+
     public UUID getAuthorId() {
         return authorId;
     }

backend/src/main/java/com/storycove/dto/StorySummaryDto.java

@@ -23,6 +23,7 @@ public class StorySummaryDto {
     // Reading progress fields
     private Boolean isRead;
     private Integer readingPosition;
+    private Integer readingProgressPercentage; // Pre-calculated percentage (0-100)
     private LocalDateTime lastReadAt;
     
     // Related entities as simple references
@@ -122,11 +123,19 @@ public class StorySummaryDto {
     public Integer getReadingPosition() {
         return readingPosition;
     }
-    
+
     public void setReadingPosition(Integer readingPosition) {
         this.readingPosition = readingPosition;
     }
-    
+
+    public Integer getReadingProgressPercentage() {
+        return readingProgressPercentage;
+    }
+
+    public void setReadingProgressPercentage(Integer readingProgressPercentage) {
+        this.readingProgressPercentage = readingProgressPercentage;
+    }
+
     public LocalDateTime getLastReadAt() {
         return lastReadAt;
     }

backend/src/main/java/com/storycove/dto/TopAuthorsStatsDto.java

@@ -0,0 +1,76 @@
+package com.storycove.dto;
+
+import java.util.List;
+
+public class TopAuthorsStatsDto {
+    private List<AuthorStatsDto> topAuthorsByStories;
+    private List<AuthorStatsDto> topAuthorsByWords;
+
+    public TopAuthorsStatsDto() {
+    }
+
+    public List<AuthorStatsDto> getTopAuthorsByStories() {
+        return topAuthorsByStories;
+    }
+
+    public void setTopAuthorsByStories(List<AuthorStatsDto> topAuthorsByStories) {
+        this.topAuthorsByStories = topAuthorsByStories;
+    }
+
+    public List<AuthorStatsDto> getTopAuthorsByWords() {
+        return topAuthorsByWords;
+    }
+
+    public void setTopAuthorsByWords(List<AuthorStatsDto> topAuthorsByWords) {
+        this.topAuthorsByWords = topAuthorsByWords;
+    }
+
+    public static class AuthorStatsDto {
+        private String authorId;
+        private String authorName;
+        private long storyCount;
+        private long totalWords;
+
+        public AuthorStatsDto() {
+        }
+
+        public AuthorStatsDto(String authorId, String authorName, long storyCount, long totalWords) {
+            this.authorId = authorId;
+            this.authorName = authorName;
+            this.storyCount = storyCount;
+            this.totalWords = totalWords;
+        }
+
+        public String getAuthorId() {
+            return authorId;
+        }
+
+        public void setAuthorId(String authorId) {
+            this.authorId = authorId;
+        }
+
+        public String getAuthorName() {
+            return authorName;
+        }
+
+        public void setAuthorName(String authorName) {
+            this.authorName = authorName;
+        }
+
+        public long getStoryCount() {
+            return storyCount;
+        }
+
+        public void setStoryCount(long storyCount) {
+            this.storyCount = storyCount;
+        }
+
+        public long getTotalWords() {
+            return totalWords;
+        }
+
+        public void setTotalWords(long totalWords) {
+            this.totalWords = totalWords;
+        }
+    }
+}

backend/src/main/java/com/storycove/dto/TopTagsStatsDto.java

@@ -0,0 +1,51 @@
+package com.storycove.dto;
+
+import java.util.List;
+
+public class TopTagsStatsDto {
+    private List<TagStatsDto> topTags;
+
+    public TopTagsStatsDto() {
+    }
+
+    public TopTagsStatsDto(List<TagStatsDto> topTags) {
+        this.topTags = topTags;
+    }
+
+    public List<TagStatsDto> getTopTags() {
+        return topTags;
+    }
+
+    public void setTopTags(List<TagStatsDto> topTags) {
+        this.topTags = topTags;
+    }
+
+    public static class TagStatsDto {
+        private String tagName;
+        private long storyCount;
+
+        public TagStatsDto() {
+        }
+
+        public TagStatsDto(String tagName, long storyCount) {
+            this.tagName = tagName;
+            this.storyCount = storyCount;
+        }
+
+        public String getTagName() {
+            return tagName;
+        }
+
+        public void setTagName(String tagName) {
+            this.tagName = tagName;
+        }
+
+        public long getStoryCount() {
+            return storyCount;
+        }
+
+        public void setStoryCount(long storyCount) {
+            this.storyCount = storyCount;
+        }
+    }
+}

backend/src/main/java/com/storycove/dto/ZIPAnalysisResponse.java

@@ -0,0 +1,98 @@
+package com.storycove.dto;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class ZIPAnalysisResponse {
+
+    private boolean success;
+    private String message;
+    private String zipFileName;
+    private int totalFiles;
+    private int validFiles;
+    private List<FileInfoDto> files;
+    private List<String> warnings;
+
+    public ZIPAnalysisResponse() {
+        this.files = new ArrayList<>();
+        this.warnings = new ArrayList<>();
+    }
+
+    public static ZIPAnalysisResponse success(String zipFileName, List<FileInfoDto> files) {
+        ZIPAnalysisResponse response = new ZIPAnalysisResponse();
+        response.setSuccess(true);
+        response.setMessage("ZIP file analyzed successfully");
+        response.setZipFileName(zipFileName);
+        response.setFiles(files);
+        response.setTotalFiles(files.size());
+        response.setValidFiles((int) files.stream().filter(f -> f.getError() == null).count());
+        return response;
+    }
+
+    public static ZIPAnalysisResponse error(String message) {
+        ZIPAnalysisResponse response = new ZIPAnalysisResponse();
+        response.setSuccess(false);
+        response.setMessage(message);
+        return response;
+    }
+
+    public void addWarning(String warning) {
+        this.warnings.add(warning);
+    }
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public void setSuccess(boolean success) {
+        this.success = success;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    public String getZipFileName() {
+        return zipFileName;
+    }
+
+    public void setZipFileName(String zipFileName) {
+        this.zipFileName = zipFileName;
+    }
+
+    public int getTotalFiles() {
+        return totalFiles;
+    }
+
+    public void setTotalFiles(int totalFiles) {
+        this.totalFiles = totalFiles;
+    }
+
+    public int getValidFiles() {
+        return validFiles;
+    }
+
+    public void setValidFiles(int validFiles) {
+        this.validFiles = validFiles;
+    }
+
+    public List<FileInfoDto> getFiles() {
+        return files;
+    }
+
+    public void setFiles(List<FileInfoDto> files) {
+        this.files = files;
+    }
+
+    public List<String> getWarnings() {
+        return warnings;
+    }
+
+    public void setWarnings(List<String> warnings) {
+        this.warnings = warnings;
+    }
+}

backend/src/main/java/com/storycove/dto/ZIPImportRequest.java

@@ -0,0 +1,177 @@
+package com.storycove.dto;
+
+import jakarta.validation.constraints.NotNull;
+
+import java.util.List;
+import java.util.Map;
+import java.util.UUID;
+
+public class ZIPImportRequest {
+
+    @NotNull(message = "ZIP session ID is required")
+    private String zipSessionId; // Temporary ID for the uploaded ZIP file
+
+    @NotNull(message = "Selected files are required")
+    private List<String> selectedFiles; // List of file names to import
+
+    // Per-file metadata overrides (key = fileName)
+    private Map<String, FileImportMetadata> fileMetadata;
+
+    // Default metadata for all files (if not specified per file)
+    private UUID defaultAuthorId;
+    private String defaultAuthorName;
+    private UUID defaultSeriesId;
+    private String defaultSeriesName;
+    private List<String> defaultTags;
+
+    private Boolean createMissingAuthor = true;
+    private Boolean createMissingSeries = true;
+    private Boolean extractImages = true;
+
+    public ZIPImportRequest() {}
+
+    public static class FileImportMetadata {
+        private UUID authorId;
+        private String authorName;
+        private UUID seriesId;
+        private String seriesName;
+        private Integer seriesVolume;
+        private List<String> tags;
+
+        public UUID getAuthorId() {
+            return authorId;
+        }
+
+        public void setAuthorId(UUID authorId) {
+            this.authorId = authorId;
+        }
+
+        public String getAuthorName() {
+            return authorName;
+        }
+
+        public void setAuthorName(String authorName) {
+            this.authorName = authorName;
+        }
+
+        public UUID getSeriesId() {
+            return seriesId;
+        }
+
+        public void setSeriesId(UUID seriesId) {
+            this.seriesId = seriesId;
+        }
+
+        public String getSeriesName() {
+            return seriesName;
+        }
+
+        public void setSeriesName(String seriesName) {
+            this.seriesName = seriesName;
+        }
+
+        public Integer getSeriesVolume() {
+            return seriesVolume;
+        }
+
+        public void setSeriesVolume(Integer seriesVolume) {
+            this.seriesVolume = seriesVolume;
+        }
+
+        public List<String> getTags() {
+            return tags;
+        }
+
+        public void setTags(List<String> tags) {
+            this.tags = tags;
+        }
+    }
+
+    public String getZipSessionId() {
+        return zipSessionId;
+    }
+
+    public void setZipSessionId(String zipSessionId) {
+        this.zipSessionId = zipSessionId;
+    }
+
+    public List<String> getSelectedFiles() {
+        return selectedFiles;
+    }
+
+    public void setSelectedFiles(List<String> selectedFiles) {
+        this.selectedFiles = selectedFiles;
+    }
+
+    public Map<String, FileImportMetadata> getFileMetadata() {
+        return fileMetadata;
+    }
+
+    public void setFileMetadata(Map<String, FileImportMetadata> fileMetadata) {
+        this.fileMetadata = fileMetadata;
+    }
+
+    public UUID getDefaultAuthorId() {
+        return defaultAuthorId;
+    }
+
+    public void setDefaultAuthorId(UUID defaultAuthorId) {
+        this.defaultAuthorId = defaultAuthorId;
+    }
+
+    public String getDefaultAuthorName() {
+        return defaultAuthorName;
+    }
+
+    public void setDefaultAuthorName(String defaultAuthorName) {
+        this.defaultAuthorName = defaultAuthorName;
+    }
+
+    public UUID getDefaultSeriesId() {
+        return defaultSeriesId;
+    }
+
+    public void setDefaultSeriesId(UUID defaultSeriesId) {
+        this.defaultSeriesId = defaultSeriesId;
+    }
+
+    public String getDefaultSeriesName() {
+        return defaultSeriesName;
+    }
+
+    public void setDefaultSeriesName(String defaultSeriesName) {
+        this.defaultSeriesName = defaultSeriesName;
+    }
+
+    public List<String> getDefaultTags() {
+        return defaultTags;
+    }
+
+    public void setDefaultTags(List<String> defaultTags) {
+        this.defaultTags = defaultTags;
+    }
+
+    public Boolean getCreateMissingAuthor() {
+        return createMissingAuthor;
+    }
+
+    public void setCreateMissingAuthor(Boolean createMissingAuthor) {
+        this.createMissingAuthor = createMissingAuthor;
+    }
+
+    public Boolean getCreateMissingSeries() {
+        return createMissingSeries;
+    }
+
+    public void setCreateMissingSeries(Boolean createMissingSeries) {
+        this.createMissingSeries = createMissingSeries;
+    }
+
+    public Boolean getExtractImages() {
+        return extractImages;
+    }
+
+    public void setExtractImages(Boolean extractImages) {
+        this.extractImages = extractImages;
+    }
+}

backend/src/main/java/com/storycove/dto/ZIPImportResponse.java

@@ -0,0 +1,101 @@
+package com.storycove.dto;
+
+import java.util.ArrayList;
+import java.util.List;
+
+public class ZIPImportResponse {
+
+    private boolean success;
+    private String message;
+    private int totalFiles;
+    private int successfulImports;
+    private int failedImports;
+    private List<FileImportResponse> results;
+    private List<String> warnings;
+
+    public ZIPImportResponse() {
+        this.results = new ArrayList<>();
+        this.warnings = new ArrayList<>();
+    }
+
+    public static ZIPImportResponse create(List<FileImportResponse> results) {
+        ZIPImportResponse response = new ZIPImportResponse();
+        response.setResults(results);
+        response.setTotalFiles(results.size());
+        response.setSuccessfulImports((int) results.stream().filter(FileImportResponse::isSuccess).count());
+        response.setFailedImports((int) results.stream().filter(r -> !r.isSuccess()).count());
+
+        if (response.getFailedImports() == 0) {
+            response.setSuccess(true);
+            response.setMessage("All files imported successfully");
+        } else if (response.getSuccessfulImports() == 0) {
+            response.setSuccess(false);
+            response.setMessage("All file imports failed");
+        } else {
+            response.setSuccess(true);
+            response.setMessage("Partial success: " + response.getSuccessfulImports() + " imported, " + response.getFailedImports() + " failed");
+        }
+
+        return response;
+    }
+
+    public void addWarning(String warning) {
+        this.warnings.add(warning);
+    }
+
+    public boolean isSuccess() {
+        return success;
+    }
+
+    public void setSuccess(boolean success) {
+        this.success = success;
+    }
+
+    public String getMessage() {
+        return message;
+    }
+
+    public void setMessage(String message) {
+        this.message = message;
+    }
+
+    public int getTotalFiles() {
+        return totalFiles;
+    }
+
+    public void setTotalFiles(int totalFiles) {
+        this.totalFiles = totalFiles;
+    }
+
+    public int getSuccessfulImports() {
+        return successfulImports;
+    }
+
+    public void setSuccessfulImports(int successfulImports) {
+        this.successfulImports = successfulImports;
+    }
+
+    public int getFailedImports() {
+        return failedImports;
+    }
+
+    public void setFailedImports(int failedImports) {
+        this.failedImports = failedImports;
+    }
+
+    public List<FileImportResponse> getResults() {
+        return results;
+    }
+
+    public void setResults(List<FileImportResponse> results) {
+        this.results = results;
+    }
+
+    public List<String> getWarnings() {
+        return warnings;
+    }
+
+    public void setWarnings(List<String> warnings) {
+        this.warnings = warnings;
+    }
+}

backend/src/main/java/com/storycove/entity/BackupJob.java

@@ -0,0 +1,195 @@
+package com.storycove.entity;
+
+import jakarta.persistence.*;
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "backup_jobs")
+public class BackupJob {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @Column(nullable = false)
+    private String libraryId;
+
+    @Column(nullable = false)
+    @Enumerated(EnumType.STRING)
+    private BackupType type;
+
+    @Column(nullable = false)
+    @Enumerated(EnumType.STRING)
+    private BackupStatus status;
+
+    @Column
+    private String filePath;
+
+    @Column
+    private Long fileSizeBytes;
+
+    @Column
+    private Integer progressPercent;
+
+    @Column(length = 1000)
+    private String errorMessage;
+
+    @Column(nullable = false)
+    private LocalDateTime createdAt;
+
+    @Column
+    private LocalDateTime startedAt;
+
+    @Column
+    private LocalDateTime completedAt;
+
+    @Column
+    private LocalDateTime expiresAt;
+
+    @PrePersist
+    protected void onCreate() {
+        createdAt = LocalDateTime.now();
+        // Backups expire after 24 hours
+        expiresAt = LocalDateTime.now().plusDays(1);
+    }
+
+    // Enums
+    public enum BackupType {
+        DATABASE_ONLY,
+        COMPLETE
+    }
+
+    public enum BackupStatus {
+        PENDING,
+        IN_PROGRESS,
+        COMPLETED,
+        FAILED,
+        EXPIRED
+    }
+
+    // Constructors
+    public BackupJob() {
+    }
+
+    public BackupJob(String libraryId, BackupType type) {
+        this.libraryId = libraryId;
+        this.type = type;
+        this.status = BackupStatus.PENDING;
+        this.progressPercent = 0;
+    }
+
+    // Getters and Setters
+    public UUID getId() {
+        return id;
+    }
+
+    public void setId(UUID id) {
+        this.id = id;
+    }
+
+    public String getLibraryId() {
+        return libraryId;
+    }
+
+    public void setLibraryId(String libraryId) {
+        this.libraryId = libraryId;
+    }
+
+    public BackupType getType() {
+        return type;
+    }
+
+    public void setType(BackupType type) {
+        this.type = type;
+    }
+
+    public BackupStatus getStatus() {
+        return status;
+    }
+
+    public void setStatus(BackupStatus status) {
+        this.status = status;
+    }
+
+    public String getFilePath() {
+        return filePath;
+    }
+
+    public void setFilePath(String filePath) {
+        this.filePath = filePath;
+    }
+
+    public Long getFileSizeBytes() {
+        return fileSizeBytes;
+    }
+
+    public void setFileSizeBytes(Long fileSizeBytes) {
+        this.fileSizeBytes = fileSizeBytes;
+    }
+
+    public Integer getProgressPercent() {
+        return progressPercent;
+    }
+
+    public void setProgressPercent(Integer progressPercent) {
+        this.progressPercent = progressPercent;
+    }
+
+    public String getErrorMessage() {
+        return errorMessage;
+    }
+
+    public void setErrorMessage(String errorMessage) {
+        this.errorMessage = errorMessage;
+    }
+
+    public LocalDateTime getCreatedAt() {
+        return createdAt;
+    }
+
+    public void setCreatedAt(LocalDateTime createdAt) {
+        this.createdAt = createdAt;
+    }
+
+    public LocalDateTime getStartedAt() {
+        return startedAt;
+    }
+
+    public void setStartedAt(LocalDateTime startedAt) {
+        this.startedAt = startedAt;
+    }
+
+    public LocalDateTime getCompletedAt() {
+        return completedAt;
+    }
+
+    public void setCompletedAt(LocalDateTime completedAt) {
+        this.completedAt = completedAt;
+    }
+
+    public LocalDateTime getExpiresAt() {
+        return expiresAt;
+    }
+
+    public void setExpiresAt(LocalDateTime expiresAt) {
+        this.expiresAt = expiresAt;
+    }
+
+    // Helper methods
+    public boolean isExpired() {
+        return LocalDateTime.now().isAfter(expiresAt);
+    }
+
+    public boolean isCompleted() {
+        return status == BackupStatus.COMPLETED;
+    }
+
+    public boolean isFailed() {
+        return status == BackupStatus.FAILED;
+    }
+
+    public boolean isInProgress() {
+        return status == BackupStatus.IN_PROGRESS;
+    }
+}

backend/src/main/java/com/storycove/entity/RefreshToken.java

@@ -0,0 +1,130 @@
+package com.storycove.entity;
+
+import jakarta.persistence.*;
+import java.time.LocalDateTime;
+import java.util.UUID;
+
+@Entity
+@Table(name = "refresh_tokens")
+public class RefreshToken {
+
+    @Id
+    @GeneratedValue(strategy = GenerationType.UUID)
+    private UUID id;
+
+    @Column(nullable = false, unique = true)
+    private String token;
+
+    @Column(nullable = false)
+    private LocalDateTime expiresAt;
+
+    @Column(nullable = false)
+    private LocalDateTime createdAt;
+
+    @Column
+    private LocalDateTime revokedAt;
+
+    @Column
+    private String libraryId;
+
+    @Column(nullable = false)
+    private String userAgent;
+
+    @Column(nullable = false)
+    private String ipAddress;
+
+    @PrePersist
+    protected void onCreate() {
+        createdAt = LocalDateTime.now();
+    }
+
+    // Constructors
+    public RefreshToken() {
+    }
+
+    public RefreshToken(String token, LocalDateTime expiresAt, String libraryId, String userAgent, String ipAddress) {
+        this.token = token;
+        this.expiresAt = expiresAt;
+        this.libraryId = libraryId;
+        this.userAgent = userAgent;
+        this.ipAddress = ipAddress;
+    }
+
+    // Getters and Setters
+    public UUID getId() {
+        return id;
+    }
+
+    public void setId(UUID id) {
+        this.id = id;
+    }
+
+    public String getToken() {
+        return token;
+    }
+
+    public void setToken(String token) {
+        this.token = token;
+    }
+
+    public LocalDateTime getExpiresAt() {
+        return expiresAt;
+    }
+
+    public void setExpiresAt(LocalDateTime expiresAt) {
+        this.expiresAt = expiresAt;
+    }
+
+    public LocalDateTime getCreatedAt() {
+        return createdAt;
+    }
+
+    public void setCreatedAt(LocalDateTime createdAt) {
+        this.createdAt = createdAt;
+    }
+
+    public LocalDateTime getRevokedAt() {
+        return revokedAt;
+    }
+
+    public void setRevokedAt(LocalDateTime revokedAt) {
+        this.revokedAt = revokedAt;
+    }
+
+    public String getLibraryId() {
+        return libraryId;
+    }
+
+    public void setLibraryId(String libraryId) {
+        this.libraryId = libraryId;
+    }
+
+    public String getUserAgent() {
+        return userAgent;
+    }
+
+    public void setUserAgent(String userAgent) {
+        this.userAgent = userAgent;
+    }
+
+    public String getIpAddress() {
+        return ipAddress;
+    }
+
+    public void setIpAddress(String ipAddress) {
+        this.ipAddress = ipAddress;
+    }
+
+    // Helper methods
+    public boolean isExpired() {
+        return LocalDateTime.now().isAfter(expiresAt);
+    }
+
+    public boolean isRevoked() {
+        return revokedAt != null;
+    }
+
+    public boolean isValid() {
+        return !isExpired() && !isRevoked();
+    }
+}

backend/src/main/java/com/storycove/entity/Story.java

@@ -287,10 +287,17 @@ public class Story {
     
     /**
      * Updates the reading progress and timestamp
+     * When position is 0 or null, resets lastReadAt to null so the story won't appear in "last read" sorting
      */
     public void updateReadingProgress(Integer position) {
         this.readingPosition = position;
-        this.lastReadAt = LocalDateTime.now();
+        // Only update lastReadAt if there's actual reading progress
+        // Reset to null when position is 0 or null to remove from "last read" sorting
+        if (position == null || position == 0) {
+            this.lastReadAt = null;
+        } else {
+            this.lastReadAt = LocalDateTime.now();
+        }
     }
     
     /**

backend/src/main/java/com/storycove/event/StoryContentUpdatedEvent.java

@@ -0,0 +1,34 @@
+package com.storycove.event;
+
+import org.springframework.context.ApplicationEvent;
+
+import java.util.UUID;
+
+/**
+ * Event published when a story's content is created or updated
+ */
+public class StoryContentUpdatedEvent extends ApplicationEvent {
+
+    private final UUID storyId;
+    private final String contentHtml;
+    private final boolean isNewStory;
+
+    public StoryContentUpdatedEvent(Object source, UUID storyId, String contentHtml, boolean isNewStory) {
+        super(source);
+        this.storyId = storyId;
+        this.contentHtml = contentHtml;
+        this.isNewStory = isNewStory;
+    }
+
+    public UUID getStoryId() {
+        return storyId;
+    }
+
+    public String getContentHtml() {
+        return contentHtml;
+    }
+
+    public boolean isNewStory() {
+        return isNewStory;
+    }
+}

backend/src/main/java/com/storycove/repository/BackupJobRepository.java

@@ -0,0 +1,25 @@
+package com.storycove.repository;
+
+import com.storycove.entity.BackupJob;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.UUID;
+
+@Repository
+public interface BackupJobRepository extends JpaRepository<BackupJob, UUID> {
+
+    List<BackupJob> findByLibraryIdOrderByCreatedAtDesc(String libraryId);
+
+    @Query("SELECT bj FROM BackupJob bj WHERE bj.expiresAt < :now AND bj.status = 'COMPLETED'")
+    List<BackupJob> findExpiredJobs(@Param("now") LocalDateTime now);
+
+    @Modifying
+    @Query("UPDATE BackupJob bj SET bj.status = 'EXPIRED' WHERE bj.expiresAt < :now AND bj.status = 'COMPLETED'")
+    int markExpiredJobs(@Param("now") LocalDateTime now);
+}

backend/src/main/java/com/storycove/repository/RefreshTokenRepository.java

@@ -0,0 +1,30 @@
+package com.storycove.repository;
+
+import com.storycove.entity.RefreshToken;
+import org.springframework.data.jpa.repository.JpaRepository;
+import org.springframework.data.jpa.repository.Modifying;
+import org.springframework.data.jpa.repository.Query;
+import org.springframework.data.repository.query.Param;
+import org.springframework.stereotype.Repository;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+import java.util.UUID;
+
+@Repository
+public interface RefreshTokenRepository extends JpaRepository<RefreshToken, UUID> {
+
+    Optional<RefreshToken> findByToken(String token);
+
+    @Modifying
+    @Query("DELETE FROM RefreshToken rt WHERE rt.expiresAt < :now")
+    void deleteExpiredTokens(@Param("now") LocalDateTime now);
+
+    @Modifying
+    @Query("UPDATE RefreshToken rt SET rt.revokedAt = :now WHERE rt.libraryId = :libraryId AND rt.revokedAt IS NULL")
+    void revokeAllByLibraryId(@Param("libraryId") String libraryId, @Param("now") LocalDateTime now);
+
+    @Modifying
+    @Query("UPDATE RefreshToken rt SET rt.revokedAt = :now WHERE rt.revokedAt IS NULL")
+    void revokeAll(@Param("now") LocalDateTime now);
+}

backend/src/main/java/com/storycove/repository/StoryRepository.java

@@ -86,6 +86,9 @@ public interface StoryRepository extends JpaRepository<Story, UUID> {
     
     @Query("SELECT COUNT(s) FROM Story s WHERE s.createdAt >= :since")
     long countStoriesCreatedSince(@Param("since") LocalDateTime since);
+
+    @Query("SELECT COUNT(s) FROM Story s WHERE s.createdAt >= :since OR s.updatedAt >= :since")
+    long countStoriesModifiedAfter(@Param("since") LocalDateTime since);
     
     @Query("SELECT AVG(s.wordCount) FROM Story s")
     Double findAverageWordCount();

backend/src/main/java/com/storycove/security/JwtAuthenticationFilter.java

@@ -1,11 +1,14 @@
 package com.storycove.security;
 
+import com.storycove.service.LibraryService;
 import com.storycove.util.JwtUtil;
 import jakarta.servlet.FilterChain;
 import jakarta.servlet.ServletException;
 import jakarta.servlet.http.Cookie;
 import jakarta.servlet.http.HttpServletRequest;
 import jakarta.servlet.http.HttpServletResponse;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.security.web.authentication.WebAuthenticationDetailsSource;
@@ -17,11 +20,15 @@ import java.util.ArrayList;
 
 @Component
 public class JwtAuthenticationFilter extends OncePerRequestFilter {
-    
+
+    private static final Logger logger = LoggerFactory.getLogger(JwtAuthenticationFilter.class);
+
     private final JwtUtil jwtUtil;
-    
+    private final LibraryService libraryService;
-    public JwtAuthenticationFilter(JwtUtil jwtUtil) {
+
+    public JwtAuthenticationFilter(JwtUtil jwtUtil, LibraryService libraryService) {
         this.jwtUtil = jwtUtil;
+        this.libraryService = libraryService;
     }
     
     @Override
@@ -52,9 +59,31 @@ public class JwtAuthenticationFilter extends OncePerRequestFilter {
         
         if (token != null && jwtUtil.validateToken(token) && !jwtUtil.isTokenExpired(token)) {
             String subject = jwtUtil.getSubjectFromToken(token);
-            
+
+            // Check if we need to switch libraries based on token's library ID
+            try {
+                String tokenLibraryId = jwtUtil.getLibraryIdFromToken(token);
+                String currentLibraryId = libraryService.getCurrentLibraryId();
+
+                // Switch library if token's library differs from current library
+                // This handles cross-device library switching automatically
+                if (tokenLibraryId != null && !tokenLibraryId.equals(currentLibraryId)) {
+                    logger.info("Token library '{}' differs from current library '{}', switching libraries",
+                            tokenLibraryId, currentLibraryId);
+                    libraryService.switchToLibraryAfterAuthentication(tokenLibraryId);
+                } else if (currentLibraryId == null && tokenLibraryId != null) {
+                    // Handle case after backend restart where no library is active
+                    logger.info("No active library, switching to token's library: {}", tokenLibraryId);
+                    libraryService.switchToLibraryAfterAuthentication(tokenLibraryId);
+                }
+            } catch (Exception e) {
+                logger.error("Failed to switch library from token: {}", e.getMessage());
+                // Don't fail the request - authentication can still proceed
+                // but user might see wrong library data until next login
+            }
+
             if (subject != null && SecurityContextHolder.getContext().getAuthentication() == null) {
-                UsernamePasswordAuthenticationToken authToken = 
+                UsernamePasswordAuthenticationToken authToken =
                     new UsernamePasswordAuthenticationToken(subject, null, new ArrayList<>());
                 authToken.setDetails(new WebAuthenticationDetailsSource().buildDetails(request));
                 SecurityContextHolder.getContext().setAuthentication(authToken);

backend/src/main/java/com/storycove/service/AsyncBackupExecutor.java

@@ -0,0 +1,125 @@
+package com.storycove.service;
+
+import com.storycove.entity.BackupJob;
+import com.storycove.repository.BackupJobRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.Resource;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Propagation;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.util.Optional;
+import java.util.UUID;
+
+/**
+ * Separate service for async backup execution.
+ * This is needed because @Async doesn't work when called from within the same class.
+ */
+@Service
+public class AsyncBackupExecutor {
+
+    private static final Logger logger = LoggerFactory.getLogger(AsyncBackupExecutor.class);
+
+    @Value("${storycove.upload.dir:/app/images}")
+    private String uploadDir;
+
+    @Autowired
+    private BackupJobRepository backupJobRepository;
+
+    @Autowired
+    private DatabaseManagementService databaseManagementService;
+
+    @Autowired
+    private LibraryService libraryService;
+
+    /**
+     * Execute backup asynchronously.
+     * This method MUST be in a separate service class for @Async to work properly.
+     */
+    @Async
+    @Transactional(propagation = Propagation.REQUIRES_NEW)
+    public void executeBackupAsync(UUID jobId) {
+        logger.info("Async executor starting for job {}", jobId);
+
+        Optional<BackupJob> jobOpt = backupJobRepository.findById(jobId);
+        if (jobOpt.isEmpty()) {
+            logger.error("Backup job not found: {}", jobId);
+            return;
+        }
+
+        BackupJob job = jobOpt.get();
+        job.setStatus(BackupJob.BackupStatus.IN_PROGRESS);
+        job.setStartedAt(LocalDateTime.now());
+        job.setProgressPercent(0);
+        backupJobRepository.save(job);
+
+        try {
+            logger.info("Starting backup job {} for library {}", job.getId(), job.getLibraryId());
+
+            // Switch to the correct library
+            if (!job.getLibraryId().equals(libraryService.getCurrentLibraryId())) {
+                libraryService.switchToLibraryAfterAuthentication(job.getLibraryId());
+            }
+
+            // Create backup file
+            Path backupDir = Paths.get(uploadDir, "backups", job.getLibraryId());
+            Files.createDirectories(backupDir);
+
+            String filename = String.format("backup_%s_%s.%s",
+                    job.getId().toString(),
+                    LocalDateTime.now().toString().replaceAll(":", "-"),
+                    job.getType() == BackupJob.BackupType.COMPLETE ? "zip" : "sql");
+
+            Path backupFile = backupDir.resolve(filename);
+
+            job.setProgressPercent(10);
+            backupJobRepository.save(job);
+
+            // Create the backup
+            Resource backupResource;
+            if (job.getType() == BackupJob.BackupType.COMPLETE) {
+                backupResource = databaseManagementService.createCompleteBackup();
+            } else {
+                backupResource = databaseManagementService.createBackup();
+            }
+
+            job.setProgressPercent(80);
+            backupJobRepository.save(job);
+
+            // Copy resource to permanent file
+            try (var inputStream = backupResource.getInputStream();
+                 var outputStream = Files.newOutputStream(backupFile)) {
+                inputStream.transferTo(outputStream);
+            }
+
+            job.setProgressPercent(95);
+            backupJobRepository.save(job);
+
+            // Set file info
+            job.setFilePath(backupFile.toString());
+            job.setFileSizeBytes(Files.size(backupFile));
+            job.setStatus(BackupJob.BackupStatus.COMPLETED);
+            job.setCompletedAt(LocalDateTime.now());
+            job.setProgressPercent(100);
+
+            logger.info("Backup job {} completed successfully. File size: {} bytes",
+                    job.getId(), job.getFileSizeBytes());
+
+        } catch (Exception e) {
+            logger.error("Backup job {} failed", job.getId(), e);
+            job.setStatus(BackupJob.BackupStatus.FAILED);
+            job.setErrorMessage(e.getMessage());
+            job.setCompletedAt(LocalDateTime.now());
+        } finally {
+            backupJobRepository.save(job);
+        }
+    }
+}

backend/src/main/java/com/storycove/service/AsyncBackupService.java

@@ -0,0 +1,167 @@
+package com.storycove.service;
+
+import com.storycove.entity.BackupJob;
+import com.storycove.repository.BackupJobRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.FileSystemResource;
+import org.springframework.core.io.Resource;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+@Service
+public class AsyncBackupService {
+
+    private static final Logger logger = LoggerFactory.getLogger(AsyncBackupService.class);
+
+    @Value("${storycove.upload.dir:/app/images}")
+    private String uploadDir;
+
+    @Autowired
+    private BackupJobRepository backupJobRepository;
+
+    @Autowired
+    private AsyncBackupExecutor asyncBackupExecutor;
+
+    /**
+     * Start a backup job asynchronously.
+     * This method returns immediately after creating the job record.
+     */
+    @Transactional
+    public BackupJob startBackupJob(String libraryId, BackupJob.BackupType type) {
+        logger.info("Creating backup job for library: {}, type: {}", libraryId, type);
+
+        BackupJob job = new BackupJob(libraryId, type);
+        job = backupJobRepository.save(job);
+
+        logger.info("Backup job created with ID: {}. Starting async execution...", job.getId());
+
+        // Start backup in background using separate service (ensures @Async works properly)
+        asyncBackupExecutor.executeBackupAsync(job.getId());
+
+        logger.info("Async backup execution triggered for job: {}", job.getId());
+
+        return job;
+    }
+
+    /**
+     * Get backup job status
+     */
+    public Optional<BackupJob> getJobStatus(UUID jobId) {
+        return backupJobRepository.findById(jobId);
+    }
+
+    /**
+     * Get backup file for download
+     */
+    public Resource getBackupFile(UUID jobId) throws IOException {
+        Optional<BackupJob> jobOpt = backupJobRepository.findById(jobId);
+        if (jobOpt.isEmpty()) {
+            throw new IOException("Backup job not found");
+        }
+
+        BackupJob job = jobOpt.get();
+
+        if (!job.isCompleted()) {
+            throw new IOException("Backup is not completed yet");
+        }
+
+        if (job.isExpired()) {
+            throw new IOException("Backup has expired");
+        }
+
+        if (job.getFilePath() == null) {
+            throw new IOException("Backup file path not set");
+        }
+
+        Path backupPath = Paths.get(job.getFilePath());
+        if (!Files.exists(backupPath)) {
+            throw new IOException("Backup file not found");
+        }
+
+        return new FileSystemResource(backupPath);
+    }
+
+    /**
+     * List backup jobs for a library
+     */
+    public List<BackupJob> listBackupJobs(String libraryId) {
+        return backupJobRepository.findByLibraryIdOrderByCreatedAtDesc(libraryId);
+    }
+
+    /**
+     * Clean up expired backup jobs and their files
+     * Runs daily at 2 AM
+     */
+    @Scheduled(cron = "0 0 2 * * ?")
+    @Transactional
+    public void cleanupExpiredBackups() {
+        logger.info("Starting cleanup of expired backups");
+
+        LocalDateTime now = LocalDateTime.now();
+
+        // Mark expired jobs
+        int markedCount = backupJobRepository.markExpiredJobs(now);
+        logger.info("Marked {} jobs as expired", markedCount);
+
+        // Find all expired jobs to delete their files
+        List<BackupJob> expiredJobs = backupJobRepository.findExpiredJobs(now);
+
+        for (BackupJob job : expiredJobs) {
+            if (job.getFilePath() != null) {
+                try {
+                    Path filePath = Paths.get(job.getFilePath());
+                    if (Files.exists(filePath)) {
+                        Files.delete(filePath);
+                        logger.info("Deleted expired backup file: {}", filePath);
+                    }
+                } catch (IOException e) {
+                    logger.warn("Failed to delete expired backup file: {}", job.getFilePath(), e);
+                }
+            }
+
+            // Delete the job record
+            backupJobRepository.delete(job);
+        }
+
+        logger.info("Cleanup completed. Deleted {} expired backups", expiredJobs.size());
+    }
+
+    /**
+     * Delete a specific backup job and its file
+     */
+    @Transactional
+    public void deleteBackupJob(UUID jobId) throws IOException {
+        Optional<BackupJob> jobOpt = backupJobRepository.findById(jobId);
+        if (jobOpt.isEmpty()) {
+            throw new IOException("Backup job not found");
+        }
+
+        BackupJob job = jobOpt.get();
+
+        // Delete file if it exists
+        if (job.getFilePath() != null) {
+            Path filePath = Paths.get(job.getFilePath());
+            if (Files.exists(filePath)) {
+                Files.delete(filePath);
+                logger.info("Deleted backup file: {}", filePath);
+            }
+        }
+
+        // Delete job record
+        backupJobRepository.delete(job);
+        logger.info("Deleted backup job: {}", jobId);
+    }
+}

backend/src/main/java/com/storycove/service/AsyncImageProcessingService.java

@@ -0,0 +1,169 @@
+package com.storycove.service;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.scheduling.annotation.Async;
+import org.springframework.stereotype.Service;
+
+import java.util.UUID;
+import java.util.concurrent.CompletableFuture;
+import java.util.regex.Matcher;
+import java.util.regex.Pattern;
+
+@Service
+public class AsyncImageProcessingService {
+
+    private static final Logger logger = LoggerFactory.getLogger(AsyncImageProcessingService.class);
+
+    private final ImageService imageService;
+    private final StoryService storyService;
+    private final ImageProcessingProgressService progressService;
+
+    @org.springframework.beans.factory.annotation.Value("${storycove.app.public-url:http://localhost:6925}")
+    private String publicUrl;
+
+    @Autowired
+    public AsyncImageProcessingService(ImageService imageService,
+                                     StoryService storyService,
+                                     ImageProcessingProgressService progressService) {
+        this.imageService = imageService;
+        this.storyService = storyService;
+        this.progressService = progressService;
+    }
+
+    @Async
+    public CompletableFuture<Void> processStoryImagesAsync(UUID storyId, String contentHtml) {
+        logger.info("Starting async image processing for story: {}", storyId);
+
+        try {
+            // Count external images first
+            int externalImageCount = countExternalImages(contentHtml);
+
+            if (externalImageCount == 0) {
+                logger.debug("No external images found for story {}", storyId);
+                return CompletableFuture.completedFuture(null);
+            }
+
+            // Start progress tracking
+            ImageProcessingProgressService.ImageProcessingProgress progress =
+                progressService.startProgress(storyId, externalImageCount);
+
+            // Process images with progress updates
+            ImageService.ContentImageProcessingResult result =
+                processImagesWithProgress(contentHtml, storyId, progress);
+
+            // Update story with processed content if changed
+            if (!result.getProcessedContent().equals(contentHtml)) {
+                progressService.updateProgress(storyId, progress.getTotalImages(),
+                    "Saving processed content", "Updating story content");
+
+                storyService.updateContentOnly(storyId, result.getProcessedContent());
+
+                progressService.completeProgress(storyId,
+                    String.format("Completed: %d images processed", result.getDownloadedImages().size()));
+
+                logger.info("Async image processing completed for story {}: {} images processed",
+                           storyId, result.getDownloadedImages().size());
+            } else {
+                progressService.completeProgress(storyId, "Completed: No images needed processing");
+            }
+
+            // Clean up progress after a delay to allow frontend to see completion
+            CompletableFuture.runAsync(() -> {
+                try {
+                    Thread.sleep(5000); // 5 seconds delay
+                    progressService.removeProgress(storyId);
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                }
+            });
+
+        } catch (Exception e) {
+            logger.error("Async image processing failed for story {}: {}", storyId, e.getMessage(), e);
+            progressService.setError(storyId, e.getMessage());
+        }
+
+        return CompletableFuture.completedFuture(null);
+    }
+
+    private int countExternalImages(String contentHtml) {
+        if (contentHtml == null || contentHtml.trim().isEmpty()) {
+            return 0;
+        }
+
+        Pattern imgPattern = Pattern.compile("<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>", Pattern.CASE_INSENSITIVE);
+        Matcher matcher = imgPattern.matcher(contentHtml);
+
+        int count = 0;
+        while (matcher.find()) {
+            String src = matcher.group(1);
+            if (isExternalUrl(src)) {
+                count++;
+            }
+        }
+
+        return count;
+    }
+
+    /**
+     * Check if a URL is external (not from this application).
+     * Returns true if the URL should be downloaded, false if it's already local.
+     */
+    private boolean isExternalUrl(String url) {
+        if (url == null || url.trim().isEmpty()) {
+            return false;
+        }
+
+        // Skip data URLs
+        if (url.startsWith("data:")) {
+            return false;
+        }
+
+        // Skip relative URLs (local paths)
+        if (url.startsWith("/")) {
+            return false;
+        }
+
+        // Skip URLs that are already pointing to our API
+        if (url.contains("/api/files/images/")) {
+            return false;
+        }
+
+        // Check if URL starts with the public URL (our own domain)
+        if (publicUrl != null && !publicUrl.trim().isEmpty()) {
+            String normalizedUrl = url.trim().toLowerCase();
+            String normalizedPublicUrl = publicUrl.trim().toLowerCase();
+
+            // Remove trailing slash from public URL for comparison
+            if (normalizedPublicUrl.endsWith("/")) {
+                normalizedPublicUrl = normalizedPublicUrl.substring(0, normalizedPublicUrl.length() - 1);
+            }
+
+            if (normalizedUrl.startsWith(normalizedPublicUrl)) {
+                logger.debug("URL is from this application (matches publicUrl): {}", url);
+                return false;
+            }
+        }
+
+        // If it's an HTTP(S) URL that didn't match our filters, it's external
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            logger.debug("URL is external: {}", url);
+            return true;
+        }
+
+        // For any other format, consider it non-external (safer default)
+        return false;
+    }
+
+    private ImageService.ContentImageProcessingResult processImagesWithProgress(
+            String contentHtml, UUID storyId, ImageProcessingProgressService.ImageProcessingProgress progress) {
+
+        // Use a custom version of processContentImages that provides progress callbacks
+        return imageService.processContentImagesWithProgress(contentHtml, storyId,
+            (currentUrl, processedCount, totalCount) -> {
+                progressService.updateProgress(storyId, processedCount, currentUrl,
+                    String.format("Processing image %d of %d", processedCount + 1, totalCount));
+            });
+    }
+}

backend/src/main/java/com/storycove/service/AuthorService.java

@@ -132,7 +132,7 @@ public class AuthorService {
         validateAuthorForCreate(author);
         Author savedAuthor = authorRepository.save(author);
         
-        // Index in OpenSearch
+        // Index in Solr
         searchServiceAdapter.indexAuthor(savedAuthor);
         
         return savedAuthor;
@@ -150,7 +150,7 @@ public class AuthorService {
         updateAuthorFields(existingAuthor, authorUpdates);
         Author savedAuthor = authorRepository.save(existingAuthor);
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(savedAuthor);
         
         return savedAuthor;
@@ -166,7 +166,7 @@ public class AuthorService {
         
         authorRepository.delete(author);
         
-        // Remove from OpenSearch
+        // Remove from Solr
         searchServiceAdapter.deleteAuthor(id);
     }
 
@@ -175,7 +175,7 @@ public class AuthorService {
         author.addUrl(url);
         Author savedAuthor = authorRepository.save(author);
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(savedAuthor);
         
         return savedAuthor;
@@ -186,7 +186,7 @@ public class AuthorService {
         author.removeUrl(url);
         Author savedAuthor = authorRepository.save(author);
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(savedAuthor);
         
         return savedAuthor;
@@ -221,7 +221,7 @@ public class AuthorService {
         logger.debug("Saved author rating: {} for author: {}", 
                      refreshedAuthor.getAuthorRating(), refreshedAuthor.getName());
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(refreshedAuthor);
         
         return refreshedAuthor;
@@ -265,7 +265,7 @@ public class AuthorService {
         author.setAvatarImagePath(avatarPath);
         Author savedAuthor = authorRepository.save(author);
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(savedAuthor);
         
         return savedAuthor;
@@ -276,7 +276,7 @@ public class AuthorService {
         author.setAvatarImagePath(null);
         Author savedAuthor = authorRepository.save(author);
         
-        // Update in OpenSearch
+        // Update in Solr
         searchServiceAdapter.updateAuthor(savedAuthor);
         
         return savedAuthor;

backend/src/main/java/com/storycove/service/AutomaticBackupService.java

@@ -0,0 +1,262 @@
+package com.storycove.service;
+
+import com.storycove.repository.StoryRepository;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.core.io.Resource;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Service;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.Comparator;
+import java.util.List;
+import java.util.stream.Collectors;
+import java.util.stream.Stream;
+
+/**
+ * Service for automatic daily backups.
+ * Runs at 4 AM daily and creates a backup if content has changed since last backup.
+ * Keeps maximum of 5 backups, rotating old ones out.
+ */
+@Service
+public class AutomaticBackupService {
+
+    private static final Logger logger = LoggerFactory.getLogger(AutomaticBackupService.class);
+    private static final int MAX_BACKUPS = 5;
+    private static final DateTimeFormatter FILENAME_FORMATTER = DateTimeFormatter.ofPattern("yyyy-MM-dd_HH-mm-ss");
+
+    @Value("${storycove.automatic-backup.dir:/app/automatic-backups}")
+    private String automaticBackupDir;
+
+    @Autowired
+    private StoryRepository storyRepository;
+
+    @Autowired
+    private DatabaseManagementService databaseManagementService;
+
+    @Autowired
+    private LibraryService libraryService;
+
+    private LocalDateTime lastBackupCheck = null;
+
+    /**
+     * Scheduled job that runs daily at 4 AM.
+     * Creates a backup if content has changed since last backup.
+     */
+    @Scheduled(cron = "0 0 4 * * ?")
+    public void performAutomaticBackup() {
+        logger.info("========================================");
+        logger.info("Starting automatic backup check at 4 AM");
+        logger.info("========================================");
+
+        try {
+            // Get current library ID (or default)
+            String libraryId = libraryService.getCurrentLibraryId();
+            if (libraryId == null) {
+                libraryId = "default";
+            }
+
+            logger.info("Checking for content changes in library: {}", libraryId);
+
+            // Check if content has changed since last backup
+            if (!hasContentChanged()) {
+                logger.info("No content changes detected since last backup. Skipping backup.");
+                logger.info("========================================");
+                return;
+            }
+
+            logger.info("Content changes detected! Creating automatic backup...");
+
+            // Create backup directory for this library
+            Path backupPath = Paths.get(automaticBackupDir, libraryId);
+            Files.createDirectories(backupPath);
+
+            // Create the backup
+            String timestamp = LocalDateTime.now().format(FILENAME_FORMATTER);
+            String filename = String.format("auto_backup_%s.zip", timestamp);
+            Path backupFile = backupPath.resolve(filename);
+
+            logger.info("Creating complete backup to: {}", backupFile);
+
+            Resource backup = databaseManagementService.createCompleteBackup();
+
+            // Write backup to file
+            try (var inputStream = backup.getInputStream();
+                 var outputStream = Files.newOutputStream(backupFile)) {
+                inputStream.transferTo(outputStream);
+            }
+
+            long fileSize = Files.size(backupFile);
+            logger.info("✅ Automatic backup created successfully");
+            logger.info("   File: {}", backupFile.getFileName());
+            logger.info("   Size: {} MB", fileSize / 1024 / 1024);
+
+            // Rotate old backups (keep only MAX_BACKUPS)
+            rotateBackups(backupPath);
+
+            // Update last backup check time
+            lastBackupCheck = LocalDateTime.now();
+
+            logger.info("========================================");
+            logger.info("Automatic backup completed successfully");
+            logger.info("========================================");
+
+        } catch (Exception e) {
+            logger.error("❌ Automatic backup failed", e);
+            logger.info("========================================");
+        }
+    }
+
+    /**
+     * Check if content has changed since last backup.
+     * Looks for stories created or updated after the last backup time.
+     */
+    private boolean hasContentChanged() {
+        try {
+            if (lastBackupCheck == null) {
+                // First run - check if there are any stories at all
+                long storyCount = storyRepository.count();
+                logger.info("First backup check - found {} stories", storyCount);
+                return storyCount > 0;
+            }
+
+            // Check for stories created or updated since last backup
+            long changedCount = storyRepository.countStoriesModifiedAfter(lastBackupCheck);
+            logger.info("Found {} stories modified since last backup ({})", changedCount, lastBackupCheck);
+            return changedCount > 0;
+
+        } catch (Exception e) {
+            logger.error("Error checking for content changes", e);
+            // On error, create backup to be safe
+            return true;
+        }
+    }
+
+    /**
+     * Rotate backups - keep only MAX_BACKUPS most recent backups.
+     * Deletes older backups.
+     */
+    private void rotateBackups(Path backupPath) throws IOException {
+        logger.info("Checking for old backups to rotate...");
+
+        // Find all backup files in the directory
+        List<Path> backupFiles;
+        try (Stream<Path> stream = Files.list(backupPath)) {
+            backupFiles = stream
+                    .filter(Files::isRegularFile)
+                    .filter(p -> p.getFileName().toString().startsWith("auto_backup_"))
+                    .filter(p -> p.getFileName().toString().endsWith(".zip"))
+                    .sorted(Comparator.comparing((Path p) -> {
+                        try {
+                            return Files.getLastModifiedTime(p);
+                        } catch (IOException e) {
+                            return null;
+                        }
+                    }).reversed()) // Most recent first
+                    .collect(Collectors.toList());
+        }
+
+        logger.info("Found {} automatic backups", backupFiles.size());
+
+        // Delete old backups if we exceed MAX_BACKUPS
+        if (backupFiles.size() > MAX_BACKUPS) {
+            List<Path> toDelete = backupFiles.subList(MAX_BACKUPS, backupFiles.size());
+            logger.info("Deleting {} old backups to maintain maximum of {}", toDelete.size(), MAX_BACKUPS);
+
+            for (Path oldBackup : toDelete) {
+                try {
+                    Files.delete(oldBackup);
+                    logger.info("   Deleted old backup: {}", oldBackup.getFileName());
+                } catch (IOException e) {
+                    logger.warn("Failed to delete old backup: {}", oldBackup, e);
+                }
+            }
+        } else {
+            logger.info("Backup count within limit ({}), no rotation needed", MAX_BACKUPS);
+        }
+    }
+
+    /**
+     * Manual trigger for testing - creates backup immediately if content changed.
+     */
+    public void triggerManualBackup() {
+        logger.info("Manual automatic backup triggered");
+        performAutomaticBackup();
+    }
+
+    /**
+     * Get list of automatic backups for the current library.
+     */
+    public List<BackupInfo> listAutomaticBackups() throws IOException {
+        String libraryId = libraryService.getCurrentLibraryId();
+        if (libraryId == null) {
+            libraryId = "default";
+        }
+
+        Path backupPath = Paths.get(automaticBackupDir, libraryId);
+        if (!Files.exists(backupPath)) {
+            return List.of();
+        }
+
+        try (Stream<Path> stream = Files.list(backupPath)) {
+            return stream
+                    .filter(Files::isRegularFile)
+                    .filter(p -> p.getFileName().toString().startsWith("auto_backup_"))
+                    .filter(p -> p.getFileName().toString().endsWith(".zip"))
+                    .sorted(Comparator.comparing((Path p) -> {
+                        try {
+                            return Files.getLastModifiedTime(p);
+                        } catch (IOException e) {
+                            return null;
+                        }
+                    }).reversed())
+                    .map(p -> {
+                        try {
+                            return new BackupInfo(
+                                    p.getFileName().toString(),
+                                    Files.size(p),
+                                    Files.getLastModifiedTime(p).toInstant().toString()
+                            );
+                        } catch (IOException e) {
+                            return null;
+                        }
+                    })
+                    .filter(info -> info != null)
+                    .collect(Collectors.toList());
+        }
+    }
+
+    /**
+     * Simple backup info class.
+     */
+    public static class BackupInfo {
+        private final String filename;
+        private final long sizeBytes;
+        private final String createdAt;
+
+        public BackupInfo(String filename, long sizeBytes, String createdAt) {
+            this.filename = filename;
+            this.sizeBytes = sizeBytes;
+            this.createdAt = createdAt;
+        }
+
+        public String getFilename() {
+            return filename;
+        }
+
+        public long getSizeBytes() {
+            return sizeBytes;
+        }
+
+        public String getCreatedAt() {
+            return createdAt;
+        }
+    }
+}

backend/src/main/java/com/storycove/service/CollectionService.java

@@ -1,5 +1,6 @@
 package com.storycove.service;
 
+import com.storycove.dto.CollectionDto;
 import com.storycove.dto.SearchResultDto;
 import com.storycove.dto.StoryReadingDto;
 import com.storycove.dto.TagDto;
@@ -50,14 +51,31 @@ public class CollectionService {
     }
     
     /**
-     * Search collections using Typesense (MANDATORY for all search/filter operations)
+     * Search collections using Solr (MANDATORY for all search/filter operations)
      * This method MUST be used instead of JPA queries for listing collections
      */
     public SearchResultDto<Collection> searchCollections(String query, List<String> tags, boolean includeArchived, int page, int limit) {
-        // Collections are currently handled at database level, not indexed in search engine
+        try {
-        // Return empty result for now as collections search is not implemented in OpenSearch
+            // Use SearchServiceAdapter to search collections
-        logger.warn("Collections search not yet implemented in OpenSearch, returning empty results");
+            SearchResultDto<CollectionDto> searchResult = searchServiceAdapter.searchCollections(query, tags, includeArchived, page, limit);
-        return new SearchResultDto<>(new ArrayList<>(), 0, page, limit, query != null ? query : "", 0);
+
+            // Convert CollectionDto back to Collection entities by fetching from database
+            List<Collection> collections = new ArrayList<>();
+            for (CollectionDto dto : searchResult.getResults()) {
+                try {
+                    Collection collection = findByIdBasic(dto.getId());
+                    collections.add(collection);
+                } catch (ResourceNotFoundException e) {
+                    logger.warn("Collection {} found in search index but not in database", dto.getId());
+                }
+            }
+
+            return new SearchResultDto<>(collections, (int) searchResult.getTotalHits(), page, limit,
+                query != null ? query : "", searchResult.getSearchTimeMs());
+        } catch (Exception e) {
+            logger.error("Collection search failed, falling back to empty results", e);
+            return new SearchResultDto<>(new ArrayList<>(), 0, page, limit, query != null ? query : "", 0);
+        }
     }
     
     /**

backend/src/main/java/com/storycove/service/DatabaseManagementService.java

@@ -7,7 +7,6 @@ import org.springframework.beans.factory.annotation.Qualifier;
 import org.springframework.beans.factory.annotation.Value;
 import org.springframework.context.ApplicationContext;
 import org.springframework.context.ApplicationContextAware;
-import org.springframework.core.io.ByteArrayResource;
 import org.springframework.core.io.Resource;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
@@ -70,33 +69,125 @@ public class DatabaseManagementService implements ApplicationContextAware {
         this.applicationContext = applicationContext;
     }
 
+    // Helper methods to extract database connection details
+    private String extractDatabaseUrl() {
+        try (Connection connection = getDataSource().getConnection()) {
+            return connection.getMetaData().getURL();
+        } catch (SQLException e) {
+            throw new RuntimeException("Failed to extract database URL", e);
+        }
+    }
+
+    private String extractDatabaseHost() {
+        String url = extractDatabaseUrl();
+        // Extract host from jdbc:postgresql://host:port/database
+        if (url.startsWith("jdbc:postgresql://")) {
+            String hostPort = url.substring("jdbc:postgresql://".length());
+            if (hostPort.contains("/")) {
+                hostPort = hostPort.substring(0, hostPort.indexOf("/"));
+            }
+            if (hostPort.contains(":")) {
+                return hostPort.substring(0, hostPort.indexOf(":"));
+            }
+            return hostPort;
+        }
+        return "localhost"; // fallback
+    }
+
+    private String extractDatabasePort() {
+        String url = extractDatabaseUrl();
+        // Extract port from jdbc:postgresql://host:port/database
+        if (url.startsWith("jdbc:postgresql://")) {
+            String hostPort = url.substring("jdbc:postgresql://".length());
+            if (hostPort.contains("/")) {
+                hostPort = hostPort.substring(0, hostPort.indexOf("/"));
+            }
+            if (hostPort.contains(":")) {
+                return hostPort.substring(hostPort.indexOf(":") + 1);
+            }
+        }
+        return "5432"; // default PostgreSQL port
+    }
+
+    private String extractDatabaseName() {
+        String url = extractDatabaseUrl();
+        // Extract database name from jdbc:postgresql://host:port/database
+        if (url.startsWith("jdbc:postgresql://")) {
+            String remaining = url.substring("jdbc:postgresql://".length());
+            if (remaining.contains("/")) {
+                String dbPart = remaining.substring(remaining.indexOf("/") + 1);
+                // Remove any query parameters
+                if (dbPart.contains("?")) {
+                    dbPart = dbPart.substring(0, dbPart.indexOf("?"));
+                }
+                return dbPart;
+            }
+        }
+        return "storycove"; // fallback
+    }
+
+    private String extractDatabaseUsername() {
+        // Get from environment variable or default
+        return System.getenv("SPRING_DATASOURCE_USERNAME") != null ?
+               System.getenv("SPRING_DATASOURCE_USERNAME") : "storycove";
+    }
+
+    private String extractDatabasePassword() {
+        // Get from environment variable or default
+        return System.getenv("SPRING_DATASOURCE_PASSWORD") != null ?
+               System.getenv("SPRING_DATASOURCE_PASSWORD") : "password";
+    }
+
     /**
      * Create a comprehensive backup including database and files in ZIP format
+     * Returns a streaming resource to avoid loading large backups into memory
      */
     public Resource createCompleteBackup() throws SQLException, IOException {
+        // Create temp file with deleteOnExit as safety net
         Path tempZip = Files.createTempFile("storycove-backup", ".zip");
-        
+        tempZip.toFile().deleteOnExit();
+
         try (ZipOutputStream zipOut = new ZipOutputStream(Files.newOutputStream(tempZip))) {
             // 1. Add database dump
             addDatabaseDumpToZip(zipOut);
-            
+
             // 2. Add all image files
             addFilesToZip(zipOut);
-            
+
             // 3. Add metadata
             addMetadataToZip(zipOut);
         }
-        
+
-        // Return the ZIP file as a resource
+        // Return the ZIP file as a FileSystemResource for streaming
-        byte[] zipData = Files.readAllBytes(tempZip);
+        // This avoids loading the entire file into memory
-        Files.deleteIfExists(tempZip);
+        return new org.springframework.core.io.FileSystemResource(tempZip.toFile()) {
-        
+            @Override
-        return new ByteArrayResource(zipData);
+            public InputStream getInputStream() throws IOException {
+                // Wrap the input stream to delete the temp file after it's fully read
+                return new java.io.FilterInputStream(super.getInputStream()) {
+                    @Override
+                    public void close() throws IOException {
+                        try {
+                            super.close();
+                        } finally {
+                            // Clean up temp file after streaming is complete
+                            try {
+                                Files.deleteIfExists(tempZip);
+                            } catch (IOException e) {
+                                // Log but don't fail - deleteOnExit will handle it
+                                System.err.println("Warning: Could not delete temp backup file: " + e.getMessage());
+                            }
+                        }
+                    }
+                };
+            }
+        };
     }
 
     /**
      * Restore from complete backup (ZIP format)
      */
+    @Transactional(timeout = 1800) // 30 minutes timeout for large backup restores
     public void restoreFromCompleteBackup(InputStream backupStream) throws IOException, SQLException {
         String currentLibraryId = libraryService.getCurrentLibraryId();
         System.err.println("Starting complete backup restore for library: " + currentLibraryId);
@@ -171,157 +262,201 @@ public class DatabaseManagementService implements ApplicationContextAware {
     }
 
     public Resource createBackup() throws SQLException, IOException {
-        StringBuilder sqlDump = new StringBuilder();
+        // Use PostgreSQL's native pg_dump for reliable backup
-        
+        String dbHost = extractDatabaseHost();
-        try (Connection connection = getDataSource().getConnection()) {
+        String dbPort = extractDatabasePort();
-            // Add header
+        String dbName = extractDatabaseName();
-            sqlDump.append("-- StoryCove Database Backup\n");
+        String dbUser = extractDatabaseUsername();
-            sqlDump.append("-- Generated at: ").append(new java.util.Date()).append("\n\n");
+        String dbPassword = extractDatabasePassword();
-            
+
-            // Disable foreign key checks during restore (PostgreSQL syntax)
+        // Create temporary file for backup
-            sqlDump.append("SET session_replication_role = replica;\n\n");
+        Path tempBackupFile = Files.createTempFile("storycove_backup_", ".sql");
-            
+
-            // List of tables in dependency order (parents first for insertion)
+        try {
-            List<String> insertTables = Arrays.asList(
+            // Build pg_dump command
-                "authors", "series", "tags", "collections",
+            ProcessBuilder pb = new ProcessBuilder(
-                "stories", "story_tags", "author_urls", "collection_stories"
+                "pg_dump",
+                "--host=" + dbHost,
+                "--port=" + dbPort,
+                "--username=" + dbUser,
+                "--dbname=" + dbName,
+                "--no-password",
+                "--verbose",
+                "--clean",
+                "--if-exists",
+                "--create",
+                "--file=" + tempBackupFile.toString()
             );
-            
+
-            // TRUNCATE in reverse order (children first)
+            // Set PGPASSWORD environment variable
-            List<String> truncateTables = Arrays.asList(
+            Map<String, String> env = pb.environment();
-                "collection_stories", "author_urls", "story_tags",
+            env.put("PGPASSWORD", dbPassword);
-                "stories", "collections", "tags", "series", "authors"
+
-            );
+            System.err.println("Starting PostgreSQL backup using pg_dump...");
-            
+            Process process = pb.start();
-            // Generate TRUNCATE statements for each table (assuming tables already exist)
+
-            for (String tableName : truncateTables) {
+            // Capture output
-                sqlDump.append("-- Truncate Table: ").append(tableName).append("\n");
+            try (BufferedReader reader = new BufferedReader(new InputStreamReader(process.getErrorStream()))) {
-                sqlDump.append("TRUNCATE TABLE \"").append(tableName).append("\" CASCADE;\n");
+                String line;
-            }
+                while ((line = reader.readLine()) != null) {
-            sqlDump.append("\n");
+                    System.err.println("pg_dump: " + line);
-            
-            // Generate INSERT statements in dependency order
-            for (String tableName : insertTables) {
-                sqlDump.append("-- Data for Table: ").append(tableName).append("\n");
-                
-                // Get table data
-                try (PreparedStatement stmt = connection.prepareStatement("SELECT * FROM \"" + tableName + "\"");
-                     ResultSet rs = stmt.executeQuery()) {
-                    
-                    ResultSetMetaData metaData = rs.getMetaData();
-                    int columnCount = metaData.getColumnCount();
-                    
-                    // Build column names for INSERT statement
-                    StringBuilder columnNames = new StringBuilder();
-                    for (int i = 1; i <= columnCount; i++) {
-                        if (i > 1) columnNames.append(", ");
-                        columnNames.append("\"").append(metaData.getColumnName(i)).append("\"");
-                    }
-                    
-                    while (rs.next()) {
-                        sqlDump.append("INSERT INTO \"").append(tableName).append("\" (")
-                               .append(columnNames).append(") VALUES (");
-                        
-                        for (int i = 1; i <= columnCount; i++) {
-                            if (i > 1) sqlDump.append(", ");
-                            
-                            Object value = rs.getObject(i);
-                            sqlDump.append(formatSqlValue(value));
-                        }
-                        
-                        sqlDump.append(");\n");
-                    }
                 }
-                
-                sqlDump.append("\n");
             }
-            
+
-            // Re-enable foreign key checks (PostgreSQL syntax)
+            int exitCode = process.waitFor();
-            sqlDump.append("SET session_replication_role = DEFAULT;\n");
+            if (exitCode != 0) {
+                throw new RuntimeException("pg_dump failed with exit code: " + exitCode);
+            }
+
+            System.err.println("PostgreSQL backup completed successfully");
+
+            // Return the backup file as a streaming resource to avoid memory issues with large databases
+            tempBackupFile.toFile().deleteOnExit();
+            return new org.springframework.core.io.FileSystemResource(tempBackupFile.toFile()) {
+                @Override
+                public InputStream getInputStream() throws IOException {
+                    // Wrap the input stream to delete the temp file after it's fully read
+                    return new java.io.FilterInputStream(super.getInputStream()) {
+                        @Override
+                        public void close() throws IOException {
+                            try {
+                                super.close();
+                            } finally {
+                                // Clean up temp file after streaming is complete
+                                try {
+                                    Files.deleteIfExists(tempBackupFile);
+                                } catch (IOException e) {
+                                    // Log but don't fail - deleteOnExit will handle it
+                                    System.err.println("Warning: Could not delete temp backup file: " + e.getMessage());
+                                }
+                            }
+                        }
+                    };
+                }
+            };
+
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException("Backup process was interrupted", e);
         }
-        
-        byte[] backupData = sqlDump.toString().getBytes(StandardCharsets.UTF_8);
-        return new ByteArrayResource(backupData);
     }
 
-    @Transactional
+    @Transactional(timeout = 1800) // 30 minutes timeout for large backup restores
     public void restoreFromBackup(InputStream backupStream) throws IOException, SQLException {
-        // Read the SQL file
+        // Use PostgreSQL's native psql for reliable restore
-        StringBuilder sqlContent = new StringBuilder();
+        String dbHost = extractDatabaseHost();
-        try (BufferedReader reader = new BufferedReader(new InputStreamReader(backupStream, StandardCharsets.UTF_8))) {
+        String dbPort = extractDatabasePort();
-            String line;
+        String dbName = extractDatabaseName();
-            while ((line = reader.readLine()) != null) {
+        String dbUser = extractDatabaseUsername();
-                // Skip comments and empty lines
+        String dbPassword = extractDatabasePassword();
-                if (!line.trim().startsWith("--") && !line.trim().isEmpty()) {
+
-                    sqlContent.append(line).append("\n");
+        // Create temporary file for the backup
+        Path tempBackupFile = Files.createTempFile("storycove_restore_", ".sql");
+
+        try {
+            // Write backup stream to temporary file, filtering out incompatible commands
+            System.err.println("Writing backup data to temporary file...");
+            try (InputStream input = backupStream;
+                 BufferedReader reader = new BufferedReader(new InputStreamReader(input, StandardCharsets.UTF_8));
+                 BufferedWriter writer = Files.newBufferedWriter(tempBackupFile, StandardCharsets.UTF_8)) {
+
+                String line;
+                while ((line = reader.readLine()) != null) {
+                    // Skip DROP DATABASE and CREATE DATABASE commands - we're already connected to the DB
+                    // Also skip database connection commands as we're already connected
+                    if (line.trim().startsWith("DROP DATABASE") ||
+                        line.trim().startsWith("CREATE DATABASE") ||
+                        line.trim().startsWith("\\connect")) {
+                        System.err.println("Skipping incompatible command: " + line.substring(0, Math.min(50, line.length())));
+                        continue;
+                    }
+                    writer.write(line);
+                    writer.newLine();
                 }
             }
-        }
 
-        // Execute the SQL statements
+            System.err.println("Starting PostgreSQL restore using psql...");
-        try (Connection connection = getDataSource().getConnection()) {
+
-            connection.setAutoCommit(false);
+            // Build psql command to restore the backup
-            
+            ProcessBuilder pb = new ProcessBuilder(
-            try {
+                "psql",
-                // Ensure database schema exists before restoring data
+                "--host=" + dbHost,
-                ensureDatabaseSchemaExists(connection);
+                "--port=" + dbPort,
-                
+                "--username=" + dbUser,
-                // Parse SQL statements properly (handle semicolons inside string literals)
+                "--dbname=" + dbName,
-                List<String> statements = parseStatements(sqlContent.toString());
+                "--no-password",
-                
+                "--echo-errors",
-                int successCount = 0;
+                "--file=" + tempBackupFile.toString()
-                for (String statement : statements) {
+            );
-                    String trimmedStatement = statement.trim();
+
-                    if (!trimmedStatement.isEmpty()) {
+            // Set PGPASSWORD environment variable
-                        try (PreparedStatement stmt = connection.prepareStatement(trimmedStatement)) {
+            Map<String, String> env = pb.environment();
-                            stmt.executeUpdate();
+            env.put("PGPASSWORD", dbPassword);
-                            successCount++;
+
-                        } catch (SQLException e) {
+            Process process = pb.start();
-                            // Log detailed error information for failed statements
+
-                            System.err.println("ERROR: Failed to execute SQL statement #" + (successCount + 1));
+            // Capture output
-                            System.err.println("Error: " + e.getMessage());
+            try (BufferedReader reader = new BufferedReader(new InputStreamReader(process.getErrorStream()));
-                            System.err.println("SQL State: " + e.getSQLState());
+                 BufferedReader outputReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
-                            System.err.println("Error Code: " + e.getErrorCode());
+
-                            
+                // Read stderr in a separate thread
-                            // Show the problematic statement (first 500 chars)
+                Thread errorThread = new Thread(() -> {
-                            String statementPreview = trimmedStatement.length() > 500 ? 
+                    try {
-                                trimmedStatement.substring(0, 500) + "..." : trimmedStatement;
+                        String line;
-                            System.err.println("Statement: " + statementPreview);
+                        while ((line = reader.readLine()) != null) {
-                            
+                            System.err.println("psql stderr: " + line);
-                            throw e; // Re-throw to trigger rollback
                         }
+                    } catch (IOException e) {
+                        System.err.println("Error reading psql stderr: " + e.getMessage());
                     }
+                });
+                errorThread.start();
+
+                // Read stdout
+                String line;
+                while ((line = outputReader.readLine()) != null) {
+                    System.err.println("psql stdout: " + line);
                 }
-                
+
-                connection.commit();
+                errorThread.join();
-                System.err.println("Restore completed successfully. Executed " + successCount + " SQL statements.");
+            }
-                
+
-                // Reindex search after successful restore
+            int exitCode = process.waitFor();
-                try {
+            if (exitCode != 0) {
-                    String currentLibraryId = libraryService.getCurrentLibraryId();
+                throw new RuntimeException("psql restore failed with exit code: " + exitCode);
-                    System.err.println("Starting search reindex after successful restore for library: " + currentLibraryId);
+            }
-                    if (currentLibraryId == null) {
+
-                        System.err.println("ERROR: No current library set during restore - cannot reindex search!");
+            System.err.println("PostgreSQL restore completed successfully");
-                        throw new IllegalStateException("No current library active during restore");
+
-                    }
+            // Reindex search after successful restore
-                    
+            try {
-                    // Manually trigger reindexing using the correct database connection
+                String currentLibraryId = libraryService.getCurrentLibraryId();
-                    System.err.println("Triggering manual reindex from library-specific database for library: " + currentLibraryId);
+                System.err.println("Starting search reindex after successful restore for library: " + currentLibraryId);
-                    reindexStoriesAndAuthorsFromCurrentDatabase();
+                if (currentLibraryId == null) {
-                    
+                    System.err.println("ERROR: No current library set during restore - cannot reindex search!");
-                    // Note: Collections collection will be recreated when needed by the service
+                    throw new IllegalStateException("No current library active during restore");
-                    System.err.println("Search reindex completed successfully for library: " + currentLibraryId);
-                } catch (Exception e) {
-                    // Log the error but don't fail the restore
-                    System.err.println("Warning: Failed to reindex search after restore: " + e.getMessage());
-                    e.printStackTrace();
                 }
-                
+
-            } catch (SQLException e) {
+                // Manually trigger reindexing using the correct database connection
-                connection.rollback();
+                System.err.println("Triggering manual reindex from library-specific database for library: " + currentLibraryId);
-                throw e;
+                reindexStoriesAndAuthorsFromCurrentDatabase();
-            } finally {
+
-                connection.setAutoCommit(true);
+                // Note: Collections collection will be recreated when needed by the service
+                System.err.println("Search reindex completed successfully for library: " + currentLibraryId);
+            } catch (Exception e) {
+                // Log the error but don't fail the restore
+                System.err.println("Warning: Failed to reindex search after restore: " + e.getMessage());
+                e.printStackTrace();
+            }
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException("Restore process was interrupted", e);
+        } finally {
+            // Clean up temporary file
+            try {
+                Files.deleteIfExists(tempBackupFile);
+            } catch (IOException e) {
+                System.err.println("Warning: Could not delete temporary restore file: " + e.getMessage());
             }
         }
     }
@@ -449,7 +584,7 @@ public class DatabaseManagementService implements ApplicationContextAware {
     /**
      * Clear all data AND files (for complete restore)
      */
-    @Transactional
+    @Transactional(timeout = 600) // 10 minutes timeout for clearing large datasets
     public int clearAllDataAndFiles() {
         // First clear the database
         int totalDeleted = clearAllData();

backend/src/main/java/com/storycove/service/EPUBImportService.java

@@ -16,6 +16,8 @@ import nl.siegmann.epublib.epub.EpubReader;
 
 import org.jsoup.Jsoup;
 import org.jsoup.nodes.Document;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
@@ -30,6 +32,7 @@ import java.util.Optional;
 @Service
 @Transactional
 public class EPUBImportService {
+    private static final Logger log = LoggerFactory.getLogger(EPUBImportService.class);
     
     private final StoryService storyService;
     private final AuthorService authorService;
@@ -59,64 +62,74 @@ public class EPUBImportService {
     public EPUBImportResponse importEPUB(EPUBImportRequest request) {
         try {
             MultipartFile epubFile = request.getEpubFile();
-            
+
             if (epubFile == null || epubFile.isEmpty()) {
                 return EPUBImportResponse.error("EPUB file is required");
             }
-            
+
             if (!isValidEPUBFile(epubFile)) {
                 return EPUBImportResponse.error("Invalid EPUB file format");
             }
-            
+
+            log.info("Parsing EPUB file: {}", epubFile.getOriginalFilename());
             Book book = parseEPUBFile(epubFile);
-            
+
+            log.info("Creating story entity from EPUB metadata");
             Story story = createStoryFromEPUB(book, request);
-            
+
+            log.info("Saving story to database: {}", story.getTitle());
             Story savedStory = storyService.create(story);
+            log.info("Story saved successfully with ID: {}", savedStory.getId());
 
             // Process embedded images if content contains any
             String originalContent = story.getContentHtml();
             if (originalContent != null && originalContent.contains("<img")) {
                 try {
+                    log.info("Processing embedded images for story: {}", savedStory.getId());
                     ImageService.ContentImageProcessingResult imageResult =
                         imageService.processContentImages(originalContent, savedStory.getId());
 
                     // Update story content with processed images if changed
                     if (!imageResult.getProcessedContent().equals(originalContent)) {
+                        log.info("Updating story content with processed images");
                         savedStory.setContentHtml(imageResult.getProcessedContent());
                         savedStory = storyService.update(savedStory.getId(), savedStory);
 
                         // Log the image processing results
-                        System.out.println("EPUB Import - Image processing completed for story " + savedStory.getId() +
+                        log.info("EPUB Import - Image processing completed for story {}. Downloaded {} images.",
-                                         ". Downloaded " + imageResult.getDownloadedImages().size() + " images.");
+                                savedStory.getId(), imageResult.getDownloadedImages().size());
 
                         if (imageResult.hasWarnings()) {
-                            System.out.println("EPUB Import - Image processing warnings: " +
+                            log.warn("EPUB Import - Image processing warnings: {}",
-                                             String.join(", ", imageResult.getWarnings()));
+                                    String.join(", ", imageResult.getWarnings()));
                         }
                     }
                 } catch (Exception e) {
                     // Log error but don't fail the import
-                    System.err.println("EPUB Import - Failed to process embedded images for story " +
+                    log.error("EPUB Import - Failed to process embedded images for story {}: {}",
-                                     savedStory.getId() + ": " + e.getMessage());
+                            savedStory.getId(), e.getMessage(), e);
                 }
             }
 
+            log.info("Building import response for story: {}", savedStory.getId());
             EPUBImportResponse response = EPUBImportResponse.success(savedStory.getId(), savedStory.getTitle());
             response.setWordCount(savedStory.getWordCount());
             response.setTotalChapters(book.getSpine().size());
-            
+
             if (request.getPreserveReadingPosition() != null && request.getPreserveReadingPosition()) {
+                log.info("Extracting and saving reading position");
                 ReadingPosition readingPosition = extractReadingPosition(book, savedStory);
                 if (readingPosition != null) {
                     ReadingPosition savedPosition = readingPositionRepository.save(readingPosition);
                     response.setReadingPosition(convertToDto(savedPosition));
                 }
             }
-            
+
+            log.info("EPUB import completed successfully for: {}", savedStory.getTitle());
             return response;
-            
+
         } catch (Exception e) {
+            log.error("EPUB import failed with exception: {}", e.getMessage(), e);
             return EPUBImportResponse.error("Failed to import EPUB: " + e.getMessage());
         }
     }
@@ -144,77 +157,119 @@ public class EPUBImportService {
     
     private Story createStoryFromEPUB(Book book, EPUBImportRequest request) {
         Metadata metadata = book.getMetadata();
-        
+
+        log.info("Extracting EPUB metadata");
         String title = extractTitle(metadata);
         String authorName = extractAuthorName(metadata, request);
         String description = extractDescription(metadata);
+
+        log.info("Extracting and sanitizing content from {} chapters", book.getSpine().size());
         String content = extractContent(book);
-        
+
         Story story = new Story();
         story.setTitle(title);
         story.setDescription(description);
         story.setContentHtml(sanitizationService.sanitize(content));
-        
+
         // Extract and process cover image
         if (request.getExtractCover() == null || request.getExtractCover()) {
+            log.info("Extracting cover image");
             String coverPath = extractAndSaveCoverImage(book);
             if (coverPath != null) {
+                log.info("Cover image saved at: {}", coverPath);
                 story.setCoverPath(coverPath);
             }
         }
-        
+
-        if (request.getAuthorId() != null) {
+        // Handle author assignment
-            try {
+        try {
-                Author author = authorService.findById(request.getAuthorId());
+            if (request.getAuthorId() != null) {
+                log.info("Looking up author by ID: {}", request.getAuthorId());
+                try {
+                    Author author = authorService.findById(request.getAuthorId());
+                    story.setAuthor(author);
+                    log.info("Author found and assigned: {}", author.getName());
+                } catch (ResourceNotFoundException e) {
+                    log.warn("Author ID {} not found", request.getAuthorId());
+                    if (request.getCreateMissingAuthor()) {
+                        log.info("Creating new author: {}", authorName);
+                        Author newAuthor = createAuthor(authorName);
+                        story.setAuthor(newAuthor);
+                        log.info("New author created with ID: {}", newAuthor.getId());
+                    }
+                }
+            } else if (authorName != null && request.getCreateMissingAuthor()) {
+                log.info("Finding or creating author: {}", authorName);
+                Author author = findOrCreateAuthor(authorName);
                 story.setAuthor(author);
-            } catch (ResourceNotFoundException e) {
+                log.info("Author assigned: {} (ID: {})", author.getName(), author.getId());
-                if (request.getCreateMissingAuthor()) {
-                    Author newAuthor = createAuthor(authorName);
-                    story.setAuthor(newAuthor);
-                }
             }
-        } else if (authorName != null && request.getCreateMissingAuthor()) {
+        } catch (Exception e) {
-            Author author = findOrCreateAuthor(authorName);
+            log.error("Error handling author assignment: {}", e.getMessage(), e);
-            story.setAuthor(author);
+            throw e;
         }
-        
+
-        if (request.getSeriesId() != null && request.getSeriesVolume() != null) {
+        // Handle series assignment
-            try {
+        try {
-                Series series = seriesService.findById(request.getSeriesId());
+            if (request.getSeriesId() != null && request.getSeriesVolume() != null) {
-                story.setSeries(series);
+                log.info("Looking up series by ID: {}", request.getSeriesId());
-                story.setVolume(request.getSeriesVolume());
+                try {
-            } catch (ResourceNotFoundException e) {
+                    Series series = seriesService.findById(request.getSeriesId());
-                if (request.getCreateMissingSeries() && request.getSeriesName() != null) {
+                    story.setSeries(series);
-                    Series newSeries = createSeries(request.getSeriesName());
-                    story.setSeries(newSeries);
                     story.setVolume(request.getSeriesVolume());
+                    log.info("Series found and assigned: {} (volume {})", series.getName(), request.getSeriesVolume());
+                } catch (ResourceNotFoundException e) {
+                    log.warn("Series ID {} not found", request.getSeriesId());
+                    if (request.getCreateMissingSeries() && request.getSeriesName() != null) {
+                        log.info("Creating new series: {}", request.getSeriesName());
+                        Series newSeries = createSeries(request.getSeriesName());
+                        story.setSeries(newSeries);
+                        story.setVolume(request.getSeriesVolume());
+                        log.info("New series created with ID: {}", newSeries.getId());
+                    }
                 }
             }
+        } catch (Exception e) {
+            log.error("Error handling series assignment: {}", e.getMessage(), e);
+            throw e;
         }
-        
+
         // Handle tags from request or extract from EPUB metadata
-        List<String> allTags = new ArrayList<>();
+        try {
-        if (request.getTags() != null && !request.getTags().isEmpty()) {
+            List<String> allTags = new ArrayList<>();
-            allTags.addAll(request.getTags());
+            if (request.getTags() != null && !request.getTags().isEmpty()) {
+                allTags.addAll(request.getTags());
+            }
+
+            // Extract subjects/keywords from EPUB metadata
+            List<String> epubTags = extractTags(metadata);
+            if (epubTags != null && !epubTags.isEmpty()) {
+                allTags.addAll(epubTags);
+            }
+
+            log.info("Processing {} tags for story", allTags.size());
+            // Remove duplicates and create tags
+            allTags.stream()
+                    .distinct()
+                    .forEach(tagName -> {
+                        try {
+                            log.debug("Finding or creating tag: {}", tagName);
+                            Tag tag = tagService.findOrCreate(tagName.trim());
+                            story.addTag(tag);
+                        } catch (Exception e) {
+                            log.error("Error creating tag '{}': {}", tagName, e.getMessage(), e);
+                            throw e;
+                        }
+                    });
+        } catch (Exception e) {
+            log.error("Error handling tags: {}", e.getMessage(), e);
+            throw e;
         }
-        
+
-        // Extract subjects/keywords from EPUB metadata
-        List<String> epubTags = extractTags(metadata);
-        if (epubTags != null && !epubTags.isEmpty()) {
-            allTags.addAll(epubTags);
-        }
-        
-        // Remove duplicates and create tags
-        allTags.stream()
-                .distinct()
-                .forEach(tagName -> {
-                    Tag tag = tagService.findOrCreate(tagName.trim());
-                    story.addTag(tag);
-                });
-        
         // Extract additional metadata for potential future use
         extractAdditionalMetadata(metadata, story);
-        
+
+        log.info("Story entity created successfully: {}", title);
         return story;
     }
     
@@ -241,7 +296,13 @@ public class EPUBImportService {
     private String extractDescription(Metadata metadata) {
         List<String> descriptions = metadata.getDescriptions();
         if (descriptions != null && !descriptions.isEmpty()) {
-            return descriptions.get(0);
+            String description = descriptions.get(0);
+            // Truncate to 1000 characters if necessary
+            if (description != null && description.length() > 1000) {
+                log.info("Description exceeds 1000 characters ({}), truncating...", description.length());
+                return description.substring(0, 997) + "...";
+            }
+            return description;
         }
         return null;
     }
@@ -282,7 +343,7 @@ public class EPUBImportService {
         if (language != null && !language.trim().isEmpty()) {
             // Store as metadata in story description if needed
             // For now, we'll just log it for potential future use
-            System.out.println("EPUB Language: " + language);
+            log.debug("EPUB Language: {}", language);
         }
         
         // Extract publisher information  
@@ -290,14 +351,14 @@ public class EPUBImportService {
         if (publishers != null && !publishers.isEmpty()) {
             String publisher = publishers.get(0);
             // Could append to description or store separately in future
-            System.out.println("EPUB Publisher: " + publisher);
+            log.debug("EPUB Publisher: {}", publisher);
         }
         
         // Extract publication date
         List<nl.siegmann.epublib.domain.Date> dates = metadata.getDates();
         if (dates != null && !dates.isEmpty()) {
             for (nl.siegmann.epublib.domain.Date date : dates) {
-                System.out.println("EPUB Date (" + date.getEvent() + "): " + date.getValue());
+                log.debug("EPUB Date ({}): {}", date.getEvent(), date.getValue());
             }
         }
         
@@ -305,7 +366,7 @@ public class EPUBImportService {
         List<nl.siegmann.epublib.domain.Identifier> identifiers = metadata.getIdentifiers();
         if (identifiers != null && !identifiers.isEmpty()) {
             for (nl.siegmann.epublib.domain.Identifier identifier : identifiers) {
-                System.out.println("EPUB Identifier (" + identifier.getScheme() + "): " + identifier.getValue());
+                log.debug("EPUB Identifier ({}): {}", identifier.getScheme(), identifier.getValue());
             }
         }
     }

backend/src/main/java/com/storycove/service/HtmlSanitizationService.java

@@ -137,13 +137,64 @@ public class HtmlSanitizationService {
         return config;
     }
     
+    /**
+     * Preprocess HTML to extract images from figure tags before sanitization
+     */
+    private String preprocessFigureTags(String html) {
+        if (html == null || html.trim().isEmpty()) {
+            return html;
+        }
+
+        try {
+            org.jsoup.nodes.Document doc = Jsoup.parse(html);
+            org.jsoup.select.Elements figures = doc.select("figure");
+
+            for (org.jsoup.nodes.Element figure : figures) {
+                // Find img tags within the figure
+                org.jsoup.select.Elements images = figure.select("img");
+
+                if (!images.isEmpty()) {
+                    // Extract the first image and replace the figure with it
+                    org.jsoup.nodes.Element img = images.first();
+
+                    // Check if there's a figcaption to preserve as alt text
+                    org.jsoup.select.Elements figcaptions = figure.select("figcaption");
+                    if (!figcaptions.isEmpty() && !img.hasAttr("alt")) {
+                        String captionText = figcaptions.first().text();
+                        if (captionText != null && !captionText.trim().isEmpty()) {
+                            img.attr("alt", captionText);
+                        }
+                    }
+
+                    // Replace the figure element with just the img
+                    figure.replaceWith(img.clone());
+                    logger.debug("Extracted image from figure tag: {}", img.attr("src"));
+                } else {
+                    // No images in figure, remove it entirely
+                    figure.remove();
+                    logger.debug("Removed figure tag without images");
+                }
+            }
+
+            return doc.body().html();
+        } catch (Exception e) {
+            logger.warn("Failed to preprocess figure tags, returning original HTML: {}", e.getMessage());
+            return html;
+        }
+    }
+
     public String sanitize(String html) {
         if (html == null || html.trim().isEmpty()) {
             return "";
         }
-        logger.info("Content before sanitization: "+html);
+
-        String saniztedHtml = Jsoup.clean(html, allowlist.preserveRelativeLinks(true));
+        logger.debug("Sanitizing HTML content (length: {} characters)", html.length());
-        logger.info("Content after sanitization: "+saniztedHtml);
+
+        // Preprocess to extract images from figure tags
+        String preprocessed = preprocessFigureTags(html);
+
+        String saniztedHtml = Jsoup.clean(preprocessed, allowlist.preserveRelativeLinks(true));
+        logger.debug("Sanitization complete (output length: {} characters)", saniztedHtml.length());
         return saniztedHtml;
     }
     

backend/src/main/java/com/storycove/service/ImageProcessingProgressService.java

@@ -0,0 +1,108 @@
+package com.storycove.service;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.stereotype.Service;
+
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Service
+public class ImageProcessingProgressService {
+
+    private static final Logger logger = LoggerFactory.getLogger(ImageProcessingProgressService.class);
+
+    private final Map<UUID, ImageProcessingProgress> progressMap = new ConcurrentHashMap<>();
+
+    public static class ImageProcessingProgress {
+        private final UUID storyId;
+        private final int totalImages;
+        private volatile int processedImages;
+        private volatile String currentImageUrl;
+        private volatile String status;
+        private volatile boolean completed;
+        private volatile String errorMessage;
+
+        public ImageProcessingProgress(UUID storyId, int totalImages) {
+            this.storyId = storyId;
+            this.totalImages = totalImages;
+            this.processedImages = 0;
+            this.status = "Starting";
+            this.completed = false;
+        }
+
+        // Getters
+        public UUID getStoryId() { return storyId; }
+        public int getTotalImages() { return totalImages; }
+        public int getProcessedImages() { return processedImages; }
+        public String getCurrentImageUrl() { return currentImageUrl; }
+        public String getStatus() { return status; }
+        public boolean isCompleted() { return completed; }
+        public String getErrorMessage() { return errorMessage; }
+        public double getProgressPercentage() {
+            return totalImages > 0 ? (double) processedImages / totalImages * 100 : 100;
+        }
+
+        // Setters
+        public void setProcessedImages(int processedImages) { this.processedImages = processedImages; }
+        public void setCurrentImageUrl(String currentImageUrl) { this.currentImageUrl = currentImageUrl; }
+        public void setStatus(String status) { this.status = status; }
+        public void setCompleted(boolean completed) { this.completed = completed; }
+        public void setErrorMessage(String errorMessage) { this.errorMessage = errorMessage; }
+
+        public void incrementProcessed() {
+            this.processedImages++;
+        }
+    }
+
+    public ImageProcessingProgress startProgress(UUID storyId, int totalImages) {
+        ImageProcessingProgress progress = new ImageProcessingProgress(storyId, totalImages);
+        progressMap.put(storyId, progress);
+        logger.info("Started image processing progress tracking for story {} with {} images", storyId, totalImages);
+        return progress;
+    }
+
+    public ImageProcessingProgress getProgress(UUID storyId) {
+        return progressMap.get(storyId);
+    }
+
+    public void updateProgress(UUID storyId, int processedImages, String currentImageUrl, String status) {
+        ImageProcessingProgress progress = progressMap.get(storyId);
+        if (progress != null) {
+            progress.setProcessedImages(processedImages);
+            progress.setCurrentImageUrl(currentImageUrl);
+            progress.setStatus(status);
+            logger.debug("Updated progress for story {}: {}/{} - {}", storyId, processedImages, progress.getTotalImages(), status);
+        }
+    }
+
+    public void completeProgress(UUID storyId, String finalStatus) {
+        ImageProcessingProgress progress = progressMap.get(storyId);
+        if (progress != null) {
+            progress.setCompleted(true);
+            progress.setStatus(finalStatus);
+            logger.info("Completed image processing for story {}: {}", storyId, finalStatus);
+        }
+    }
+
+    public void setError(UUID storyId, String errorMessage) {
+        ImageProcessingProgress progress = progressMap.get(storyId);
+        if (progress != null) {
+            progress.setErrorMessage(errorMessage);
+            progress.setStatus("Error: " + errorMessage);
+            progress.setCompleted(true);
+            logger.error("Image processing error for story {}: {}", storyId, errorMessage);
+        }
+    }
+
+    public void removeProgress(UUID storyId) {
+        progressMap.remove(storyId);
+        logger.debug("Removed progress tracking for story {}", storyId);
+    }
+
+    public boolean isProcessing(UUID storyId) {
+        ImageProcessingProgress progress = progressMap.get(storyId);
+        return progress != null && !progress.isCompleted();
+    }
+}

backend/src/main/java/com/storycove/service/ImageService.java

@@ -4,6 +4,8 @@ import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.beans.factory.annotation.Autowired;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.event.EventListener;
+import org.springframework.scheduling.annotation.Async;
 import org.springframework.stereotype.Service;
 import org.springframework.web.multipart.MultipartFile;
 
@@ -21,6 +23,8 @@ import java.util.List;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;
 
+import com.storycove.event.StoryContentUpdatedEvent;
+
 @Service
 public class ImageService {
 
@@ -42,6 +46,12 @@ public class ImageService {
 
     @Autowired
     private StoryService storyService;
+
+    @Autowired
+    private AuthorService authorService;
+
+    @Autowired
+    private CollectionService collectionService;
     
     private String getUploadDir() {
         String libraryPath = libraryService.getCurrentImagePath();
@@ -59,7 +69,10 @@ public class ImageService {
     
     @Value("${storycove.images.max-file-size:5242880}") // 5MB default
     private long maxFileSize;
-    
+
+    @Value("${storycove.app.public-url:http://localhost:6925}")
+    private String publicUrl;
+
     public enum ImageType {
         COVER("covers"),
         AVATAR("avatars"),
@@ -248,14 +261,14 @@ public class ImageService {
      * Process HTML content and download all referenced images, replacing URLs with local paths
      */
     public ContentImageProcessingResult processContentImages(String htmlContent, UUID storyId) {
-        logger.info("Processing content images for story: {}, content length: {}", storyId,
+        logger.debug("Processing content images for story: {}, content length: {}", storyId,
                    htmlContent != null ? htmlContent.length() : 0);
 
         List<String> warnings = new ArrayList<>();
         List<String> downloadedImages = new ArrayList<>();
 
         if (htmlContent == null || htmlContent.trim().isEmpty()) {
-            logger.info("No content to process for story: {}", storyId);
+            logger.debug("No content to process for story: {}", storyId);
             return new ContentImageProcessingResult(htmlContent, warnings, downloadedImages);
         }
 
@@ -273,18 +286,18 @@ public class ImageService {
             String imageUrl = matcher.group(1);
             imageCount++;
 
-            logger.info("Found image #{}: {} in tag: {}", imageCount, imageUrl, fullImgTag);
+            logger.debug("Found image #{}: {} in tag: {}", imageCount, imageUrl, fullImgTag);
 
             try {
-                // Skip if it's already a local path or data URL
+                // Skip if it's already a local path, data URL, or from this application
-                if (imageUrl.startsWith("/") || imageUrl.startsWith("data:")) {
+                if (!isExternalUrl(imageUrl)) {
-                    logger.info("Skipping local/data URL: {}", imageUrl);
+                    logger.debug("Skipping local/internal URL: {}", imageUrl);
                     matcher.appendReplacement(processedContent, Matcher.quoteReplacement(fullImgTag));
                     continue;
                 }
 
                 externalImageCount++;
-                logger.info("Processing external image #{}: {}", externalImageCount, imageUrl);
+                logger.debug("Processing external image #{}: {}", externalImageCount, imageUrl);
 
                 // Download and store the image
                 String localPath = downloadImageFromUrl(imageUrl, storyId);
@@ -292,7 +305,7 @@ public class ImageService {
 
                 // Generate local URL
                 String localUrl = getLocalImageUrl(storyId, localPath);
-                logger.info("Downloaded image: {} -> {}", imageUrl, localUrl);
+                logger.debug("Downloaded image: {} -> {}", imageUrl, localUrl);
 
                 // Replace the src attribute with the local path - handle both single and double quotes
                 String newImgTag = fullImgTag
@@ -305,7 +318,7 @@ public class ImageService {
                     newImgTag = fullImgTag.replaceAll("src\\s*=\\s*[\"']?" + Pattern.quote(imageUrl) + "[\"']?", "src=\"" + localUrl + "\"");
                 }
 
-                logger.info("Replaced img tag: {} -> {}", fullImgTag, newImgTag);
+                logger.debug("Replaced img tag: {} -> {}", fullImgTag, newImgTag);
                 matcher.appendReplacement(processedContent, Matcher.quoteReplacement(newImgTag));
 
             } catch (Exception e) {
@@ -324,6 +337,151 @@ public class ImageService {
         return new ContentImageProcessingResult(processedContent.toString(), warnings, downloadedImages);
     }
 
+    /**
+     * Functional interface for progress callbacks during image processing
+     */
+    @FunctionalInterface
+    public interface ImageProcessingProgressCallback {
+        void onProgress(String currentImageUrl, int processedCount, int totalCount);
+    }
+
+    /**
+     * Process content images with progress callbacks for async processing
+     */
+    public ContentImageProcessingResult processContentImagesWithProgress(String htmlContent, UUID storyId, ImageProcessingProgressCallback progressCallback) {
+        logger.debug("Processing content images with progress for story: {}, content length: {}", storyId,
+                   htmlContent != null ? htmlContent.length() : 0);
+
+        List<String> warnings = new ArrayList<>();
+        List<String> downloadedImages = new ArrayList<>();
+
+        if (htmlContent == null || htmlContent.trim().isEmpty()) {
+            logger.debug("No content to process for story: {}", storyId);
+            return new ContentImageProcessingResult(htmlContent, warnings, downloadedImages);
+        }
+
+        // Find all img tags with src attributes
+        Pattern imgPattern = Pattern.compile("<img[^>]+src=[\"']([^\"']+)[\"'][^>]*>", Pattern.CASE_INSENSITIVE);
+        Matcher matcher = imgPattern.matcher(htmlContent);
+
+        // First pass: count external images
+        List<String> externalImages = new ArrayList<>();
+        Matcher countMatcher = imgPattern.matcher(htmlContent);
+        while (countMatcher.find()) {
+            String imageUrl = countMatcher.group(1);
+            if (isExternalUrl(imageUrl)) {
+                externalImages.add(imageUrl);
+            }
+        }
+
+        int totalExternalImages = externalImages.size();
+        int processedCount = 0;
+
+        StringBuffer processedContent = new StringBuffer();
+        matcher.reset(); // Reset the matcher for processing
+
+        while (matcher.find()) {
+            String fullImgTag = matcher.group(0);
+            String imageUrl = matcher.group(1);
+
+            logger.debug("Found image: {} in tag: {}", imageUrl, fullImgTag);
+
+            try {
+                // Skip if it's already a local path, data URL, or from this application
+                if (!isExternalUrl(imageUrl)) {
+                    logger.debug("Skipping local/internal URL: {}", imageUrl);
+                    matcher.appendReplacement(processedContent, Matcher.quoteReplacement(fullImgTag));
+                    continue;
+                }
+
+                // Call progress callback
+                if (progressCallback != null) {
+                    progressCallback.onProgress(imageUrl, processedCount, totalExternalImages);
+                }
+
+                logger.debug("Processing external image #{}: {}", processedCount + 1, imageUrl);
+
+                // Download and store the image
+                String localPath = downloadImageFromUrl(imageUrl, storyId);
+                downloadedImages.add(localPath);
+
+                // Generate local URL
+                String localUrl = getLocalImageUrl(storyId, localPath);
+                logger.debug("Downloaded image: {} -> {}", imageUrl, localUrl);
+
+                // Replace the src attribute with the local path
+                String newImgTag = fullImgTag
+                    .replaceFirst("src=\"" + Pattern.quote(imageUrl) + "\"", "src=\"" + localUrl + "\"")
+                    .replaceFirst("src='" + Pattern.quote(imageUrl) + "'", "src='" + localUrl + "'");
+
+                matcher.appendReplacement(processedContent, Matcher.quoteReplacement(newImgTag));
+                processedCount++;
+
+            } catch (Exception e) {
+                logger.warn("Failed to download image: {} - Error: {}", imageUrl, e.getMessage());
+                warnings.add("Failed to download image: " + imageUrl + " - " + e.getMessage());
+                matcher.appendReplacement(processedContent, Matcher.quoteReplacement(fullImgTag));
+            }
+        }
+
+        matcher.appendTail(processedContent);
+
+        logger.info("Processed {} external images for story: {} (Total: {}, Downloaded: {}, Warnings: {})",
+                   processedCount, storyId, processedCount, downloadedImages.size(), warnings.size());
+
+        return new ContentImageProcessingResult(processedContent.toString(), warnings, downloadedImages);
+    }
+
+    /**
+     * Check if a URL is external (not from this application).
+     * Returns true if the URL should be downloaded, false if it's already local.
+     */
+    private boolean isExternalUrl(String url) {
+        if (url == null || url.trim().isEmpty()) {
+            return false;
+        }
+
+        // Skip data URLs
+        if (url.startsWith("data:")) {
+            return false;
+        }
+
+        // Skip relative URLs (local paths)
+        if (url.startsWith("/")) {
+            return false;
+        }
+
+        // Skip URLs that are already pointing to our API
+        if (url.contains("/api/files/images/")) {
+            return false;
+        }
+
+        // Check if URL starts with the public URL (our own domain)
+        if (publicUrl != null && !publicUrl.trim().isEmpty()) {
+            String normalizedUrl = url.trim().toLowerCase();
+            String normalizedPublicUrl = publicUrl.trim().toLowerCase();
+
+            // Remove trailing slash from public URL for comparison
+            if (normalizedPublicUrl.endsWith("/")) {
+                normalizedPublicUrl = normalizedPublicUrl.substring(0, normalizedPublicUrl.length() - 1);
+            }
+
+            if (normalizedUrl.startsWith(normalizedPublicUrl)) {
+                logger.debug("URL is from this application (matches publicUrl): {}", url);
+                return false;
+            }
+        }
+
+        // If it's an HTTP(S) URL that didn't match our filters, it's external
+        if (url.startsWith("http://") || url.startsWith("https://")) {
+            logger.debug("URL is external: {}", url);
+            return true;
+        }
+
+        // For any other format, consider it non-external (safer default)
+        return false;
+    }
+
     /**
      * Download an image from a URL and store it locally
      */
@@ -388,7 +546,7 @@ public class ImageService {
             return "/api/files/images/default/" + imagePath;
         }
         String localUrl = "/api/files/images/" + currentLibraryId + "/" + imagePath;
-        logger.info("Generated local image URL: {} for story: {}", localUrl, storyId);
+        logger.debug("Generated local image URL: {} for story: {}", localUrl, storyId);
         return localUrl;
     }
 
@@ -437,25 +595,26 @@ public class ImageService {
         int foldersToDelete = 0;
 
         // Step 1: Collect all image references from all story content
-        logger.info("Scanning all story content for image references...");
+        logger.debug("Scanning all story content for image references...");
         referencedImages = collectAllImageReferences();
-        logger.info("Found {} unique image references in story content", referencedImages.size());
+        logger.debug("Found {} unique image references in story content", referencedImages.size());
 
         try {
             // Step 2: Scan the content images directory
             Path contentImagesDir = Paths.get(getUploadDir(), ImageType.CONTENT.getDirectory());
 
             if (!Files.exists(contentImagesDir)) {
-                logger.info("Content images directory does not exist: {}", contentImagesDir);
+                logger.debug("Content images directory does not exist: {}", contentImagesDir);
                 return new ContentImageCleanupResult(orphanedImages, 0, 0, referencedImages.size(), errors, dryRun);
             }
 
-            logger.info("Scanning content images directory: {}", contentImagesDir);
+            logger.debug("Scanning content images directory: {}", contentImagesDir);
 
             // Walk through all story directories
             Files.walk(contentImagesDir, 2)
                 .filter(Files::isDirectory)
                 .filter(path -> !path.equals(contentImagesDir)) // Skip the root content directory
+                .filter(path -> !isSynologySystemPath(path)) // Skip Synology system directories
                 .forEach(storyDir -> {
                     try {
                         String storyId = storyDir.getFileName().toString();
@@ -465,11 +624,13 @@ public class ImageService {
                         boolean storyExists = storyService.findByIdOptional(UUID.fromString(storyId)).isPresent();
 
                         if (!storyExists) {
-                            logger.info("Found orphaned story directory (story deleted): {}", storyId);
+                            logger.debug("Found orphaned story directory (story deleted): {}", storyId);
                             // Mark entire directory for deletion
                             try {
                                 Files.walk(storyDir)
                                     .filter(Files::isRegularFile)
+                                    .filter(path -> !isSynologySystemPath(path)) // Skip Synology system files
+                                    .filter(path -> isValidImageFile(path)) // Only process actual image files
                                     .forEach(file -> {
                                         try {
                                             long size = Files.size(file);
@@ -489,13 +650,18 @@ public class ImageService {
                         try {
                             Files.walk(storyDir)
                                 .filter(Files::isRegularFile)
+                                .filter(path -> !isSynologySystemPath(path)) // Skip Synology system files
+                                .filter(path -> isValidImageFile(path)) // Only process actual image files
                                 .forEach(imageFile -> {
                                     try {
-                                        String imagePath = getRelativeImagePath(imageFile);
+                                        String filename = imageFile.getFileName().toString();
 
-                                        if (!referencedImages.contains(imagePath)) {
+                                        // Only consider it orphaned if it's not in our referenced filenames
-                                            logger.debug("Found orphaned image: {}", imagePath);
+                                        if (!referencedImages.contains(filename)) {
+                                            logger.debug("Found orphaned image: {}", filename);
                                             orphanedImages.add(imageFile.toString());
+                                        } else {
+                                            logger.debug("Image file is referenced, keeping: {}", filename);
                                         }
                                     } catch (Exception e) {
                                         errors.add("Error checking image file " + imageFile + ": " + e.getMessage());
@@ -535,7 +701,7 @@ public class ImageService {
 
             // Step 3: Delete orphaned files if not dry run
             if (!dryRun && !orphanedImages.isEmpty()) {
-                logger.info("Deleting {} orphaned images...", orphanedImages.size());
+                logger.debug("Deleting {} orphaned images...", orphanedImages.size());
 
                 Set<Path> directoriesToCheck = new HashSet<>();
 
@@ -557,7 +723,7 @@ public class ImageService {
                     try {
                         if (Files.exists(dir) && isDirEmpty(dir)) {
                             Files.delete(dir);
-                            logger.info("Deleted empty story directory: {}", dir);
+                            logger.debug("Deleted empty story directory: {}", dir);
                         }
                     } catch (IOException e) {
                         errors.add("Failed to delete empty directory " + dir + ": " + e.getMessage());
@@ -577,10 +743,10 @@ public class ImageService {
     }
 
     /**
-     * Collect all image references from all story content
+     * Collect all image filenames referenced in content (UUID-based filenames only)
      */
     private Set<String> collectAllImageReferences() {
-        Set<String> referencedImages = new HashSet<>();
+        Set<String> referencedFilenames = new HashSet<>();
 
         try {
             // Get all stories
@@ -590,27 +756,70 @@ public class ImageService {
             Pattern imagePattern = Pattern.compile("src=[\"']([^\"']*(?:content/[^\"']*\\.(jpg|jpeg|png)))[\"']", Pattern.CASE_INSENSITIVE);
 
             for (com.storycove.entity.Story story : allStories) {
+                // Add story cover image filename if present
+                if (story.getCoverPath() != null && !story.getCoverPath().trim().isEmpty()) {
+                    String filename = extractFilename(story.getCoverPath());
+                    if (filename != null) {
+                        referencedFilenames.add(filename);
+                        logger.debug("Found cover image filename in story {}: {}", story.getId(), filename);
+                    }
+                }
+
+                // Add author avatar image filename if present
+                if (story.getAuthor() != null && story.getAuthor().getAvatarImagePath() != null && !story.getAuthor().getAvatarImagePath().trim().isEmpty()) {
+                    String filename = extractFilename(story.getAuthor().getAvatarImagePath());
+                    if (filename != null) {
+                        referencedFilenames.add(filename);
+                        logger.debug("Found avatar image filename for author {}: {}", story.getAuthor().getId(), filename);
+                    }
+                }
+
+                // Add content images from HTML
                 if (story.getContentHtml() != null) {
                     Matcher matcher = imagePattern.matcher(story.getContentHtml());
 
                     while (matcher.find()) {
                         String imageSrc = matcher.group(1);
 
-                        // Convert to relative path format that matches our file system
+                        // Extract just the filename from the URL
-                        String relativePath = convertSrcToRelativePath(imageSrc);
+                        String filename = extractFilename(imageSrc);
-                        if (relativePath != null) {
+                        if (filename != null && isUuidBasedFilename(filename)) {
-                            referencedImages.add(relativePath);
+                            referencedFilenames.add(filename);
-                            logger.debug("Found image reference in story {}: {}", story.getId(), relativePath);
+                            logger.debug("Found content image filename in story {}: {}", story.getId(), filename);
                         }
                     }
                 }
             }
 
+            // Also get all authors separately to catch avatars for authors without stories
+            List<com.storycove.entity.Author> allAuthors = authorService.findAll();
+            for (com.storycove.entity.Author author : allAuthors) {
+                if (author.getAvatarImagePath() != null && !author.getAvatarImagePath().trim().isEmpty()) {
+                    String filename = extractFilename(author.getAvatarImagePath());
+                    if (filename != null) {
+                        referencedFilenames.add(filename);
+                        logger.debug("Found standalone avatar image filename for author {}: {}", author.getId(), filename);
+                    }
+                }
+            }
+
+            // Also get all collections to catch cover images
+            List<com.storycove.entity.Collection> allCollections = collectionService.findAllWithTags();
+            for (com.storycove.entity.Collection collection : allCollections) {
+                if (collection.getCoverImagePath() != null && !collection.getCoverImagePath().trim().isEmpty()) {
+                    String filename = extractFilename(collection.getCoverImagePath());
+                    if (filename != null) {
+                        referencedFilenames.add(filename);
+                        logger.debug("Found collection cover image filename for collection {}: {}", collection.getId(), filename);
+                    }
+                }
+            }
+
         } catch (Exception e) {
             logger.error("Error collecting image references from stories", e);
         }
 
-        return referencedImages;
+        return referencedFilenames;
     }
 
     /**
@@ -629,6 +838,64 @@ public class ImageService {
         return null;
     }
 
+    /**
+     * Convert absolute file path to relative path from upload directory
+     */
+    private String convertAbsolutePathToRelative(String absolutePath) {
+        try {
+            if (absolutePath == null || absolutePath.trim().isEmpty()) {
+                return null;
+            }
+
+            Path absPath = Paths.get(absolutePath);
+            Path uploadDirPath = Paths.get(getUploadDir());
+
+            // If the path is already relative to upload dir, return as-is
+            if (!absPath.isAbsolute()) {
+                return absolutePath.replace('\\', '/');
+            }
+
+            // Try to make it relative to the upload directory
+            if (absPath.startsWith(uploadDirPath)) {
+                Path relativePath = uploadDirPath.relativize(absPath);
+                return relativePath.toString().replace('\\', '/');
+            }
+
+            // If it's not under upload directory, check if it's library-specific path
+            String libraryPath = libraryService.getCurrentImagePath();
+            Path baseUploadPath = Paths.get(baseUploadDir);
+
+            if (absPath.startsWith(baseUploadPath)) {
+                Path relativePath = baseUploadPath.relativize(absPath);
+                String relativeStr = relativePath.toString().replace('\\', '/');
+
+                // Remove library prefix if present to make it library-agnostic for comparison
+                if (relativeStr.startsWith(libraryPath.substring(1))) { // Remove leading slash from library path
+                    return relativeStr.substring(libraryPath.length() - 1); // Keep the leading slash
+                }
+                return relativeStr;
+            }
+
+            // Fallback: just use the filename portion if it's in the right structure
+            String fileName = absPath.getFileName().toString();
+            if (fileName.matches(".*\\.(jpg|jpeg|png)$")) {
+                // Try to preserve directory structure if it looks like covers/ or avatars/
+                Path parent = absPath.getParent();
+                if (parent != null) {
+                    String parentName = parent.getFileName().toString();
+                    if (parentName.equals("covers") || parentName.equals("avatars")) {
+                        return parentName + "/" + fileName;
+                    }
+                }
+                return fileName;
+            }
+
+        } catch (Exception e) {
+            logger.debug("Failed to convert absolute path to relative: {}", absolutePath, e);
+        }
+        return null;
+    }
+
     /**
      * Get relative image path from absolute file path
      */
@@ -741,4 +1008,115 @@ public class ImageService {
             return String.format("%.1f GB", totalSizeBytes / (1024.0 * 1024.0 * 1024.0));
         }
     }
+
+    /**
+     * Check if a path is a Synology system path that should be ignored
+     */
+    private boolean isSynologySystemPath(Path path) {
+        String pathStr = path.toString();
+        String fileName = path.getFileName().toString();
+
+        // Skip Synology metadata directories and files
+        return pathStr.contains("@eaDir") ||
+               fileName.startsWith("@") ||
+               fileName.contains("@SynoEAStream") ||
+               fileName.startsWith(".") ||
+               fileName.equals("Thumbs.db") ||
+               fileName.equals(".DS_Store");
+    }
+
+    /**
+     * Check if a file is a valid image file (not a system/metadata file)
+     */
+    private boolean isValidImageFile(Path path) {
+        if (isSynologySystemPath(path)) {
+            return false;
+        }
+
+        String fileName = path.getFileName().toString().toLowerCase();
+        return fileName.endsWith(".jpg") ||
+               fileName.endsWith(".jpeg") ||
+               fileName.endsWith(".png") ||
+               fileName.endsWith(".gif") ||
+               fileName.endsWith(".webp");
+    }
+
+    /**
+     * Extract filename from a path or URL
+     */
+    private String extractFilename(String pathOrUrl) {
+        if (pathOrUrl == null || pathOrUrl.trim().isEmpty()) {
+            return null;
+        }
+
+        try {
+            // Remove query parameters if present
+            if (pathOrUrl.contains("?")) {
+                pathOrUrl = pathOrUrl.substring(0, pathOrUrl.indexOf("?"));
+            }
+
+            // Get the last part after slash
+            String filename = pathOrUrl.substring(pathOrUrl.lastIndexOf("/") + 1);
+
+            // Remove any special Synology suffixes
+            filename = filename.replace("@SynoEAStream", "");
+
+            return filename.trim().isEmpty() ? null : filename;
+        } catch (Exception e) {
+            logger.debug("Failed to extract filename from: {}", pathOrUrl);
+            return null;
+        }
+    }
+
+    /**
+     * Check if a filename follows UUID pattern (indicates it's our generated file)
+     */
+    private boolean isUuidBasedFilename(String filename) {
+        if (filename == null || filename.trim().isEmpty()) {
+            return false;
+        }
+
+        // Remove extension
+        String nameWithoutExt = filename;
+        int lastDot = filename.lastIndexOf(".");
+        if (lastDot > 0) {
+            nameWithoutExt = filename.substring(0, lastDot);
+        }
+
+        // Check if it matches UUID pattern (8-4-4-4-12 hex characters)
+        return nameWithoutExt.matches("[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}");
+    }
+
+    /**
+     * Event listener for story content updates - processes external images asynchronously
+     */
+    @EventListener
+    @Async
+    public void handleStoryContentUpdated(StoryContentUpdatedEvent event) {
+        logger.info("Processing images for {} story {} after content update",
+                   event.isNewStory() ? "new" : "updated", event.getStoryId());
+
+        try {
+            ContentImageProcessingResult result = processContentImages(event.getContentHtml(), event.getStoryId());
+
+            // If content was changed, we need to update the story (but this could cause circular events)
+            // Instead, let's just log the results for now and let the controller handle updates if needed
+            if (result.hasWarnings()) {
+                logger.warn("Image processing warnings for story {}: {}", event.getStoryId(), result.getWarnings());
+            }
+            if (!result.getDownloadedImages().isEmpty()) {
+                logger.info("Downloaded {} external images for story {}: {}",
+                           result.getDownloadedImages().size(), event.getStoryId(), result.getDownloadedImages());
+            }
+
+            // TODO: If content was changed, we might need a way to update the story without triggering another event
+            if (!result.getProcessedContent().equals(event.getContentHtml())) {
+                logger.info("Story {} content was processed and external images were replaced with local URLs", event.getStoryId());
+                // For now, just log that processing occurred - the original content processing already handles updates
+            }
+
+        } catch (Exception e) {
+            logger.error("Failed to process images for story {}: {}", event.getStoryId(), e.getMessage(), e);
+        }
+    }
 }

backend/src/main/java/com/storycove/service/LibraryService.java

@@ -115,7 +115,7 @@ public class LibraryService implements ApplicationContextAware {
     
     /**
      * Switch to library after authentication with forced reindexing
-     * This ensures OpenSearch is always up-to-date after login
+     * This ensures Solr is always up-to-date after login
      */
     public synchronized void switchToLibraryAfterAuthentication(String libraryId) throws Exception {
         logger.info("Switching to library after authentication: {} (forcing reindex)", libraryId);
@@ -144,9 +144,9 @@ public class LibraryService implements ApplicationContextAware {
         String previousLibraryId = currentLibraryId;
         
         if (libraryId.equals(currentLibraryId) && forceReindex) {
-            logger.info("Forcing reindex for current library: {} ({})", library.getName(), libraryId);
+            logger.debug("Forcing reindex for current library: {} ({})", library.getName(), libraryId);
         } else {
-            logger.info("Switching to library: {} ({})", library.getName(), libraryId);
+            logger.debug("Switching to library: {} ({})", library.getName(), libraryId);
         }
         
         // Close current resources
@@ -154,15 +154,15 @@ public class LibraryService implements ApplicationContextAware {
         
         // Set new active library (datasource routing handled by SmartRoutingDataSource)
         currentLibraryId = libraryId;
-        // OpenSearch indexes are global - no per-library initialization needed
+        // Solr indexes are global - no per-library initialization needed
-        logger.info("Library switched to OpenSearch mode for library: {}", libraryId);
+        logger.debug("Library switched to Solr mode for library: {}", libraryId);
         
         logger.info("Successfully switched to library: {}", library.getName());
         
         // Perform complete reindex AFTER library switch is fully complete
         // This ensures database routing is properly established
         if (forceReindex || !libraryId.equals(previousLibraryId)) {
-            logger.info("Starting post-switch OpenSearch reindex for library: {}", libraryId);
+            logger.debug("Starting post-switch Solr reindex for library: {}", libraryId);
 
             // Run reindex asynchronously to avoid blocking authentication response
             // and allow time for database routing to fully stabilize
@@ -171,7 +171,7 @@ public class LibraryService implements ApplicationContextAware {
                 try {
                     // Give routing time to stabilize
                     Thread.sleep(500);
-                    logger.info("Starting async OpenSearch reindex for library: {}", finalLibraryId);
+                    logger.debug("Starting async Solr reindex for library: {}", finalLibraryId);
 
                     SearchServiceAdapter searchService = applicationContext.getBean(SearchServiceAdapter.class);
                     // Get all stories and authors for reindexing
@@ -184,12 +184,12 @@ public class LibraryService implements ApplicationContextAware {
                     searchService.bulkIndexStories(allStories);
                     searchService.bulkIndexAuthors(allAuthors);
 
-                    logger.info("Completed async OpenSearch reindexing for library: {} ({} stories, {} authors)",
+                    logger.info("Completed async Solr reindexing for library: {} ({} stories, {} authors)",
                         finalLibraryId, allStories.size(), allAuthors.size());
                 } catch (Exception e) {
-                    logger.warn("Failed to async reindex OpenSearch for library {}: {}", finalLibraryId, e.getMessage());
+                    logger.warn("Failed to async reindex Solr for library {}: {}", finalLibraryId, e.getMessage());
                 }
-            }, "OpenSearchReindex-" + libraryId).start();
+            }, "SolrReindex-" + libraryId).start();
         }
     }
     
@@ -342,10 +342,10 @@ public class LibraryService implements ApplicationContextAware {
                     library.setInitialized((Boolean) data.getOrDefault("initialized", false));
                     
                     libraries.put(id, library);
-                    logger.info("Loaded library: {} ({})", library.getName(), id);
+                    logger.debug("Loaded library: {} ({})", library.getName(), id);
                 }
             } else {
-                logger.info("No libraries configuration file found, will create default");
+                logger.debug("No libraries configuration file found, will create default");
             }
         } catch (IOException e) {
             logger.error("Failed to load libraries configuration", e);
@@ -411,7 +411,7 @@ public class LibraryService implements ApplicationContextAware {
             String json = objectMapper.writerWithDefaultPrettyPrinter().writeValueAsString(config);
             Files.writeString(Paths.get(LIBRARIES_CONFIG_PATH), json);
             
-            logger.info("Saved libraries configuration");
+            logger.debug("Saved libraries configuration");
         } catch (IOException e) {
             logger.error("Failed to save libraries configuration", e);
         }
@@ -419,7 +419,7 @@ public class LibraryService implements ApplicationContextAware {
     
     private DataSource createDataSource(String dbName) {
         String url = baseDbUrl.replaceAll("/[^/]*$", "/" + dbName);
-        logger.info("Creating DataSource for: {}", url);
+        logger.debug("Creating DataSource for: {}", url);
         
         // First, ensure the database exists
         ensureDatabaseExists(dbName);
@@ -459,7 +459,7 @@ public class LibraryService implements ApplicationContextAware {
                 preparedStatement.setString(1, dbName);
                 try (var resultSet = preparedStatement.executeQuery()) {
                     if (resultSet.next()) {
-                        logger.info("Database {} already exists", dbName);
+                        logger.debug("Database {} already exists", dbName);
                         return; // Database exists, nothing to do
                     }
                 }
@@ -488,7 +488,7 @@ public class LibraryService implements ApplicationContextAware {
     }
     
     private void initializeNewDatabaseSchema(String dbName) {
-        logger.info("Initializing schema for new database: {}", dbName);
+        logger.debug("Initializing schema for new database: {}", dbName);
         
         // Create a temporary DataSource for the new database to initialize schema
         String newDbUrl = baseDbUrl.replaceAll("/[^/]*$", "/" + dbName);
@@ -505,7 +505,7 @@ public class LibraryService implements ApplicationContextAware {
             // Use Hibernate to create the schema
             // This mimics what Spring Boot does during startup
             createSchemaUsingHibernate(tempDataSource);
-            logger.info("Schema initialized for database: {}", dbName);
+            logger.debug("Schema initialized for database: {}", dbName);
             
         } catch (Exception e) {
             logger.error("Failed to initialize schema for database {}: {}", dbName, e.getMessage());
@@ -520,15 +520,15 @@ public class LibraryService implements ApplicationContextAware {
         }
         
         try {
-            logger.info("Initializing resources for new library: {}", library.getName());
+            logger.debug("Initializing resources for new library: {}", library.getName());
             
             // 1. Create image directory structure
             initializeImageDirectories(library);
             
-            // 2. OpenSearch indexes are global and managed automatically
+            // 2. Solr indexes are global and managed automatically
-            // No per-library initialization needed for OpenSearch
+            // No per-library initialization needed for Solr
             
-            logger.info("Successfully initialized resources for library: {}", library.getName());
+            logger.debug("Successfully initialized resources for library: {}", library.getName());
             
         } catch (Exception e) {
             logger.error("Failed to initialize resources for library {}: {}", libraryId, e.getMessage());
@@ -544,16 +544,16 @@ public class LibraryService implements ApplicationContextAware {
             
             if (!java.nio.file.Files.exists(libraryImagePath)) {
                 java.nio.file.Files.createDirectories(libraryImagePath);
-                logger.info("Created image directory: {}", imagePath);
+                logger.debug("Created image directory: {}", imagePath);
                 
                 // Create subdirectories for different image types
                 java.nio.file.Files.createDirectories(libraryImagePath.resolve("stories"));
                 java.nio.file.Files.createDirectories(libraryImagePath.resolve("authors"));  
                 java.nio.file.Files.createDirectories(libraryImagePath.resolve("collections"));
                 
-                logger.info("Created image subdirectories for library: {}", library.getId());
+                logger.debug("Created image subdirectories for library: {}", library.getId());
             } else {
-                logger.info("Image directory already exists: {}", imagePath);
+                logger.debug("Image directory already exists: {}", imagePath);
             }
             
         } catch (Exception e) {
@@ -749,7 +749,7 @@ public class LibraryService implements ApplicationContextAware {
                 statement.executeUpdate(sql);
             }
             
-            logger.info("Successfully created all database tables and constraints");
+            logger.debug("Successfully created all database tables and constraints");
             
         } catch (SQLException e) {
             logger.error("Failed to create database schema", e);
@@ -760,7 +760,7 @@ public class LibraryService implements ApplicationContextAware {
     
     private void closeCurrentResources() {
         // No need to close datasource - SmartRoutingDataSource handles this
-        // OpenSearch service is managed by Spring - no explicit cleanup needed
+        // Solr service is managed by Spring - no explicit cleanup needed
         // Don't clear currentLibraryId here - only when explicitly switching
     }
     

backend/src/main/java/com/storycove/service/LibraryStatisticsService.java

@@ -0,0 +1,643 @@
+package com.storycove.service;
+
+import com.storycove.config.SolrProperties;
+import com.storycove.dto.*;
+import com.storycove.dto.LibraryOverviewStatsDto.StoryWordCountDto;
+import com.storycove.repository.CollectionRepository;
+import org.apache.solr.client.solrj.SolrClient;
+import org.apache.solr.client.solrj.SolrQuery;
+import org.apache.solr.client.solrj.SolrServerException;
+import org.apache.solr.client.solrj.response.FacetField;
+import org.apache.solr.client.solrj.response.QueryResponse;
+import org.apache.solr.common.SolrDocument;
+import org.apache.solr.common.params.StatsParams;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
+import org.springframework.stereotype.Service;
+
+import java.io.IOException;
+import java.time.LocalDate;
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+import java.time.format.DateTimeFormatter;
+import java.util.*;
+import java.util.stream.Collectors;
+
+@Service
+@ConditionalOnProperty(
+    value = "storycove.search.engine",
+    havingValue = "solr",
+    matchIfMissing = false
+)
+public class LibraryStatisticsService {
+
+    private static final Logger logger = LoggerFactory.getLogger(LibraryStatisticsService.class);
+    private static final int WORDS_PER_MINUTE = 250;
+
+    @Autowired(required = false)
+    private SolrClient solrClient;
+
+    @Autowired
+    private SolrProperties properties;
+
+    @Autowired
+    private LibraryService libraryService;
+
+    @Autowired
+    private CollectionRepository collectionRepository;
+
+    /**
+     * Get overview statistics for a library
+     */
+    public LibraryOverviewStatsDto getOverviewStatistics(String libraryId) throws IOException, SolrServerException {
+        LibraryOverviewStatsDto stats = new LibraryOverviewStatsDto();
+
+        // Collection Overview
+        stats.setTotalStories(getTotalStories(libraryId));
+        stats.setTotalAuthors(getTotalAuthors(libraryId));
+        stats.setTotalSeries(getTotalSeries(libraryId));
+        stats.setTotalTags(getTotalTags(libraryId));
+        stats.setTotalCollections(getTotalCollections(libraryId));
+        stats.setUniqueSourceDomains(getUniqueSourceDomains(libraryId));
+
+        // Content Metrics - use Solr Stats Component
+        WordCountStats wordStats = getWordCountStatistics(libraryId);
+        stats.setTotalWordCount(wordStats.sum);
+        stats.setAverageWordsPerStory(wordStats.mean);
+        stats.setLongestStory(getLongestStory(libraryId));
+        stats.setShortestStory(getShortestStory(libraryId));
+
+        // Reading Time
+        stats.setTotalReadingTimeMinutes(wordStats.sum / WORDS_PER_MINUTE);
+        stats.setAverageReadingTimeMinutes(wordStats.mean / WORDS_PER_MINUTE);
+
+        return stats;
+    }
+
+    /**
+     * Get total number of stories in library
+     */
+    private long getTotalStories(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0); // We only want the count
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        return response.getResults().getNumFound();
+    }
+
+    /**
+     * Get total number of authors in library
+     */
+    private long getTotalAuthors(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+
+        QueryResponse response = solrClient.query(properties.getCores().getAuthors(), query);
+        return response.getResults().getNumFound();
+    }
+
+    /**
+     * Get total number of series using faceting on seriesId
+     */
+    private long getTotalSeries(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("seriesId:[* TO *]"); // Only stories that have a series
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("seriesId");
+        query.setFacetLimit(-1); // Get all unique series
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField seriesFacet = response.getFacetField("seriesId");
+
+        return (seriesFacet != null && seriesFacet.getValues() != null)
+                ? seriesFacet.getValueCount()
+                : 0;
+    }
+
+    /**
+     * Get total number of unique tags using faceting
+     */
+    private long getTotalTags(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("tagNames");
+        query.setFacetLimit(-1); // Get all unique tags
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField tagsFacet = response.getFacetField("tagNames");
+
+        return (tagsFacet != null && tagsFacet.getValues() != null)
+                ? tagsFacet.getValueCount()
+                : 0;
+    }
+
+    /**
+     * Get total number of collections
+     */
+    private long getTotalCollections(String libraryId) {
+        // Collections are stored in the database, not indexed in Solr
+        return collectionRepository.countByIsArchivedFalse();
+    }
+
+    /**
+     * Get number of unique source domains using faceting
+     */
+    private long getUniqueSourceDomains(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("sourceDomain:[* TO *]"); // Only stories with a source domain
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("sourceDomain");
+        query.setFacetLimit(-1);
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField domainFacet = response.getFacetField("sourceDomain");
+
+        return (domainFacet != null && domainFacet.getValues() != null)
+                ? domainFacet.getValueCount()
+                : 0;
+    }
+
+    /**
+     * Get word count statistics using Solr Stats Component
+     */
+    private WordCountStats getWordCountStatistics(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setParam(StatsParams.STATS, true);
+        query.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+
+        WordCountStats stats = new WordCountStats();
+
+        // Extract stats from response
+        var fieldStatsInfo = response.getFieldStatsInfo();
+        if (fieldStatsInfo != null && fieldStatsInfo.get("wordCount") != null) {
+            var fieldStat = fieldStatsInfo.get("wordCount");
+
+            Object sumObj = fieldStat.getSum();
+            Object meanObj = fieldStat.getMean();
+
+            stats.sum = (sumObj != null) ? ((Number) sumObj).longValue() : 0L;
+            stats.mean = (meanObj != null) ? ((Number) meanObj).doubleValue() : 0.0;
+        }
+
+        return stats;
+    }
+
+    /**
+     * Get the longest story in the library
+     */
+    private StoryWordCountDto getLongestStory(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("wordCount:[1 TO *]"); // Exclude stories with 0 words
+        query.setSort("wordCount", SolrQuery.ORDER.desc);
+        query.setRows(1);
+        query.setFields("id", "title", "authorName", "wordCount");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+
+        if (response.getResults().isEmpty()) {
+            return null;
+        }
+
+        SolrDocument doc = response.getResults().get(0);
+        return createStoryWordCountDto(doc);
+    }
+
+    /**
+     * Get the shortest story in the library (excluding 0 word count)
+     */
+    private StoryWordCountDto getShortestStory(String libraryId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("wordCount:[1 TO *]"); // Exclude stories with 0 words
+        query.setSort("wordCount", SolrQuery.ORDER.asc);
+        query.setRows(1);
+        query.setFields("id", "title", "authorName", "wordCount");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+
+        if (response.getResults().isEmpty()) {
+            return null;
+        }
+
+        SolrDocument doc = response.getResults().get(0);
+        return createStoryWordCountDto(doc);
+    }
+
+    /**
+     * Helper method to create StoryWordCountDto from Solr document
+     */
+    private StoryWordCountDto createStoryWordCountDto(SolrDocument doc) {
+        String id = (String) doc.getFieldValue("id");
+        String title = (String) doc.getFieldValue("title");
+        String authorName = (String) doc.getFieldValue("authorName");
+        Object wordCountObj = doc.getFieldValue("wordCount");
+        int wordCount = (wordCountObj != null) ? ((Number) wordCountObj).intValue() : 0;
+        long readingTime = wordCount / WORDS_PER_MINUTE;
+
+        return new StoryWordCountDto(id, title, authorName, wordCount, readingTime);
+    }
+
+    /**
+     * Helper class to hold word count statistics
+     */
+    private static class WordCountStats {
+        long sum = 0;
+        double mean = 0.0;
+    }
+
+    /**
+     * Get top tags statistics
+     */
+    public TopTagsStatsDto getTopTagsStatistics(String libraryId, int limit) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("tagNames");
+        query.setFacetLimit(limit);
+        query.setFacetSort("count"); // Sort by count (most popular first)
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField tagsFacet = response.getFacetField("tagNames");
+
+        List<TopTagsStatsDto.TagStatsDto> topTags = new ArrayList<>();
+        if (tagsFacet != null && tagsFacet.getValues() != null) {
+            for (FacetField.Count count : tagsFacet.getValues()) {
+                topTags.add(new TopTagsStatsDto.TagStatsDto(count.getName(), count.getCount()));
+            }
+        }
+
+        return new TopTagsStatsDto(topTags);
+    }
+
+    /**
+     * Get top authors statistics
+     */
+    public TopAuthorsStatsDto getTopAuthorsStatistics(String libraryId, int limit) throws IOException, SolrServerException {
+        TopAuthorsStatsDto stats = new TopAuthorsStatsDto();
+
+        // Top authors by story count
+        stats.setTopAuthorsByStories(getTopAuthorsByStoryCount(libraryId, limit));
+
+        // Top authors by total words
+        stats.setTopAuthorsByWords(getTopAuthorsByWordCount(libraryId, limit));
+
+        return stats;
+    }
+
+    private List<TopAuthorsStatsDto.AuthorStatsDto> getTopAuthorsByStoryCount(String libraryId, int limit)
+            throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("authorId");
+        query.setFacetLimit(limit);
+        query.setFacetSort("count");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField authorFacet = response.getFacetField("authorId");
+
+        List<TopAuthorsStatsDto.AuthorStatsDto> topAuthors = new ArrayList<>();
+        if (authorFacet != null && authorFacet.getValues() != null) {
+            for (FacetField.Count count : authorFacet.getValues()) {
+                String authorId = count.getName();
+                long storyCount = count.getCount();
+
+                // Get author name and total words
+                SolrQuery authorQuery = new SolrQuery("authorId:" + authorId);
+                authorQuery.addFilterQuery("libraryId:" + libraryId);
+                authorQuery.setRows(1);
+                authorQuery.setFields("authorName");
+
+                QueryResponse authorResponse = solrClient.query(properties.getCores().getStories(), authorQuery);
+                String authorName = "";
+                if (!authorResponse.getResults().isEmpty()) {
+                    authorName = (String) authorResponse.getResults().get(0).getFieldValue("authorName");
+                }
+
+                // Get total words for this author
+                long totalWords = getAuthorTotalWords(libraryId, authorId);
+
+                topAuthors.add(new TopAuthorsStatsDto.AuthorStatsDto(authorId, authorName, storyCount, totalWords));
+            }
+        }
+
+        return topAuthors;
+    }
+
+    private List<TopAuthorsStatsDto.AuthorStatsDto> getTopAuthorsByWordCount(String libraryId, int limit)
+            throws IOException, SolrServerException {
+        // First get all unique authors
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("authorId");
+        query.setFacetLimit(-1); // Get all authors
+        query.setFacetSort("count");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        FacetField authorFacet = response.getFacetField("authorId");
+
+        List<TopAuthorsStatsDto.AuthorStatsDto> allAuthors = new ArrayList<>();
+        if (authorFacet != null && authorFacet.getValues() != null) {
+            for (FacetField.Count count : authorFacet.getValues()) {
+                String authorId = count.getName();
+                long storyCount = count.getCount();
+
+                // Get author name
+                SolrQuery authorQuery = new SolrQuery("authorId:" + authorId);
+                authorQuery.addFilterQuery("libraryId:" + libraryId);
+                authorQuery.setRows(1);
+                authorQuery.setFields("authorName");
+
+                QueryResponse authorResponse = solrClient.query(properties.getCores().getStories(), authorQuery);
+                String authorName = "";
+                if (!authorResponse.getResults().isEmpty()) {
+                    authorName = (String) authorResponse.getResults().get(0).getFieldValue("authorName");
+                }
+
+                // Get total words for this author
+                long totalWords = getAuthorTotalWords(libraryId, authorId);
+
+                allAuthors.add(new TopAuthorsStatsDto.AuthorStatsDto(authorId, authorName, storyCount, totalWords));
+            }
+        }
+
+        // Sort by total words and return top N
+        return allAuthors.stream()
+                .sorted(Comparator.comparingLong(TopAuthorsStatsDto.AuthorStatsDto::getTotalWords).reversed())
+                .limit(limit)
+                .collect(Collectors.toList());
+    }
+
+    private long getAuthorTotalWords(String libraryId, String authorId) throws IOException, SolrServerException {
+        SolrQuery query = new SolrQuery("authorId:" + authorId);
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.setRows(0);
+        query.setParam(StatsParams.STATS, true);
+        query.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+
+        var fieldStatsInfo = response.getFieldStatsInfo();
+        if (fieldStatsInfo != null && fieldStatsInfo.get("wordCount") != null) {
+            var fieldStat = fieldStatsInfo.get("wordCount");
+            Object sumObj = fieldStat.getSum();
+            return (sumObj != null) ? ((Number) sumObj).longValue() : 0L;
+        }
+
+        return 0L;
+    }
+
+    /**
+     * Get rating statistics
+     */
+    public RatingStatsDto getRatingStatistics(String libraryId) throws IOException, SolrServerException {
+        RatingStatsDto stats = new RatingStatsDto();
+
+        // Get average rating using stats component
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("rating:[* TO *]"); // Only rated stories
+        query.setRows(0);
+        query.setParam(StatsParams.STATS, true);
+        query.setParam(StatsParams.STATS_FIELD, "rating");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        long totalRated = response.getResults().getNumFound();
+
+        var fieldStatsInfo = response.getFieldStatsInfo();
+        if (fieldStatsInfo != null && fieldStatsInfo.get("rating") != null) {
+            var fieldStat = fieldStatsInfo.get("rating");
+            Object meanObj = fieldStat.getMean();
+            stats.setAverageRating((meanObj != null) ? ((Number) meanObj).doubleValue() : 0.0);
+        }
+
+        stats.setTotalRatedStories(totalRated);
+
+        // Get total stories to calculate unrated
+        long totalStories = getTotalStories(libraryId);
+        stats.setTotalUnratedStories(totalStories - totalRated);
+
+        // Get rating distribution using faceting
+        SolrQuery distQuery = new SolrQuery("*:*");
+        distQuery.addFilterQuery("libraryId:" + libraryId);
+        distQuery.addFilterQuery("rating:[* TO *]");
+        distQuery.setRows(0);
+        distQuery.setFacet(true);
+        distQuery.addFacetField("rating");
+        distQuery.setFacetLimit(-1);
+
+        QueryResponse distResponse = solrClient.query(properties.getCores().getStories(), distQuery);
+        FacetField ratingFacet = distResponse.getFacetField("rating");
+
+        Map<Integer, Long> distribution = new HashMap<>();
+        if (ratingFacet != null && ratingFacet.getValues() != null) {
+            for (FacetField.Count count : ratingFacet.getValues()) {
+                try {
+                    int rating = Integer.parseInt(count.getName());
+                    distribution.put(rating, count.getCount());
+                } catch (NumberFormatException e) {
+                    // Skip invalid ratings
+                }
+            }
+        }
+
+        stats.setRatingDistribution(distribution);
+
+        return stats;
+    }
+
+    /**
+     * Get source domain statistics
+     */
+    public SourceDomainStatsDto getSourceDomainStatistics(String libraryId, int limit) throws IOException, SolrServerException {
+        SourceDomainStatsDto stats = new SourceDomainStatsDto();
+
+        // Get top domains using faceting
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("sourceDomain:[* TO *]"); // Only stories with source
+        query.setRows(0);
+        query.setFacet(true);
+        query.addFacetField("sourceDomain");
+        query.setFacetLimit(limit);
+        query.setFacetSort("count");
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        long storiesWithSource = response.getResults().getNumFound();
+
+        FacetField domainFacet = response.getFacetField("sourceDomain");
+
+        List<SourceDomainStatsDto.DomainStatsDto> topDomains = new ArrayList<>();
+        if (domainFacet != null && domainFacet.getValues() != null) {
+            for (FacetField.Count count : domainFacet.getValues()) {
+                topDomains.add(new SourceDomainStatsDto.DomainStatsDto(count.getName(), count.getCount()));
+            }
+        }
+
+        stats.setTopDomains(topDomains);
+        stats.setStoriesWithSource(storiesWithSource);
+
+        long totalStories = getTotalStories(libraryId);
+        stats.setStoriesWithoutSource(totalStories - storiesWithSource);
+
+        return stats;
+    }
+
+    /**
+     * Get reading progress statistics
+     */
+    public ReadingProgressStatsDto getReadingProgressStatistics(String libraryId) throws IOException, SolrServerException {
+        ReadingProgressStatsDto stats = new ReadingProgressStatsDto();
+
+        long totalStories = getTotalStories(libraryId);
+        stats.setTotalStories(totalStories);
+
+        // Get read stories count
+        SolrQuery readQuery = new SolrQuery("*:*");
+        readQuery.addFilterQuery("libraryId:" + libraryId);
+        readQuery.addFilterQuery("isRead:true");
+        readQuery.setRows(0);
+
+        QueryResponse readResponse = solrClient.query(properties.getCores().getStories(), readQuery);
+        long readStories = readResponse.getResults().getNumFound();
+
+        stats.setReadStories(readStories);
+        stats.setUnreadStories(totalStories - readStories);
+
+        if (totalStories > 0) {
+            stats.setPercentageRead((readStories * 100.0) / totalStories);
+        }
+
+        // Get total words read
+        SolrQuery readWordsQuery = new SolrQuery("*:*");
+        readWordsQuery.addFilterQuery("libraryId:" + libraryId);
+        readWordsQuery.addFilterQuery("isRead:true");
+        readWordsQuery.setRows(0);
+        readWordsQuery.setParam(StatsParams.STATS, true);
+        readWordsQuery.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+        QueryResponse readWordsResponse = solrClient.query(properties.getCores().getStories(), readWordsQuery);
+        var readFieldStats = readWordsResponse.getFieldStatsInfo();
+        if (readFieldStats != null && readFieldStats.get("wordCount") != null) {
+            var fieldStat = readFieldStats.get("wordCount");
+            Object sumObj = fieldStat.getSum();
+            stats.setTotalWordsRead((sumObj != null) ? ((Number) sumObj).longValue() : 0L);
+        }
+
+        // Get total words unread
+        SolrQuery unreadWordsQuery = new SolrQuery("*:*");
+        unreadWordsQuery.addFilterQuery("libraryId:" + libraryId);
+        unreadWordsQuery.addFilterQuery("isRead:false");
+        unreadWordsQuery.setRows(0);
+        unreadWordsQuery.setParam(StatsParams.STATS, true);
+        unreadWordsQuery.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+        QueryResponse unreadWordsResponse = solrClient.query(properties.getCores().getStories(), unreadWordsQuery);
+        var unreadFieldStats = unreadWordsResponse.getFieldStatsInfo();
+        if (unreadFieldStats != null && unreadFieldStats.get("wordCount") != null) {
+            var fieldStat = unreadFieldStats.get("wordCount");
+            Object sumObj = fieldStat.getSum();
+            stats.setTotalWordsUnread((sumObj != null) ? ((Number) sumObj).longValue() : 0L);
+        }
+
+        return stats;
+    }
+
+    /**
+     * Get reading activity statistics for the last week
+     */
+    public ReadingActivityStatsDto getReadingActivityStatistics(String libraryId) throws IOException, SolrServerException {
+        ReadingActivityStatsDto stats = new ReadingActivityStatsDto();
+
+        LocalDateTime oneWeekAgo = LocalDateTime.now().minusWeeks(1);
+        String oneWeekAgoStr = oneWeekAgo.toInstant(ZoneOffset.UTC).toString();
+
+        // Get stories read in last week
+        SolrQuery query = new SolrQuery("*:*");
+        query.addFilterQuery("libraryId:" + libraryId);
+        query.addFilterQuery("lastReadAt:[" + oneWeekAgoStr + " TO *]");
+        query.setRows(0);
+
+        QueryResponse response = solrClient.query(properties.getCores().getStories(), query);
+        long storiesReadLastWeek = response.getResults().getNumFound();
+        stats.setStoriesReadLastWeek(storiesReadLastWeek);
+
+        // Get words read in last week
+        SolrQuery wordsQuery = new SolrQuery("*:*");
+        wordsQuery.addFilterQuery("libraryId:" + libraryId);
+        wordsQuery.addFilterQuery("lastReadAt:[" + oneWeekAgoStr + " TO *]");
+        wordsQuery.setRows(0);
+        wordsQuery.setParam(StatsParams.STATS, true);
+        wordsQuery.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+        QueryResponse wordsResponse = solrClient.query(properties.getCores().getStories(), wordsQuery);
+        var fieldStatsInfo = wordsResponse.getFieldStatsInfo();
+        long wordsReadLastWeek = 0L;
+        if (fieldStatsInfo != null && fieldStatsInfo.get("wordCount") != null) {
+            var fieldStat = fieldStatsInfo.get("wordCount");
+            Object sumObj = fieldStat.getSum();
+            wordsReadLastWeek = (sumObj != null) ? ((Number) sumObj).longValue() : 0L;
+        }
+
+        stats.setWordsReadLastWeek(wordsReadLastWeek);
+        stats.setReadingTimeMinutesLastWeek(wordsReadLastWeek / WORDS_PER_MINUTE);
+
+        // Get daily activity (last 7 days)
+        List<ReadingActivityStatsDto.DailyActivityDto> dailyActivity = new ArrayList<>();
+        for (int i = 6; i >= 0; i--) {
+            LocalDate date = LocalDate.now().minusDays(i);
+            LocalDateTime dayStart = date.atStartOfDay();
+            LocalDateTime dayEnd = date.atTime(23, 59, 59);
+
+            String dayStartStr = dayStart.toInstant(ZoneOffset.UTC).toString();
+            String dayEndStr = dayEnd.toInstant(ZoneOffset.UTC).toString();
+
+            SolrQuery dayQuery = new SolrQuery("*:*");
+            dayQuery.addFilterQuery("libraryId:" + libraryId);
+            dayQuery.addFilterQuery("lastReadAt:[" + dayStartStr + " TO " + dayEndStr + "]");
+            dayQuery.setRows(0);
+            dayQuery.setParam(StatsParams.STATS, true);
+            dayQuery.setParam(StatsParams.STATS_FIELD, "wordCount");
+
+            QueryResponse dayResponse = solrClient.query(properties.getCores().getStories(), dayQuery);
+            long storiesRead = dayResponse.getResults().getNumFound();
+
+            long wordsRead = 0L;
+            var dayFieldStats = dayResponse.getFieldStatsInfo();
+            if (dayFieldStats != null && dayFieldStats.get("wordCount") != null) {
+                var fieldStat = dayFieldStats.get("wordCount");
+                Object sumObj = fieldStat.getSum();
+                wordsRead = (sumObj != null) ? ((Number) sumObj).longValue() : 0L;
+            }
+
+            dailyActivity.add(new ReadingActivityStatsDto.DailyActivityDto(
+                    date.format(DateTimeFormatter.ISO_LOCAL_DATE),
+                    storiesRead,
+                    wordsRead
+            ));
+        }
+
+        stats.setDailyActivity(dailyActivity);
+
+        return stats;
+    }
+}

backend/src/main/java/com/storycove/service/OpenSearchHealthService.java

@@ -1,133 +0,0 @@
-package com.storycove.service;
-
-import com.storycove.config.OpenSearchProperties;
-import org.opensearch.client.opensearch.OpenSearchClient;
-import org.opensearch.client.opensearch.cluster.HealthRequest;
-import org.opensearch.client.opensearch.cluster.HealthResponse;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
-import org.springframework.beans.factory.annotation.Autowired;
-import org.springframework.boot.actuate.health.Health;
-import org.springframework.boot.actuate.health.HealthIndicator;
-import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
-import org.springframework.scheduling.annotation.Scheduled;
-import org.springframework.stereotype.Service;
-
-import java.time.LocalDateTime;
-import java.util.concurrent.atomic.AtomicReference;
-
-@Service
-@ConditionalOnProperty(name = "storycove.search.engine", havingValue = "opensearch")
-public class OpenSearchHealthService implements HealthIndicator {
-
-    private static final Logger logger = LoggerFactory.getLogger(OpenSearchHealthService.class);
-
-    private final OpenSearchClient openSearchClient;
-    private final OpenSearchProperties properties;
-
-    private final AtomicReference<Health> lastKnownHealth = new AtomicReference<>(Health.unknown().build());
-    private LocalDateTime lastCheckTime = LocalDateTime.now();
-
-    @Autowired
-    public OpenSearchHealthService(OpenSearchClient openSearchClient, OpenSearchProperties properties) {
-        this.openSearchClient = openSearchClient;
-        this.properties = properties;
-    }
-
-    @Override
-    public Health health() {
-        return lastKnownHealth.get();
-    }
-
-    @Scheduled(fixedDelayString = "#{@openSearchProperties.health.checkInterval}")
-    public void performHealthCheck() {
-        try {
-            HealthResponse clusterHealth = openSearchClient.cluster().health(
-                HealthRequest.of(h -> h.timeout(t -> t.time("10s")))
-            );
-
-            Health.Builder healthBuilder = Health.up()
-                .withDetail("cluster_name", clusterHealth.clusterName())
-                .withDetail("status", clusterHealth.status().jsonValue())
-                .withDetail("number_of_nodes", clusterHealth.numberOfNodes())
-                .withDetail("number_of_data_nodes", clusterHealth.numberOfDataNodes())
-                .withDetail("active_primary_shards", clusterHealth.activePrimaryShards())
-                .withDetail("active_shards", clusterHealth.activeShards())
-                .withDetail("relocating_shards", clusterHealth.relocatingShards())
-                .withDetail("initializing_shards", clusterHealth.initializingShards())
-                .withDetail("unassigned_shards", clusterHealth.unassignedShards())
-                .withDetail("last_check", LocalDateTime.now());
-
-            // Check if cluster status is concerning
-            switch (clusterHealth.status()) {
-                case Red:
-                    healthBuilder = Health.down()
-                        .withDetail("reason", "Cluster status is RED - some primary shards are unassigned");
-                    break;
-                case Yellow:
-                    if (isProduction()) {
-                        healthBuilder = Health.down()
-                            .withDetail("reason", "Cluster status is YELLOW - some replica shards are unassigned (critical in production)");
-                    } else {
-                        // Yellow is acceptable in development (single node clusters)
-                        healthBuilder.withDetail("warning", "Cluster status is YELLOW - acceptable for development");
-                    }
-                    break;
-                case Green:
-                    // All good
-                    break;
-            }
-
-            lastKnownHealth.set(healthBuilder.build());
-            lastCheckTime = LocalDateTime.now();
-
-            if (properties.getHealth().isEnableMetrics()) {
-                logMetrics(clusterHealth);
-            }
-
-        } catch (Exception e) {
-            logger.error("OpenSearch health check failed", e);
-            Health unhealthyStatus = Health.down()
-                .withDetail("error", e.getMessage())
-                .withDetail("last_successful_check", lastCheckTime)
-                .withDetail("current_time", LocalDateTime.now())
-                .build();
-            lastKnownHealth.set(unhealthyStatus);
-        }
-    }
-
-    private void logMetrics(HealthResponse clusterHealth) {
-        logger.info("OpenSearch Cluster Metrics - Status: {}, Nodes: {}, Active Shards: {}, Unassigned: {}",
-            clusterHealth.status().jsonValue(),
-            clusterHealth.numberOfNodes(),
-            clusterHealth.activeShards(),
-            clusterHealth.unassignedShards());
-    }
-
-    private boolean isProduction() {
-        return "production".equalsIgnoreCase(properties.getProfile());
-    }
-
-    /**
-     * Manual health check for immediate status
-     */
-    public boolean isClusterHealthy() {
-        Health currentHealth = lastKnownHealth.get();
-        return currentHealth.getStatus() == org.springframework.boot.actuate.health.Status.UP;
-    }
-
-    /**
-     * Get detailed cluster information
-     */
-    public String getClusterInfo() {
-        try {
-            var info = openSearchClient.info();
-            return String.format("OpenSearch %s (Cluster: %s, Lucene: %s)",
-                info.version().number(),
-                info.clusterName(),
-                info.version().luceneVersion());
-        } catch (Exception e) {
-            return "Unable to retrieve cluster information: " + e.getMessage();
-        }
-    }
-}

backend/src/main/java/com/storycove/service/PDFImportService.java

@@ -0,0 +1,683 @@
+package com.storycove.service;
+
+import com.storycove.dto.FileImportResponse;
+import com.storycove.dto.PDFImportRequest;
+import com.storycove.entity.*;
+import com.storycove.service.exception.InvalidFileException;
+import com.storycove.service.exception.ResourceNotFoundException;
+
+import org.apache.pdfbox.Loader;
+import org.apache.pdfbox.pdmodel.PDDocument;
+import org.apache.pdfbox.pdmodel.PDDocumentInformation;
+import org.apache.pdfbox.pdmodel.PDPage;
+import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;
+import org.apache.pdfbox.text.PDFTextStripper;
+import org.apache.pdfbox.text.TextPosition;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.multipart.MultipartFile;
+
+import javax.imageio.ImageIO;
+import java.awt.image.BufferedImage;
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.io.InputStream;
+import java.util.*;
+import java.util.regex.Pattern;
+
+@Service
+@Transactional
+public class PDFImportService {
+    private static final Logger log = LoggerFactory.getLogger(PDFImportService.class);
+
+    private static final Pattern PAGE_NUMBER_PATTERN = Pattern.compile("^\\s*\\d+\\s*$");
+    private static final int MAX_FILE_SIZE = 300 * 1024 * 1024; // 300MB
+
+    private final StoryService storyService;
+    private final AuthorService authorService;
+    private final SeriesService seriesService;
+    private final TagService tagService;
+    private final HtmlSanitizationService sanitizationService;
+    private final ImageService imageService;
+    private final LibraryService libraryService;
+
+    @Autowired
+    public PDFImportService(StoryService storyService,
+                           AuthorService authorService,
+                           SeriesService seriesService,
+                           TagService tagService,
+                           HtmlSanitizationService sanitizationService,
+                           ImageService imageService,
+                           LibraryService libraryService) {
+        this.storyService = storyService;
+        this.authorService = authorService;
+        this.seriesService = seriesService;
+        this.tagService = tagService;
+        this.sanitizationService = sanitizationService;
+        this.imageService = imageService;
+        this.libraryService = libraryService;
+    }
+
+    public FileImportResponse importPDF(PDFImportRequest request) {
+        try {
+            MultipartFile pdfFile = request.getPdfFile();
+
+            if (pdfFile == null || pdfFile.isEmpty()) {
+                return FileImportResponse.error("PDF file is required", null);
+            }
+
+            if (!isValidPDFFile(pdfFile)) {
+                return FileImportResponse.error("Invalid PDF file format", pdfFile.getOriginalFilename());
+            }
+
+            log.info("Parsing PDF file: {}", pdfFile.getOriginalFilename());
+            PDDocument document = parsePDFFile(pdfFile);
+
+            try {
+                log.info("Extracting metadata from PDF");
+                PDFMetadata metadata = extractMetadata(document, pdfFile.getOriginalFilename());
+
+                // Validate author is provided
+                String authorName = determineAuthorName(request, metadata);
+                if (authorName == null || authorName.trim().isEmpty()) {
+                    return FileImportResponse.error("Author name is required for PDF import. No author found in PDF metadata.", pdfFile.getOriginalFilename());
+                }
+
+                log.info("Extracting content and images from PDF");
+                PDFContent content = extractContentWithImages(document, request.getExtractImages());
+
+                log.info("Creating story entity from PDF");
+                Story story = createStoryFromPDF(metadata, content, request, authorName);
+
+                log.info("Saving story to database: {}", story.getTitle());
+                Story savedStory = storyService.create(story);
+                log.info("Story saved successfully with ID: {}", savedStory.getId());
+
+                // Process and save embedded images if any were extracted
+                if (request.getExtractImages() && !content.getImages().isEmpty()) {
+                    try {
+                        log.info("Processing {} embedded images for story: {}", content.getImages().size(), savedStory.getId());
+                        String updatedContent = processAndSaveImages(content, savedStory.getId());
+
+                        if (!updatedContent.equals(savedStory.getContentHtml())) {
+                            savedStory.setContentHtml(updatedContent);
+                            savedStory = storyService.update(savedStory.getId(), savedStory);
+                            log.info("Story content updated with processed images");
+                        }
+                    } catch (Exception e) {
+                        log.error("Failed to process embedded images for story {}: {}", savedStory.getId(), e.getMessage(), e);
+                    }
+                }
+
+                log.info("PDF import completed successfully for: {}", savedStory.getTitle());
+                FileImportResponse response = FileImportResponse.success(savedStory.getId(), savedStory.getTitle(), "PDF");
+                response.setFileName(pdfFile.getOriginalFilename());
+                response.setWordCount(savedStory.getWordCount());
+                response.setExtractedImages(content.getImages().size());
+
+                return response;
+
+            } finally {
+                document.close();
+            }
+
+        } catch (Exception e) {
+            log.error("PDF import failed with exception: {}", e.getMessage(), e);
+            return FileImportResponse.error("Failed to import PDF: " + e.getMessage(),
+                request.getPdfFile() != null ? request.getPdfFile().getOriginalFilename() : null);
+        }
+    }
+
+    private boolean isValidPDFFile(MultipartFile file) {
+        String filename = file.getOriginalFilename();
+        if (filename == null || !filename.toLowerCase().endsWith(".pdf")) {
+            return false;
+        }
+
+        if (file.getSize() > MAX_FILE_SIZE) {
+            log.warn("PDF file size {} exceeds maximum {}", file.getSize(), MAX_FILE_SIZE);
+            return false;
+        }
+
+        String contentType = file.getContentType();
+        return "application/pdf".equals(contentType) || contentType == null;
+    }
+
+    private PDDocument parsePDFFile(MultipartFile pdfFile) throws IOException {
+        try (InputStream inputStream = pdfFile.getInputStream()) {
+            return Loader.loadPDF(inputStream.readAllBytes());
+        } catch (Exception e) {
+            throw new InvalidFileException("Failed to parse PDF file: " + e.getMessage());
+        }
+    }
+
+    private PDFMetadata extractMetadata(PDDocument document, String fileName) {
+        PDFMetadata metadata = new PDFMetadata();
+        PDDocumentInformation info = document.getDocumentInformation();
+
+        if (info != null) {
+            metadata.setTitle(info.getTitle());
+            metadata.setAuthor(info.getAuthor());
+            metadata.setSubject(info.getSubject());
+            metadata.setKeywords(info.getKeywords());
+            metadata.setCreator(info.getCreator());
+        }
+
+        // Use filename as fallback title
+        if (metadata.getTitle() == null || metadata.getTitle().trim().isEmpty()) {
+            String titleFromFilename = fileName.replaceAll("\\.pdf$", "").replaceAll("[_-]", " ");
+            metadata.setTitle(titleFromFilename);
+        }
+
+        metadata.setPageCount(document.getNumberOfPages());
+
+        return metadata;
+    }
+
+    private PDFContent extractContentWithImages(PDDocument document, Boolean extractImages) throws IOException {
+        PDFContent content = new PDFContent();
+        StringBuilder htmlContent = new StringBuilder();
+        List<PDFImage> images = new ArrayList<>();
+
+        boolean shouldExtractImages = extractImages != null && extractImages;
+
+        // Extract images first to know their positions
+        if (shouldExtractImages) {
+            images = extractImagesFromPDF(document);
+            log.info("Extracted {} images from PDF", images.size());
+        }
+
+        // Extract text with custom stripper to filter headers/footers
+        CustomPDFTextStripper stripper = new CustomPDFTextStripper();
+        stripper.setSortByPosition(true);
+
+        // Process page by page to insert images at correct positions
+        for (int pageNum = 0; pageNum < document.getNumberOfPages(); pageNum++) {
+            stripper.setStartPage(pageNum + 1);
+            stripper.setEndPage(pageNum + 1);
+
+            String pageText = stripper.getText(document);
+
+            // Filter out obvious page numbers and headers/footers
+            pageText = filterHeadersFooters(pageText, pageNum + 1);
+
+            if (pageText != null && !pageText.trim().isEmpty()) {
+                // Convert text to HTML paragraphs
+                String[] paragraphs = pageText.split("\\n\\s*\\n");
+
+                for (String para : paragraphs) {
+                    String trimmed = para.trim();
+                    if (!trimmed.isEmpty() && !isLikelyHeaderFooter(trimmed)) {
+                        htmlContent.append("<p>").append(escapeHtml(trimmed)).append("</p>\n");
+                    }
+                }
+            }
+
+            // Insert images that belong to this page
+            if (shouldExtractImages) {
+                for (PDFImage image : images) {
+                    if (image.getPageNumber() == pageNum) {
+                        // Add placeholder for image (will be replaced with actual path after saving)
+                        htmlContent.append("<img data-pdf-image-id=\"")
+                                  .append(image.getImageId())
+                                  .append("\" alt=\"Image from PDF\" />\n");
+                    }
+                }
+            }
+        }
+
+        content.setHtmlContent(htmlContent.toString());
+        content.setImages(images);
+
+        return content;
+    }
+
+    private List<PDFImage> extractImagesFromPDF(PDDocument document) {
+        List<PDFImage> images = new ArrayList<>();
+        int imageCounter = 0;
+
+        for (int pageNum = 0; pageNum < document.getNumberOfPages(); pageNum++) {
+            try {
+                PDPage page = document.getPage(pageNum);
+
+                // Get all images from the page resources
+                Iterable<org.apache.pdfbox.cos.COSName> names = page.getResources().getXObjectNames();
+                for (org.apache.pdfbox.cos.COSName name : names) {
+                    try {
+                        org.apache.pdfbox.pdmodel.graphics.PDXObject xObject = page.getResources().getXObject(name);
+
+                        if (xObject instanceof PDImageXObject) {
+                            PDImageXObject imageObj = (PDImageXObject) xObject;
+                            BufferedImage bImage = imageObj.getImage();
+
+                            // Skip very small images (likely decorative or icons)
+                            if (bImage.getWidth() < 50 || bImage.getHeight() < 50) {
+                                continue;
+                            }
+
+                            // Convert BufferedImage to byte array
+                            ByteArrayOutputStream baos = new ByteArrayOutputStream();
+                            ImageIO.write(bImage, "png", baos);
+                            byte[] imageBytes = baos.toByteArray();
+
+                            PDFImage pdfImage = new PDFImage();
+                            pdfImage.setImageId("pdf-img-" + imageCounter);
+                            pdfImage.setPageNumber(pageNum);
+                            pdfImage.setImageData(imageBytes);
+                            pdfImage.setWidth(bImage.getWidth());
+                            pdfImage.setHeight(bImage.getHeight());
+
+                            images.add(pdfImage);
+                            imageCounter++;
+                        }
+                    } catch (Exception e) {
+                        log.warn("Failed to extract image '{}' from page {}: {}", name, pageNum, e.getMessage());
+                    }
+                }
+            } catch (Exception e) {
+                log.warn("Failed to process images on page {}: {}", pageNum, e.getMessage());
+            }
+        }
+
+        return images;
+    }
+
+    private String processAndSaveImages(PDFContent content, UUID storyId) throws IOException {
+        String htmlContent = content.getHtmlContent();
+
+        // Get current library ID for constructing image URLs
+        String currentLibraryId = libraryService.getCurrentLibraryId();
+        if (currentLibraryId == null || currentLibraryId.trim().isEmpty()) {
+            log.warn("Current library ID is null or empty when processing PDF images for story: {}", storyId);
+            currentLibraryId = "default";
+        }
+
+        for (PDFImage image : content.getImages()) {
+            try {
+                // Create a MultipartFile from the image bytes
+                MultipartFile imageFile = new PDFImageMultipartFile(
+                    image.getImageData(),
+                    "pdf-image-" + image.getImageId() + ".png",
+                    "image/png"
+                );
+
+                // Save the image using ImageService (ImageType.CONTENT saves to content directory)
+                String imagePath = imageService.uploadImage(imageFile, ImageService.ImageType.CONTENT);
+
+                // Construct the full URL with library ID
+                // imagePath will be like "content/uuid.png"
+                String imageUrl = "/api/files/images/" + currentLibraryId + "/" + imagePath;
+
+                // Replace placeholder with actual image URL
+                String placeholder = "data-pdf-image-id=\"" + image.getImageId() + "\"";
+                String replacement = "src=\"" + imageUrl + "\"";
+                htmlContent = htmlContent.replace(placeholder, replacement);
+
+                log.debug("Saved PDF image {} to path: {} (URL: {})", image.getImageId(), imagePath, imageUrl);
+
+            } catch (Exception e) {
+                log.error("Failed to save PDF image {}: {}", image.getImageId(), e.getMessage());
+                // Remove the placeholder if we failed to save the image
+                htmlContent = htmlContent.replaceAll(
+                    "<img data-pdf-image-id=\"" + image.getImageId() + "\"[^>]*>",
+                    ""
+                );
+            }
+        }
+
+        return htmlContent;
+    }
+
+    private String filterHeadersFooters(String text, int pageNumber) {
+        if (text == null) return "";
+
+        String[] lines = text.split("\\n");
+        if (lines.length <= 2) return text; // Too short to have headers/footers
+
+        StringBuilder filtered = new StringBuilder();
+
+        // Skip first line if it looks like a header
+        int startIdx = 0;
+        if (lines.length > 1 && isLikelyHeaderFooter(lines[0])) {
+            startIdx = 1;
+        }
+
+        // Skip last line if it looks like a footer or page number
+        int endIdx = lines.length;
+        if (lines.length > 1 && isLikelyHeaderFooter(lines[lines.length - 1])) {
+            endIdx = lines.length - 1;
+        }
+
+        for (int i = startIdx; i < endIdx; i++) {
+            filtered.append(lines[i]).append("\n");
+        }
+
+        return filtered.toString();
+    }
+
+    private boolean isLikelyHeaderFooter(String line) {
+        String trimmed = line.trim();
+
+        // Check if it's just a page number
+        if (PAGE_NUMBER_PATTERN.matcher(trimmed).matches()) {
+            return true;
+        }
+
+        // Check if it's very short (likely header/footer)
+        if (trimmed.length() < 3) {
+            return true;
+        }
+
+        // Check for common header/footer patterns
+        String lower = trimmed.toLowerCase();
+        if (lower.matches(".*page \\d+.*") ||
+            lower.matches(".*\\d+ of \\d+.*") ||
+            lower.matches("chapter \\d+") ||
+            lower.matches("\\d+")) {
+            return true;
+        }
+
+        return false;
+    }
+
+    private String determineAuthorName(PDFImportRequest request, PDFMetadata metadata) {
+        // Priority: request.authorName > request.authorId > metadata.author
+        if (request.getAuthorName() != null && !request.getAuthorName().trim().isEmpty()) {
+            return request.getAuthorName().trim();
+        }
+
+        if (request.getAuthorId() != null) {
+            try {
+                Author author = authorService.findById(request.getAuthorId());
+                return author.getName();
+            } catch (ResourceNotFoundException e) {
+                log.warn("Author ID {} not found", request.getAuthorId());
+            }
+        }
+
+        if (metadata.getAuthor() != null && !metadata.getAuthor().trim().isEmpty()) {
+            return metadata.getAuthor().trim();
+        }
+
+        return null;
+    }
+
+    private Story createStoryFromPDF(PDFMetadata metadata, PDFContent content,
+                                    PDFImportRequest request, String authorName) {
+        Story story = new Story();
+        story.setTitle(metadata.getTitle() != null ? metadata.getTitle() : "Untitled PDF");
+        story.setDescription(metadata.getSubject());
+        story.setContentHtml(sanitizationService.sanitize(content.getHtmlContent()));
+
+        // Handle author assignment
+        try {
+            if (request.getAuthorId() != null) {
+                try {
+                    Author author = authorService.findById(request.getAuthorId());
+                    story.setAuthor(author);
+                } catch (ResourceNotFoundException e) {
+                    if (request.getCreateMissingAuthor()) {
+                        Author newAuthor = createAuthor(authorName);
+                        story.setAuthor(newAuthor);
+                    }
+                }
+            } else if (authorName != null && request.getCreateMissingAuthor()) {
+                Author author = findOrCreateAuthor(authorName);
+                story.setAuthor(author);
+            }
+        } catch (Exception e) {
+            log.error("Error handling author assignment: {}", e.getMessage(), e);
+            throw e;
+        }
+
+        // Handle series assignment
+        try {
+            if (request.getSeriesId() != null && request.getSeriesVolume() != null) {
+                try {
+                    Series series = seriesService.findById(request.getSeriesId());
+                    story.setSeries(series);
+                    story.setVolume(request.getSeriesVolume());
+                } catch (ResourceNotFoundException e) {
+                    if (request.getCreateMissingSeries() && request.getSeriesName() != null) {
+                        Series newSeries = createSeries(request.getSeriesName());
+                        story.setSeries(newSeries);
+                        story.setVolume(request.getSeriesVolume());
+                    }
+                }
+            }
+        } catch (Exception e) {
+            log.error("Error handling series assignment: {}", e.getMessage(), e);
+            throw e;
+        }
+
+        // Handle tags
+        try {
+            List<String> allTags = new ArrayList<>();
+            if (request.getTags() != null && !request.getTags().isEmpty()) {
+                allTags.addAll(request.getTags());
+            }
+
+            // Extract keywords from PDF metadata
+            if (metadata.getKeywords() != null && !metadata.getKeywords().trim().isEmpty()) {
+                String[] keywords = metadata.getKeywords().split("[,;]");
+                for (String keyword : keywords) {
+                    String trimmed = keyword.trim();
+                    if (!trimmed.isEmpty()) {
+                        allTags.add(trimmed);
+                    }
+                }
+            }
+
+            // Create tags
+            allTags.stream()
+                    .distinct()
+                    .forEach(tagName -> {
+                        try {
+                            Tag tag = tagService.findOrCreate(tagName.trim());
+                            story.addTag(tag);
+                        } catch (Exception e) {
+                            log.error("Error creating tag '{}': {}", tagName, e.getMessage(), e);
+                        }
+                    });
+        } catch (Exception e) {
+            log.error("Error handling tags: {}", e.getMessage(), e);
+            throw e;
+        }
+
+        return story;
+    }
+
+    private Author findOrCreateAuthor(String authorName) {
+        Optional<Author> existingAuthor = authorService.findByNameOptional(authorName);
+        if (existingAuthor.isPresent()) {
+            return existingAuthor.get();
+        }
+        return createAuthor(authorName);
+    }
+
+    private Author createAuthor(String authorName) {
+        Author author = new Author();
+        author.setName(authorName);
+        return authorService.create(author);
+    }
+
+    private Series createSeries(String seriesName) {
+        Series series = new Series();
+        series.setName(seriesName);
+        return seriesService.create(series);
+    }
+
+    private String escapeHtml(String text) {
+        return text.replace("&", "&amp;")
+                   .replace("<", "&lt;")
+                   .replace(">", "&gt;")
+                   .replace("\"", "&quot;")
+                   .replace("'", "&#39;")
+                   .replace("\n", "<br/>");
+    }
+
+    public List<String> validatePDFFile(MultipartFile file) {
+        List<String> errors = new ArrayList<>();
+
+        if (file == null || file.isEmpty()) {
+            errors.add("PDF file is required");
+            return errors;
+        }
+
+        if (!isValidPDFFile(file)) {
+            errors.add("Invalid PDF file format. Only .pdf files are supported");
+        }
+
+        if (file.getSize() > MAX_FILE_SIZE) {
+            errors.add("PDF file size exceeds " + (MAX_FILE_SIZE / 1024 / 1024) + "MB limit");
+        }
+
+        try {
+            PDDocument document = parsePDFFile(file);
+            try {
+                if (document.getNumberOfPages() == 0) {
+                    errors.add("PDF file contains no pages");
+                }
+            } finally {
+                document.close();
+            }
+        } catch (Exception e) {
+            errors.add("Failed to parse PDF file: " + e.getMessage());
+        }
+
+        return errors;
+    }
+
+    // Inner classes for data structures
+
+    private static class PDFMetadata {
+        private String title;
+        private String author;
+        private String subject;
+        private String keywords;
+        private String creator;
+        private int pageCount;
+
+        public String getTitle() { return title; }
+        public void setTitle(String title) { this.title = title; }
+        public String getAuthor() { return author; }
+        public void setAuthor(String author) { this.author = author; }
+        public String getSubject() { return subject; }
+        public void setSubject(String subject) { this.subject = subject; }
+        public String getKeywords() { return keywords; }
+        public void setKeywords(String keywords) { this.keywords = keywords; }
+        public String getCreator() { return creator; }
+        public void setCreator(String creator) { this.creator = creator; }
+        public int getPageCount() { return pageCount; }
+        public void setPageCount(int pageCount) { this.pageCount = pageCount; }
+    }
+
+    private static class PDFContent {
+        private String htmlContent;
+        private List<PDFImage> images = new ArrayList<>();
+
+        public String getHtmlContent() { return htmlContent; }
+        public void setHtmlContent(String htmlContent) { this.htmlContent = htmlContent; }
+        public List<PDFImage> getImages() { return images; }
+        public void setImages(List<PDFImage> images) { this.images = images; }
+    }
+
+    private static class PDFImage {
+        private String imageId;
+        private int pageNumber;
+        private byte[] imageData;
+        private int width;
+        private int height;
+
+        public String getImageId() { return imageId; }
+        public void setImageId(String imageId) { this.imageId = imageId; }
+        public int getPageNumber() { return pageNumber; }
+        public void setPageNumber(int pageNumber) { this.pageNumber = pageNumber; }
+        public byte[] getImageData() { return imageData; }
+        public void setImageData(byte[] imageData) { this.imageData = imageData; }
+        public int getWidth() { return width; }
+        public void setWidth(int width) { this.width = width; }
+        public int getHeight() { return height; }
+        public void setHeight(int height) { this.height = height; }
+    }
+
+    /**
+     * Custom PDF text stripper to filter headers/footers
+     */
+    private static class CustomPDFTextStripper extends PDFTextStripper {
+        public CustomPDFTextStripper() throws IOException {
+            super();
+        }
+
+        @Override
+        protected void writeString(String text, List<TextPosition> textPositions) throws IOException {
+            super.writeString(text, textPositions);
+        }
+    }
+
+    /**
+     * Custom MultipartFile implementation for PDF images
+     */
+    private static class PDFImageMultipartFile implements MultipartFile {
+        private final byte[] data;
+        private final String filename;
+        private final String contentType;
+
+        public PDFImageMultipartFile(byte[] data, String filename, String contentType) {
+            this.data = data;
+            this.filename = filename;
+            this.contentType = contentType;
+        }
+
+        @Override
+        public String getName() {
+            return "image";
+        }
+
+        @Override
+        public String getOriginalFilename() {
+            return filename;
+        }
+
+        @Override
+        public String getContentType() {
+            return contentType;
+        }
+
+        @Override
+        public boolean isEmpty() {
+            return data == null || data.length == 0;
+        }
+
+        @Override
+        public long getSize() {
+            return data != null ? data.length : 0;
+        }
+
+        @Override
+        public byte[] getBytes() {
+            return data;
+        }
+
+        @Override
+        public InputStream getInputStream() {
+            return new ByteArrayInputStream(data);
+        }
+
+        @Override
+        public void transferTo(java.io.File dest) throws IOException {
+            try (java.io.FileOutputStream fos = new java.io.FileOutputStream(dest)) {
+                fos.write(data);
+            }
+        }
+
+        @Override
+        public void transferTo(java.nio.file.Path dest) throws IOException {
+            java.nio.file.Files.write(dest, data);
+        }
+    }
+}

backend/src/main/java/com/storycove/service/RefreshTokenService.java

@@ -0,0 +1,91 @@
+package com.storycove.service;
+
+import com.storycove.entity.RefreshToken;
+import com.storycove.repository.RefreshTokenRepository;
+import com.storycove.util.JwtUtil;
+import jakarta.transaction.Transactional;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Service;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+@Service
+public class RefreshTokenService {
+
+    private static final Logger logger = LoggerFactory.getLogger(RefreshTokenService.class);
+
+    private final RefreshTokenRepository refreshTokenRepository;
+    private final JwtUtil jwtUtil;
+
+    public RefreshTokenService(RefreshTokenRepository refreshTokenRepository, JwtUtil jwtUtil) {
+        this.refreshTokenRepository = refreshTokenRepository;
+        this.jwtUtil = jwtUtil;
+    }
+
+    /**
+     * Create a new refresh token
+     */
+    public RefreshToken createRefreshToken(String libraryId, String userAgent, String ipAddress) {
+        String token = jwtUtil.generateRefreshToken();
+        LocalDateTime expiresAt = LocalDateTime.now().plusSeconds(jwtUtil.getRefreshExpirationMs() / 1000);
+
+        RefreshToken refreshToken = new RefreshToken(token, expiresAt, libraryId, userAgent, ipAddress);
+        return refreshTokenRepository.save(refreshToken);
+    }
+
+    /**
+     * Find a refresh token by its token string
+     */
+    public Optional<RefreshToken> findByToken(String token) {
+        return refreshTokenRepository.findByToken(token);
+    }
+
+    /**
+     * Verify and validate a refresh token
+     */
+    public Optional<RefreshToken> verifyRefreshToken(String token) {
+        return refreshTokenRepository.findByToken(token)
+                .filter(RefreshToken::isValid);
+    }
+
+    /**
+     * Revoke a specific refresh token
+     */
+    @Transactional
+    public void revokeToken(RefreshToken token) {
+        token.setRevokedAt(LocalDateTime.now());
+        refreshTokenRepository.save(token);
+    }
+
+    /**
+     * Revoke all refresh tokens for a specific library
+     */
+    @Transactional
+    public void revokeAllByLibraryId(String libraryId) {
+        refreshTokenRepository.revokeAllByLibraryId(libraryId, LocalDateTime.now());
+        logger.info("Revoked all refresh tokens for library: {}", libraryId);
+    }
+
+    /**
+     * Revoke all refresh tokens (e.g., for logout all)
+     */
+    @Transactional
+    public void revokeAll() {
+        refreshTokenRepository.revokeAll(LocalDateTime.now());
+        logger.info("Revoked all refresh tokens");
+    }
+
+    /**
+     * Clean up expired tokens periodically
+     * Runs daily at 3 AM
+     */
+    @Scheduled(cron = "0 0 3 * * ?")
+    @Transactional
+    public void cleanupExpiredTokens() {
+        refreshTokenRepository.deleteExpiredTokens(LocalDateTime.now());
+        logger.info("Cleaned up expired refresh tokens");
+    }
+}

backend/src/main/java/com/storycove/service/SearchServiceAdapter.java

@@ -1,9 +1,11 @@
 package com.storycove.service;
 
 import com.storycove.dto.AuthorSearchDto;
+import com.storycove.dto.CollectionDto;
 import com.storycove.dto.SearchResultDto;
 import com.storycove.dto.StorySearchDto;
 import com.storycove.entity.Author;
+import com.storycove.entity.Collection;
 import com.storycove.entity.Story;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
@@ -16,7 +18,7 @@ import java.util.UUID;
 /**
  * Service adapter that provides a unified interface for search operations.
  *
- * This adapter directly delegates to OpenSearchService.
+ * This adapter directly delegates to SolrService.
  */
 @Service
 public class SearchServiceAdapter {
@@ -24,7 +26,7 @@ public class SearchServiceAdapter {
     private static final Logger logger = LoggerFactory.getLogger(SearchServiceAdapter.class);
 
     @Autowired
-    private OpenSearchService openSearchService;
+    private SolrService solrService;
 
     // ===============================
     // SEARCH OPERATIONS
@@ -46,11 +48,20 @@ public class SearchServiceAdapter {
                                                          String sourceDomain, String seriesFilter,
                                                          Integer minTagCount, Boolean popularOnly,
                                                          Boolean hiddenGemsOnly) {
-        return openSearchService.searchStories(query, tags, author, series, minWordCount, maxWordCount,
+        logger.info("SearchServiceAdapter: delegating search to SolrService");
-            minRating, isRead, isFavorite, sortBy, sortOrder, page, size, facetBy,
+        try {
-            createdAfter, createdBefore, lastReadAfter, lastReadBefore, unratedOnly, readingStatus,
+            SearchResultDto<StorySearchDto> result = solrService.searchStories(query, tags, author, series, minWordCount, maxWordCount,
-            hasReadingProgress, hasCoverImage, sourceDomain, seriesFilter, minTagCount, popularOnly,
+                minRating, isRead, isFavorite, sortBy, sortOrder, page, size, facetBy,
-            hiddenGemsOnly);
+                createdAfter, createdBefore, lastReadAfter, lastReadBefore, unratedOnly, readingStatus,
+                hasReadingProgress, hasCoverImage, sourceDomain, seriesFilter, minTagCount, popularOnly,
+                hiddenGemsOnly);
+            logger.info("SearchServiceAdapter: received result with {} stories and {} facets",
+                result.getResults().size(), result.getFacets().size());
+            return result;
+        } catch (Exception e) {
+            logger.error("SearchServiceAdapter: error during search", e);
+            throw e;
+        }
     }
 
     /**
@@ -60,7 +71,7 @@ public class SearchServiceAdapter {
                                                 String series, Integer minWordCount, Integer maxWordCount,
                                                 Float minRating, Boolean isRead, Boolean isFavorite,
                                                 Long seed) {
-        return openSearchService.getRandomStories(count, tags, author, series, minWordCount, maxWordCount,
+        return solrService.getRandomStories(count, tags, author, series, minWordCount, maxWordCount,
             minRating, isRead, isFavorite, seed);
     }
 
@@ -69,7 +80,7 @@ public class SearchServiceAdapter {
      */
     public void recreateIndices() {
         try {
-            openSearchService.recreateIndices();
+            solrService.recreateIndices();
         } catch (Exception e) {
             logger.error("Failed to recreate search indices", e);
             throw new RuntimeException("Failed to recreate search indices", e);
@@ -93,21 +104,29 @@ public class SearchServiceAdapter {
      * Get random story ID with unified interface
      */
     public String getRandomStoryId(Long seed) {
-        return openSearchService.getRandomStoryId(seed);
+        return solrService.getRandomStoryId(seed);
     }
 
     /**
      * Search authors with unified interface
      */
     public List<AuthorSearchDto> searchAuthors(String query, int limit) {
-        return openSearchService.searchAuthors(query, limit);
+        return solrService.searchAuthors(query, limit);
     }
 
     /**
      * Get tag suggestions with unified interface
      */
     public List<String> getTagSuggestions(String query, int limit) {
-        return openSearchService.getTagSuggestions(query, limit);
+        return solrService.getTagSuggestions(query, limit);
+    }
+
+    /**
+     * Search collections with unified interface
+     */
+    public SearchResultDto<CollectionDto> searchCollections(String query, List<String> tags,
+                                                            boolean includeArchived, int page, int limit) {
+        return solrService.searchCollections(query, tags, includeArchived, page, limit);
     }
 
     // ===============================
@@ -115,93 +134,137 @@ public class SearchServiceAdapter {
     // ===============================
 
     /**
-     * Index a story in OpenSearch
+     * Index a story in Solr
      */
     public void indexStory(Story story) {
         try {
-            openSearchService.indexStory(story);
+            solrService.indexStory(story);
         } catch (Exception e) {
             logger.error("Failed to index story {}", story.getId(), e);
         }
     }
 
     /**
-     * Update a story in OpenSearch
+     * Update a story in Solr
      */
     public void updateStory(Story story) {
         try {
-            openSearchService.updateStory(story);
+            solrService.updateStory(story);
         } catch (Exception e) {
             logger.error("Failed to update story {}", story.getId(), e);
         }
     }
 
     /**
-     * Delete a story from OpenSearch
+     * Delete a story from Solr
      */
     public void deleteStory(UUID storyId) {
         try {
-            openSearchService.deleteStory(storyId);
+            solrService.deleteStory(storyId);
         } catch (Exception e) {
             logger.error("Failed to delete story {}", storyId, e);
         }
     }
 
     /**
-     * Index an author in OpenSearch
+     * Index an author in Solr
      */
     public void indexAuthor(Author author) {
         try {
-            openSearchService.indexAuthor(author);
+            solrService.indexAuthor(author);
         } catch (Exception e) {
             logger.error("Failed to index author {}", author.getId(), e);
         }
     }
 
     /**
-     * Update an author in OpenSearch
+     * Update an author in Solr
      */
     public void updateAuthor(Author author) {
         try {
-            openSearchService.updateAuthor(author);
+            solrService.updateAuthor(author);
         } catch (Exception e) {
             logger.error("Failed to update author {}", author.getId(), e);
         }
     }
 
     /**
-     * Delete an author from OpenSearch
+     * Delete an author from Solr
      */
     public void deleteAuthor(UUID authorId) {
         try {
-            openSearchService.deleteAuthor(authorId);
+            solrService.deleteAuthor(authorId);
         } catch (Exception e) {
             logger.error("Failed to delete author {}", authorId, e);
         }
     }
 
     /**
-     * Bulk index stories in OpenSearch
+     * Bulk index stories in Solr
      */
     public void bulkIndexStories(List<Story> stories) {
         try {
-            openSearchService.bulkIndexStories(stories);
+            solrService.bulkIndexStories(stories);
         } catch (Exception e) {
             logger.error("Failed to bulk index {} stories", stories.size(), e);
         }
     }
 
     /**
-     * Bulk index authors in OpenSearch
+     * Bulk index authors in Solr
      */
     public void bulkIndexAuthors(List<Author> authors) {
         try {
-            openSearchService.bulkIndexAuthors(authors);
+            solrService.bulkIndexAuthors(authors);
         } catch (Exception e) {
             logger.error("Failed to bulk index {} authors", authors.size(), e);
         }
     }
 
+    /**
+     * Index a collection in Solr
+     */
+    public void indexCollection(Collection collection) {
+        try {
+            solrService.indexCollection(collection);
+        } catch (Exception e) {
+            logger.error("Failed to index collection {}", collection.getId(), e);
+        }
+    }
+
+    /**
+     * Update a collection in Solr
+     */
+    public void updateCollection(Collection collection) {
+        try {
+            solrService.updateCollection(collection);
+        } catch (Exception e) {
+            logger.error("Failed to update collection {}", collection.getId(), e);
+        }
+    }
+
+    /**
+     * Delete a collection from Solr
+     */
+    public void deleteCollection(UUID collectionId) {
+        try {
+            solrService.deleteCollection(collectionId);
+        } catch (Exception e) {
+            logger.error("Failed to delete collection {}", collectionId, e);
+        }
+    }
+
+    /**
+     * Bulk index collections in Solr
+     */
+    public void bulkIndexCollections(List<Collection> collections) {
+        try {
+            solrService.bulkIndexCollections(collections);
+        } catch (Exception e) {
+            logger.error("Failed to bulk index {} collections", collections.size(), e);
+        }
+    }
+
     // ===============================
     // UTILITY METHODS
     // ===============================
@@ -210,14 +273,14 @@ public class SearchServiceAdapter {
      * Check if search service is available and healthy
      */
     public boolean isSearchServiceAvailable() {
-        return openSearchService.testConnection();
+        return solrService.testConnection();
     }
 
     /**
      * Get current search engine name
      */
     public String getCurrentSearchEngine() {
-        return "opensearch";
+        return "solr";
     }
 
     /**
@@ -228,10 +291,10 @@ public class SearchServiceAdapter {
     }
 
     /**
-     * Check if we can switch to OpenSearch
+     * Check if we can switch to Solr
      */
-    public boolean canSwitchToOpenSearch() {
+    public boolean canSwitchToSolr() {
-        return true; // Already using OpenSearch
+        return true; // Already using Solr
     }
 
     /**
@@ -246,10 +309,10 @@ public class SearchServiceAdapter {
      */
     public SearchStatus getSearchStatus() {
         return new SearchStatus(
-            "opensearch",
+            "solr",
             false, // no dual-write
             false, // no typesense
-            openSearchService.testConnection()
+            solrService.testConnection()
         );
     }
 
@@ -260,19 +323,19 @@ public class SearchServiceAdapter {
         private final String primaryEngine;
         private final boolean dualWrite;
         private final boolean typesenseAvailable;
-        private final boolean openSearchAvailable;
+        private final boolean solrAvailable;
 
         public SearchStatus(String primaryEngine, boolean dualWrite,
-                          boolean typesenseAvailable, boolean openSearchAvailable) {
+                          boolean typesenseAvailable, boolean solrAvailable) {
             this.primaryEngine = primaryEngine;
             this.dualWrite = dualWrite;
             this.typesenseAvailable = typesenseAvailable;
-            this.openSearchAvailable = openSearchAvailable;
+            this.solrAvailable = solrAvailable;
         }
 
         public String getPrimaryEngine() { return primaryEngine; }
         public boolean isDualWrite() { return dualWrite; }
         public boolean isTypesenseAvailable() { return typesenseAvailable; }
-        public boolean isOpenSearchAvailable() { return openSearchAvailable; }
+        public boolean isSolrAvailable() { return solrAvailable; }
     }
 }

backend/src/main/java/com/storycove/service/StoryService.java

@@ -342,15 +342,15 @@ public class StoryService {
         }
         
         Story savedStory = storyRepository.save(story);
-        
+
         // Handle tags
         if (story.getTags() != null && !story.getTags().isEmpty()) {
             updateStoryTags(savedStory, story.getTags());
         }
-        
+
         // Index in search engine
         searchServiceAdapter.indexStory(savedStory);
-        
+
         return savedStory;
     }
 
@@ -370,15 +370,15 @@ public class StoryService {
         }
         
         Story savedStory = storyRepository.save(story);
-        
+
         // Handle tags by names
         if (tagNames != null && !tagNames.isEmpty()) {
             updateStoryTagsByNames(savedStory, tagNames);
         }
-        
+
         // Index in search engine
         searchServiceAdapter.indexStory(savedStory);
-        
+
         return savedStory;
     }
 
@@ -422,6 +422,18 @@ public class StoryService {
         return updatedStory;
     }
 
+    public Story updateContentOnly(UUID id, String contentHtml) {
+        Story existingStory = findById(id);
+        existingStory.setContentHtml(contentHtml);
+
+        Story updatedStory = storyRepository.save(existingStory);
+
+        // Update in search engine since content changed
+        searchServiceAdapter.updateStory(updatedStory);
+
+        return updatedStory;
+    }
+
     public void delete(UUID id) {
         Story story = findById(id);
         

backend/src/main/java/com/storycove/service/TagService.java

@@ -28,11 +28,12 @@ import java.util.UUID;
 @Validated
 @Transactional
 public class TagService {
-    
+
     private static final Logger logger = LoggerFactory.getLogger(TagService.class);
 
     private final TagRepository tagRepository;
     private final TagAliasRepository tagAliasRepository;
+    private SolrService solrService;
 
     @Autowired
     public TagService(TagRepository tagRepository, TagAliasRepository tagAliasRepository) {
@@ -40,6 +41,11 @@ public class TagService {
         this.tagAliasRepository = tagAliasRepository;
     }
 
+    @Autowired(required = false)
+    public void setSolrService(SolrService solrService) {
+        this.solrService = solrService;
+    }
+
     @Transactional(readOnly = true)
     public List<Tag> findAll() {
         return tagRepository.findAll();
@@ -142,13 +148,39 @@ public class TagService {
 
     public void delete(UUID id) {
         Tag tag = findById(id);
-        
+
-        // Check if tag is used by any stories
+        // Remove tag from all stories before deletion and track for reindexing
+        List<Story> storiesToReindex = new ArrayList<>();
         if (!tag.getStories().isEmpty()) {
-            throw new IllegalStateException("Cannot delete tag that is used by stories. Remove tag from all stories first.");
+            // Create a copy to avoid ConcurrentModificationException
+            List<Story> storiesToUpdate = new ArrayList<>(tag.getStories());
+            storiesToUpdate.forEach(story -> {
+                story.removeTag(tag);
+                storiesToReindex.add(story);
+            });
+            logger.info("Removed tag '{}' from {} stories before deletion", tag.getName(), storiesToUpdate.size());
         }
-        
+
+        // Remove tag from all collections before deletion
+        if (tag.getCollections() != null && !tag.getCollections().isEmpty()) {
+            tag.getCollections().forEach(collection -> collection.getTags().remove(tag));
+            logger.info("Removed tag '{}' from {} collections before deletion", tag.getName(), tag.getCollections().size());
+        }
+
         tagRepository.delete(tag);
+        logger.info("Deleted tag '{}'", tag.getName());
+
+        // Reindex affected stories in Solr
+        if (solrService != null && !storiesToReindex.isEmpty()) {
+            try {
+                for (Story story : storiesToReindex) {
+                    solrService.indexStory(story);
+                }
+                logger.info("Reindexed {} stories after tag deletion", storiesToReindex.size());
+            } catch (Exception e) {
+                logger.error("Failed to reindex stories after tag deletion", e);
+            }
+        }
     }
 
     public List<Tag> deleteUnusedTags() {

backend/src/main/java/com/storycove/service/ZIPImportService.java

@@ -0,0 +1,521 @@
+package com.storycove.service;
+
+import com.storycove.dto.*;
+import com.storycove.service.exception.InvalidFileException;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.stereotype.Service;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.*;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.*;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.zip.ZipEntry;
+import java.util.zip.ZipInputStream;
+
+@Service
+public class ZIPImportService {
+    private static final Logger log = LoggerFactory.getLogger(ZIPImportService.class);
+
+    private static final long MAX_ZIP_SIZE = 1024L * 1024 * 1024; // 1GB
+    private static final int MAX_FILES_IN_ZIP = 30;
+    private static final long ZIP_SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+
+    // Temporary storage for extracted ZIP files (sessionId -> session data)
+    private final Map<String, ZIPSession> activeSessions = new ConcurrentHashMap<>();
+
+    private final EPUBImportService epubImportService;
+    private final PDFImportService pdfImportService;
+
+    @Autowired
+    public ZIPImportService(EPUBImportService epubImportService,
+                           PDFImportService pdfImportService) {
+        this.epubImportService = epubImportService;
+        this.pdfImportService = pdfImportService;
+    }
+
+    /**
+     * Analyze a ZIP file and return information about its contents
+     */
+    public ZIPAnalysisResponse analyzeZIPFile(MultipartFile zipFile) {
+        try {
+            // Validate ZIP file
+            if (zipFile == null || zipFile.isEmpty()) {
+                return ZIPAnalysisResponse.error("ZIP file is required");
+            }
+
+            if (!isValidZIPFile(zipFile)) {
+                return ZIPAnalysisResponse.error("Invalid ZIP file format");
+            }
+
+            if (zipFile.getSize() > MAX_ZIP_SIZE) {
+                return ZIPAnalysisResponse.error("ZIP file size exceeds " + (MAX_ZIP_SIZE / 1024 / 1024) + "MB limit");
+            }
+
+            log.info("Analyzing ZIP file: {} (size: {} bytes)", zipFile.getOriginalFilename(), zipFile.getSize());
+
+            // Create temporary directory for extraction
+            String sessionId = UUID.randomUUID().toString();
+            Path tempDir = Files.createTempDirectory("storycove-zip-" + sessionId);
+
+            // Extract ZIP contents
+            List<FileInfoDto> files = extractAndAnalyzeZIP(zipFile, tempDir, sessionId);
+
+            if (files.isEmpty()) {
+                cleanupSession(sessionId);
+                return ZIPAnalysisResponse.error("No valid EPUB or PDF files found in ZIP");
+            }
+
+            if (files.size() > MAX_FILES_IN_ZIP) {
+                cleanupSession(sessionId);
+                return ZIPAnalysisResponse.error("ZIP contains too many files (max " + MAX_FILES_IN_ZIP + ")");
+            }
+
+            // Store session data
+            ZIPSession session = new ZIPSession(sessionId, tempDir, files);
+            activeSessions.put(sessionId, session);
+
+            // Schedule cleanup
+            scheduleSessionCleanup(sessionId);
+
+            ZIPAnalysisResponse response = ZIPAnalysisResponse.success(zipFile.getOriginalFilename(), files);
+            response.addWarning("Session ID: " + sessionId + " (valid for 30 minutes)");
+
+            log.info("ZIP analysis completed. Session ID: {}, Files found: {}", sessionId, files.size());
+            return response;
+
+        } catch (Exception e) {
+            log.error("Failed to analyze ZIP file: {}", e.getMessage(), e);
+            return ZIPAnalysisResponse.error("Failed to analyze ZIP file: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Import selected files from a previously analyzed ZIP
+     */
+    public ZIPImportResponse importFromZIP(ZIPImportRequest request) {
+        try {
+            // Validate session
+            ZIPSession session = activeSessions.get(request.getZipSessionId());
+            if (session == null) {
+                return createErrorResponse("Invalid or expired session ID");
+            }
+
+            if (session.isExpired()) {
+                cleanupSession(request.getZipSessionId());
+                return createErrorResponse("Session has expired. Please re-upload the ZIP file");
+            }
+
+            List<String> selectedFiles = request.getSelectedFiles();
+            if (selectedFiles == null || selectedFiles.isEmpty()) {
+                return createErrorResponse("No files selected for import");
+            }
+
+            log.info("Importing {} files from ZIP session: {}", selectedFiles.size(), request.getZipSessionId());
+
+            List<FileImportResponse> results = new ArrayList<>();
+
+            // Import each selected file
+            for (String fileName : selectedFiles) {
+                try {
+                    FileInfoDto fileInfo = session.getFileInfo(fileName);
+                    if (fileInfo == null) {
+                        FileImportResponse errorResult = FileImportResponse.error("File not found in session: " + fileName, fileName);
+                        results.add(errorResult);
+                        continue;
+                    }
+
+                    if (fileInfo.getError() != null) {
+                        FileImportResponse errorResult = FileImportResponse.error("File has errors: " + fileInfo.getError(), fileName);
+                        results.add(errorResult);
+                        continue;
+                    }
+
+                    // Get file-specific or default metadata
+                    ZIPImportRequest.FileImportMetadata metadata = getFileMetadata(request, fileName);
+
+                    // Import based on file type
+                    FileImportResponse result;
+                    if ("EPUB".equals(fileInfo.getFileType())) {
+                        result = importEPUBFromSession(session, fileName, metadata, request);
+                    } else if ("PDF".equals(fileInfo.getFileType())) {
+                        result = importPDFFromSession(session, fileName, metadata, request);
+                    } else {
+                        result = FileImportResponse.error("Unsupported file type: " + fileInfo.getFileType(), fileName);
+                    }
+
+                    results.add(result);
+
+                    if (result.isSuccess()) {
+                        log.info("Successfully imported file: {} (Story ID: {})", fileName, result.getStoryId());
+                    } else {
+                        log.warn("Failed to import file: {} - {}", fileName, result.getMessage());
+                    }
+
+                } catch (Exception e) {
+                    log.error("Failed to import file {}: {}", fileName, e.getMessage(), e);
+                    FileImportResponse errorResult = FileImportResponse.error("Import failed: " + e.getMessage(), fileName);
+                    results.add(errorResult);
+                }
+            }
+
+            // Cleanup session after import
+            cleanupSession(request.getZipSessionId());
+
+            log.info("ZIP import completed. Total: {}, Success: {}, Failed: {}",
+                    results.size(),
+                    results.stream().filter(FileImportResponse::isSuccess).count(),
+                    results.stream().filter(r -> !r.isSuccess()).count());
+
+            return ZIPImportResponse.create(results);
+
+        } catch (Exception e) {
+            log.error("ZIP import failed: {}", e.getMessage(), e);
+            return createErrorResponse("Import failed: " + e.getMessage());
+        }
+    }
+
+    private boolean isValidZIPFile(MultipartFile file) {
+        String filename = file.getOriginalFilename();
+        if (filename == null || !filename.toLowerCase().endsWith(".zip")) {
+            return false;
+        }
+
+        String contentType = file.getContentType();
+        return "application/zip".equals(contentType) ||
+               "application/x-zip-compressed".equals(contentType) ||
+               contentType == null;
+    }
+
+    private List<FileInfoDto> extractAndAnalyzeZIP(MultipartFile zipFile, Path tempDir, String sessionId) throws IOException {
+        List<FileInfoDto> files = new ArrayList<>();
+        int fileCount = 0;
+
+        try (ZipInputStream zis = new ZipInputStream(zipFile.getInputStream())) {
+            ZipEntry entry;
+
+            while ((entry = zis.getNextEntry()) != null) {
+                // Skip directories
+                if (entry.isDirectory()) {
+                    continue;
+                }
+
+                // Only process root-level files
+                String entryName = entry.getName();
+                if (entryName.contains("/") || entryName.contains("\\")) {
+                    log.debug("Skipping nested file: {}", entryName);
+                    continue;
+                }
+
+                // Check if it's an EPUB or PDF
+                String lowerName = entryName.toLowerCase();
+                if (!lowerName.endsWith(".epub") && !lowerName.endsWith(".pdf")) {
+                    log.debug("Skipping non-EPUB/PDF file: {}", entryName);
+                    continue;
+                }
+
+                fileCount++;
+                if (fileCount > MAX_FILES_IN_ZIP) {
+                    log.warn("ZIP contains more than {} files, stopping extraction", MAX_FILES_IN_ZIP);
+                    break;
+                }
+
+                // Extract file to temp directory
+                Path extractedFile = tempDir.resolve(entryName);
+                Files.copy(zis, extractedFile);
+
+                // Analyze the extracted file
+                FileInfoDto fileInfo = analyzeExtractedFile(extractedFile, entryName);
+                files.add(fileInfo);
+
+                zis.closeEntry();
+            }
+        }
+
+        return files;
+    }
+
+    private FileInfoDto analyzeExtractedFile(Path filePath, String fileName) {
+        try {
+            long fileSize = Files.size(filePath);
+            String fileType;
+            String extractedTitle = null;
+            String extractedAuthor = null;
+            boolean hasMetadata = false;
+
+            if (fileName.toLowerCase().endsWith(".epub")) {
+                fileType = "EPUB";
+                // Try to extract EPUB metadata
+                try {
+                    // Create a temporary MultipartFile for validation
+                    byte[] fileBytes = Files.readAllBytes(filePath);
+                    MultipartFile tempFile = new TempMultipartFile(fileBytes, fileName, "application/epub+zip");
+
+                    // Use EPUBImportService to extract metadata
+                    // For now, we'll just validate the file
+                    List<String> errors = epubImportService.validateEPUBFile(tempFile);
+                    if (!errors.isEmpty()) {
+                        FileInfoDto errorInfo = new FileInfoDto(fileName, fileType, fileSize);
+                        errorInfo.setError(String.join(", ", errors));
+                        return errorInfo;
+                    }
+
+                    hasMetadata = true;
+                    // We could extract more metadata here if needed
+                } catch (Exception e) {
+                    log.warn("Failed to extract EPUB metadata for {}: {}", fileName, e.getMessage());
+                }
+            } else if (fileName.toLowerCase().endsWith(".pdf")) {
+                fileType = "PDF";
+                // Try to extract PDF metadata
+                try {
+                    byte[] fileBytes = Files.readAllBytes(filePath);
+                    MultipartFile tempFile = new TempMultipartFile(fileBytes, fileName, "application/pdf");
+
+                    // Use PDFImportService to validate
+                    List<String> errors = pdfImportService.validatePDFFile(tempFile);
+                    if (!errors.isEmpty()) {
+                        FileInfoDto errorInfo = new FileInfoDto(fileName, fileType, fileSize);
+                        errorInfo.setError(String.join(", ", errors));
+                        return errorInfo;
+                    }
+
+                    hasMetadata = true;
+                    // We could extract more metadata here if needed
+                } catch (Exception e) {
+                    log.warn("Failed to extract PDF metadata for {}: {}", fileName, e.getMessage());
+                }
+            } else {
+                FileInfoDto errorInfo = new FileInfoDto(fileName, "UNKNOWN", fileSize);
+                errorInfo.setError("Unsupported file type");
+                return errorInfo;
+            }
+
+            FileInfoDto fileInfo = new FileInfoDto(fileName, fileType, fileSize);
+            fileInfo.setExtractedTitle(extractedTitle);
+            fileInfo.setExtractedAuthor(extractedAuthor);
+            fileInfo.setHasMetadata(hasMetadata);
+
+            return fileInfo;
+
+        } catch (Exception e) {
+            log.error("Failed to analyze file {}: {}", fileName, e.getMessage(), e);
+            FileInfoDto errorInfo = new FileInfoDto(fileName, "UNKNOWN", 0L);
+            errorInfo.setError("Failed to analyze file: " + e.getMessage());
+            return errorInfo;
+        }
+    }
+
+    private ZIPImportRequest.FileImportMetadata getFileMetadata(ZIPImportRequest request, String fileName) {
+        // Check for file-specific metadata first
+        if (request.getFileMetadata() != null && request.getFileMetadata().containsKey(fileName)) {
+            return request.getFileMetadata().get(fileName);
+        }
+
+        // Return default metadata
+        ZIPImportRequest.FileImportMetadata metadata = new ZIPImportRequest.FileImportMetadata();
+        metadata.setAuthorId(request.getDefaultAuthorId());
+        metadata.setAuthorName(request.getDefaultAuthorName());
+        metadata.setSeriesId(request.getDefaultSeriesId());
+        metadata.setSeriesName(request.getDefaultSeriesName());
+        metadata.setTags(request.getDefaultTags());
+
+        return metadata;
+    }
+
+    private FileImportResponse importEPUBFromSession(ZIPSession session, String fileName,
+                                                     ZIPImportRequest.FileImportMetadata metadata,
+                                                     ZIPImportRequest request) throws IOException {
+        Path filePath = session.getTempDir().resolve(fileName);
+        byte[] fileBytes = Files.readAllBytes(filePath);
+
+        MultipartFile epubFile = new TempMultipartFile(fileBytes, fileName, "application/epub+zip");
+
+        EPUBImportRequest epubRequest = new EPUBImportRequest();
+        epubRequest.setEpubFile(epubFile);
+        epubRequest.setAuthorId(metadata.getAuthorId());
+        epubRequest.setAuthorName(metadata.getAuthorName());
+        epubRequest.setSeriesId(metadata.getSeriesId());
+        epubRequest.setSeriesName(metadata.getSeriesName());
+        epubRequest.setSeriesVolume(metadata.getSeriesVolume());
+        epubRequest.setTags(metadata.getTags());
+        epubRequest.setCreateMissingAuthor(request.getCreateMissingAuthor());
+        epubRequest.setCreateMissingSeries(request.getCreateMissingSeries());
+        epubRequest.setExtractCover(true);
+
+        EPUBImportResponse epubResponse = epubImportService.importEPUB(epubRequest);
+
+        // Convert EPUBImportResponse to FileImportResponse
+        if (epubResponse.isSuccess()) {
+            FileImportResponse response = FileImportResponse.success(epubResponse.getStoryId(), epubResponse.getStoryTitle(), "EPUB");
+            response.setFileName(fileName);
+            response.setWordCount(epubResponse.getWordCount());
+            return response;
+        } else {
+            return FileImportResponse.error(epubResponse.getMessage(), fileName);
+        }
+    }
+
+    private FileImportResponse importPDFFromSession(ZIPSession session, String fileName,
+                                                    ZIPImportRequest.FileImportMetadata metadata,
+                                                    ZIPImportRequest request) throws IOException {
+        Path filePath = session.getTempDir().resolve(fileName);
+        byte[] fileBytes = Files.readAllBytes(filePath);
+
+        MultipartFile pdfFile = new TempMultipartFile(fileBytes, fileName, "application/pdf");
+
+        PDFImportRequest pdfRequest = new PDFImportRequest();
+        pdfRequest.setPdfFile(pdfFile);
+        pdfRequest.setAuthorId(metadata.getAuthorId());
+        pdfRequest.setAuthorName(metadata.getAuthorName());
+        pdfRequest.setSeriesId(metadata.getSeriesId());
+        pdfRequest.setSeriesName(metadata.getSeriesName());
+        pdfRequest.setSeriesVolume(metadata.getSeriesVolume());
+        pdfRequest.setTags(metadata.getTags());
+        pdfRequest.setCreateMissingAuthor(request.getCreateMissingAuthor());
+        pdfRequest.setCreateMissingSeries(request.getCreateMissingSeries());
+        pdfRequest.setExtractImages(request.getExtractImages());
+
+        return pdfImportService.importPDF(pdfRequest);
+    }
+
+    private void scheduleSessionCleanup(String sessionId) {
+        Timer timer = new Timer(true);
+        timer.schedule(new TimerTask() {
+            @Override
+            public void run() {
+                cleanupSession(sessionId);
+            }
+        }, ZIP_SESSION_TIMEOUT_MS);
+    }
+
+    private void cleanupSession(String sessionId) {
+        ZIPSession session = activeSessions.remove(sessionId);
+        if (session != null) {
+            try {
+                deleteDirectory(session.getTempDir());
+                log.info("Cleaned up ZIP session: {}", sessionId);
+            } catch (Exception e) {
+                log.error("Failed to cleanup ZIP session {}: {}", sessionId, e.getMessage(), e);
+            }
+        }
+    }
+
+    private void deleteDirectory(Path directory) throws IOException {
+        if (Files.exists(directory)) {
+            Files.walk(directory)
+                    .sorted((a, b) -> -a.compareTo(b)) // Delete files before directories
+                    .forEach(path -> {
+                        try {
+                            Files.delete(path);
+                        } catch (IOException e) {
+                            log.warn("Failed to delete file {}: {}", path, e.getMessage());
+                        }
+                    });
+        }
+    }
+
+    private ZIPImportResponse createErrorResponse(String message) {
+        ZIPImportResponse response = new ZIPImportResponse();
+        response.setSuccess(false);
+        response.setMessage(message);
+        return response;
+    }
+
+    // Inner classes
+
+    private static class ZIPSession {
+        private final String sessionId;
+        private final Path tempDir;
+        private final Map<String, FileInfoDto> files;
+        private final long createdAt;
+
+        public ZIPSession(String sessionId, Path tempDir, List<FileInfoDto> fileList) {
+            this.sessionId = sessionId;
+            this.tempDir = tempDir;
+            this.files = new HashMap<>();
+            for (FileInfoDto file : fileList) {
+                this.files.put(file.getFileName(), file);
+            }
+            this.createdAt = System.currentTimeMillis();
+        }
+
+        public Path getTempDir() {
+            return tempDir;
+        }
+
+        public FileInfoDto getFileInfo(String fileName) {
+            return files.get(fileName);
+        }
+
+        public boolean isExpired() {
+            return System.currentTimeMillis() - createdAt > ZIP_SESSION_TIMEOUT_MS;
+        }
+    }
+
+    /**
+     * Temporary MultipartFile implementation for extracted files
+     */
+    private static class TempMultipartFile implements MultipartFile {
+        private final byte[] data;
+        private final String filename;
+        private final String contentType;
+
+        public TempMultipartFile(byte[] data, String filename, String contentType) {
+            this.data = data;
+            this.filename = filename;
+            this.contentType = contentType;
+        }
+
+        @Override
+        public String getName() {
+            return "file";
+        }
+
+        @Override
+        public String getOriginalFilename() {
+            return filename;
+        }
+
+        @Override
+        public String getContentType() {
+            return contentType;
+        }
+
+        @Override
+        public boolean isEmpty() {
+            return data == null || data.length == 0;
+        }
+
+        @Override
+        public long getSize() {
+            return data != null ? data.length : 0;
+        }
+
+        @Override
+        public byte[] getBytes() {
+            return data;
+        }
+
+        @Override
+        public InputStream getInputStream() {
+            return new ByteArrayInputStream(data);
+        }
+
+        @Override
+        public void transferTo(java.io.File dest) throws IOException {
+            try (java.io.FileOutputStream fos = new java.io.FileOutputStream(dest)) {
+                fos.write(data);
+            }
+        }
+
+        @Override
+        public void transferTo(java.nio.file.Path dest) throws IOException {
+            Files.write(dest, data);
+        }
+    }
+}

backend/src/main/java/com/storycove/util/JwtUtil.java

@@ -16,15 +16,18 @@ import java.util.Date;
 
 @Component
 public class JwtUtil {
-    
+
     private static final Logger logger = LoggerFactory.getLogger(JwtUtil.class);
-    
+
     // Security: Generate new secret on each startup to invalidate all existing tokens
     private String secret;
-    
+
-    @Value("${storycove.jwt.expiration:86400000}") // 24 hours default
+    @Value("${storycove.jwt.expiration:86400000}") // 24 hours default (access token)
     private Long expiration;
-    
+
+    @Value("${storycove.jwt.refresh-expiration:1209600000}") // 14 days default (refresh token)
+    private Long refreshExpiration;
+
     @PostConstruct
     public void initialize() {
         // Generate a new random secret on startup to invalidate all existing JWT tokens
@@ -33,10 +36,21 @@ public class JwtUtil {
         byte[] secretBytes = new byte[64]; // 512 bits
         random.nextBytes(secretBytes);
         this.secret = Base64.getEncoder().encodeToString(secretBytes);
-        
+
         logger.info("JWT secret rotated on startup - all existing tokens invalidated");
         logger.info("Users will need to re-authenticate after application restart for security");
     }
+
+    public Long getRefreshExpirationMs() {
+        return refreshExpiration;
+    }
+
+    public String generateRefreshToken() {
+        SecureRandom random = new SecureRandom();
+        byte[] tokenBytes = new byte[32]; // 256 bits
+        random.nextBytes(tokenBytes);
+        return Base64.getUrlEncoder().withoutPadding().encodeToString(tokenBytes);
+    }
     
     private SecretKey getSigningKey() {
         return Keys.hmacShaKeyFor(secret.getBytes());

backend/src/main/resources/application.yml

@@ -4,6 +4,11 @@ spring:
     username: ${SPRING_DATASOURCE_USERNAME:storycove}
     password: ${SPRING_DATASOURCE_PASSWORD:password}
     driver-class-name: org.postgresql.Driver
+    hikari:
+      connection-timeout: 60000  # 60 seconds
+      idle-timeout: 300000       # 5 minutes
+      max-lifetime: 1800000      # 30 minutes
+      maximum-pool-size: 20
   
   jpa:
     hibernate:
@@ -16,8 +21,8 @@ spring:
   
   servlet:
     multipart:
-      max-file-size: 256MB  # Increased for backup restore
+      max-file-size: 4096MB  # 4GB for large backup restore
-      max-request-size: 260MB  # Slightly higher to account for form data
+      max-request-size: 4150MB  # Slightly higher to account for form data
 
   jackson:
     serialization:
@@ -27,6 +32,8 @@ spring:
 
 server:
   port: 8080
+  tomcat:
+    max-http-request-size: 4200MB  # Tomcat HTTP request size limit (4GB + overhead)
 
 storycove:
   app:
@@ -35,60 +42,55 @@ storycove:
     allowed-origins: ${STORYCOVE_CORS_ALLOWED_ORIGINS:http://localhost:3000,http://localhost:6925}
   jwt:
     secret: ${JWT_SECRET}  # REQUIRED: Must be at least 32 characters, no default for security
-    expiration: 86400000  # 24 hours
+    expiration: 86400000  # 24 hours (access token)
+    refresh-expiration: 1209600000  # 14 days (refresh token)
   auth:
     password: ${APP_PASSWORD}  # REQUIRED: No default password for security
   search:
-    engine: opensearch  # OpenSearch is the only search engine
+    engine: solr  # Apache Solr search engine
-  opensearch:
+  solr:
     # Connection settings
-    host: ${OPENSEARCH_HOST:localhost}
+    url: ${SOLR_URL:http://solr:8983/solr}
-    port: ${OPENSEARCH_PORT:9200}
+    username: ${SOLR_USERNAME:}
-    scheme: ${OPENSEARCH_SCHEME:http}
+    password: ${SOLR_PASSWORD:}
-    username: ${OPENSEARCH_USERNAME:}
-    password: ${OPENSEARCH_PASSWORD:}  # Empty when security is disabled
 
-    # Environment-specific configuration
+    # Core configuration
-    profile: ${SPRING_PROFILES_ACTIVE:development}  # development, staging, production
+    cores:
+      stories: ${SOLR_STORIES_CORE:storycove_stories}
+      authors: ${SOLR_AUTHORS_CORE:storycove_authors}
 
-    # Security settings
+    # Connection settings
-    security:
-      ssl-verification: ${OPENSEARCH_SSL_VERIFICATION:false}
-      trust-all-certificates: ${OPENSEARCH_TRUST_ALL_CERTS:true}
-      keystore-path: ${OPENSEARCH_KEYSTORE_PATH:}
-      keystore-password: ${OPENSEARCH_KEYSTORE_PASSWORD:}
-      truststore-path: ${OPENSEARCH_TRUSTSTORE_PATH:}
-      truststore-password: ${OPENSEARCH_TRUSTSTORE_PASSWORD:}
-
-    # Connection pool settings
     connection:
-      timeout: ${OPENSEARCH_CONNECTION_TIMEOUT:30000}  # 30 seconds
+      timeout: ${SOLR_CONNECTION_TIMEOUT:30000}  # 30 seconds
-      socket-timeout: ${OPENSEARCH_SOCKET_TIMEOUT:60000}  # 60 seconds
+      socket-timeout: ${SOLR_SOCKET_TIMEOUT:60000}  # 60 seconds
-      max-connections-per-route: ${OPENSEARCH_MAX_CONN_PER_ROUTE:10}
+      max-connections-per-route: ${SOLR_MAX_CONN_PER_ROUTE:10}
-      max-connections-total: ${OPENSEARCH_MAX_CONN_TOTAL:30}
+      max-connections-total: ${SOLR_MAX_CONN_TOTAL:30}
-      retry-on-failure: ${OPENSEARCH_RETRY_ON_FAILURE:true}
+      retry-on-failure: ${SOLR_RETRY_ON_FAILURE:true}
-      max-retries: ${OPENSEARCH_MAX_RETRIES:3}
+      max-retries: ${SOLR_MAX_RETRIES:3}
 
-    # Index settings
+    # Query settings
-    indices:
+    query:
-      default-shards: ${OPENSEARCH_DEFAULT_SHARDS:1}
+      default-rows: ${SOLR_DEFAULT_ROWS:10}
-      default-replicas: ${OPENSEARCH_DEFAULT_REPLICAS:0}
+      max-rows: ${SOLR_MAX_ROWS:1000}
-      refresh-interval: ${OPENSEARCH_REFRESH_INTERVAL:1s}
+      default-operator: ${SOLR_DEFAULT_OPERATOR:AND}
+      highlight: ${SOLR_ENABLE_HIGHLIGHT:true}
+      facets: ${SOLR_ENABLE_FACETS:true}
 
-    # Bulk operations
+    # Commit settings
-    bulk:
+    commit:
-      actions: ${OPENSEARCH_BULK_ACTIONS:1000}
+      soft-commit: ${SOLR_SOFT_COMMIT:true}
-      size: ${OPENSEARCH_BULK_SIZE:5242880}  # 5MB
+      commit-within: ${SOLR_COMMIT_WITHIN:1000}  # 1 second
-      timeout: ${OPENSEARCH_BULK_TIMEOUT:10000}  # 10 seconds
+      wait-searcher: ${SOLR_WAIT_SEARCHER:false}
-      concurrent-requests: ${OPENSEARCH_BULK_CONCURRENT:1}
 
     # Health and monitoring
     health:
-      check-interval: ${OPENSEARCH_HEALTH_CHECK_INTERVAL:30000}  # 30 seconds
+      check-interval: ${SOLR_HEALTH_CHECK_INTERVAL:30000}  # 30 seconds
-      slow-query-threshold: ${OPENSEARCH_SLOW_QUERY_THRESHOLD:5000}  # 5 seconds
+      slow-query-threshold: ${SOLR_SLOW_QUERY_THRESHOLD:5000}  # 5 seconds
-      enable-metrics: ${OPENSEARCH_ENABLE_METRICS:true}
+      enable-metrics: ${SOLR_ENABLE_METRICS:true}
   images:
     storage-path: ${IMAGE_STORAGE_PATH:/app/images}
+  automatic-backup:
+    dir: ${AUTOMATIC_BACKUP_DIR:/app/automatic-backups}
 
 management:
   endpoints:
@@ -100,8 +102,8 @@ management:
       show-details: when-authorized
       show-components: always
   health:
-    opensearch:
+    solr:
-      enabled: ${OPENSEARCH_HEALTH_ENABLED:true}
+      enabled: ${SOLR_HEALTH_ENABLED:true}
 
 logging:
   level:

backend/src/main/resources/opensearch/README.md

@@ -1,178 +0,0 @@
-# OpenSearch Configuration - Best Practices Implementation
-
-## Overview
-
-This directory contains a production-ready OpenSearch configuration following industry best practices for security, scalability, and maintainability.
-
-## Architecture
-
-### 📁 Directory Structure
-```
-opensearch/
-├── config/
-│   ├── opensearch-development.yml    # Development-specific settings
-│   └── opensearch-production.yml     # Production-specific settings
-├── mappings/
-│   ├── stories-mapping.json          # Story index mapping
-│   ├── authors-mapping.json          # Author index mapping
-│   └── collections-mapping.json      # Collection index mapping
-├── templates/
-│   ├── stories-template.json         # Index template for stories_*
-│   └── index-lifecycle-policy.json   # ILM policy for index management
-└── README.md                         # This file
-```
-
-## ✅ Best Practices Implemented
-
-### 🔒 **Security**
-- **Environment-Aware SSL Configuration**
-  - Production: Full certificate validation with custom truststore support
-  - Development: Optional certificate validation for local development
-- **Proper Authentication**: Basic auth with secure credential management
-- **Connection Security**: TLS 1.3 support with hostname verification
-
-### 🏗️ **Configuration Management**
-- **Externalized Configuration**: JSON/YAML files instead of hardcoded values
-- **Environment-Specific Settings**: Different configs for dev/staging/prod
-- **Type-Safe Properties**: Strongly-typed configuration classes
-- **Validation**: Configuration validation at startup
-
-### 📈 **Scalability & Performance**
-- **Connection Pooling**: Configurable connection pool with timeout management
-- **Environment-Aware Sharding**:
-  - Development: 1 shard, 0 replicas (single node)
-  - Production: 3 shards, 1 replica (high availability)
-- **Bulk Operations**: Optimized bulk indexing with configurable batch sizes
-- **Index Templates**: Automatic application of settings to new indexes
-
-### 🔄 **Index Lifecycle Management**
-- **Automated Index Rollover**: Based on size, document count, and age
-- **Hot-Warm-Cold Architecture**: Optimized storage costs
-- **Retention Policies**: Automatic cleanup of old data
-- **Force Merge**: Optimization in warm phase
-
-### 📊 **Monitoring & Observability**
-- **Health Checks**: Automatic cluster health monitoring
-- **Spring Boot Actuator**: Health endpoints for monitoring systems
-- **Metrics Collection**: Configurable performance metrics
-- **Slow Query Detection**: Configurable thresholds for query performance
-
-### 🛡️ **Error Handling & Resilience**
-- **Connection Retry Logic**: Automatic retry with backoff
-- **Circuit Breaker Pattern**: Fail-fast for unhealthy clusters
-- **Graceful Degradation**: Graceful handling when OpenSearch unavailable
-- **Detailed Error Logging**: Comprehensive error tracking
-
-## 🚀 Usage
-
-### Development Environment
-```yaml
-# application-development.yml
-storycove:
-  opensearch:
-    profile: development
-    security:
-      ssl-verification: false
-      trust-all-certificates: true
-    indices:
-      default-shards: 1
-      default-replicas: 0
-```
-
-### Production Environment
-```yaml
-# application-production.yml
-storycove:
-  opensearch:
-    profile: production
-    security:
-      ssl-verification: true
-      trust-all-certificates: false
-      truststore-path: /etc/ssl/opensearch-truststore.jks
-    indices:
-      default-shards: 3
-      default-replicas: 1
-```
-
-## 📋 Environment Variables
-
-### Required
-- `OPENSEARCH_PASSWORD`: Admin password for OpenSearch cluster
-
-### Optional (with sensible defaults)
-- `OPENSEARCH_HOST`: Cluster hostname (default: localhost)
-- `OPENSEARCH_PORT`: Cluster port (default: 9200)
-- `OPENSEARCH_USERNAME`: Admin username (default: admin)
-- `OPENSEARCH_SSL_VERIFICATION`: Enable SSL verification (default: false for dev)
-- `OPENSEARCH_MAX_CONN_TOTAL`: Max connections (default: 30 for dev, 200 for prod)
-
-## 🎯 Index Templates
-
-Index templates automatically apply configuration to new indexes:
-
-```json
-{
-  "index_patterns": ["stories_*"],
-  "template": {
-    "settings": {
-      "number_of_shards": "#{ENV_SPECIFIC}",
-      "analysis": {
-        "analyzer": {
-          "story_analyzer": {
-            "type": "standard",
-            "stopwords": "_english_"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-## 🔍 Health Monitoring
-
-Access health information:
-- **Application Health**: `/actuator/health`
-- **OpenSearch Specific**: `/actuator/health/opensearch`
-- **Detailed Metrics**: Available when `enable-metrics: true`
-
-## 🔄 Deployment Strategy
-
-Recommended deployment approach:
-
-1. **Development**: Test OpenSearch configuration locally
-2. **Staging**: Validate performance and accuracy in staging environment
-3. **Production**: Deploy with proper monitoring and backup procedures
-
-## 🛠️ Troubleshooting
-
-### Common Issues
-
-1. **SSL Certificate Errors**
-   - Development: Set `trust-all-certificates: true`
-   - Production: Provide valid truststore path
-
-2. **Connection Timeouts**
-   - Increase `connection.timeout` values
-   - Check network connectivity and firewall rules
-
-3. **Index Creation Failures**
-   - Verify cluster health with `/actuator/health/opensearch`
-   - Check OpenSearch logs for detailed error messages
-
-4. **Performance Issues**
-   - Monitor slow queries with configurable thresholds
-   - Adjust bulk operation settings
-   - Review shard allocation and replica settings
-
-## 🔮 Future Enhancements
-
-- **Multi-Cluster Support**: Connect to multiple OpenSearch clusters
-- **Advanced Security**: Integration with OpenSearch Security plugin
-- **Custom Analyzers**: Domain-specific text analysis
-- **Index Aliases**: Zero-downtime index updates
-- **Machine Learning**: Integration with OpenSearch ML features
-
----
-
-This configuration provides a solid foundation that scales from development to enterprise production environments while maintaining security, performance, and operational excellence.

backend/src/main/resources/opensearch/config/opensearch-development.yml

@@ -1,32 +0,0 @@
-# OpenSearch Development Configuration
-opensearch:
-  cluster:
-    name: "storycove-dev"
-    initial_master_nodes: ["opensearch-node"]
-
-  # Development settings - single node, minimal resources
-  indices:
-    default_settings:
-      number_of_shards: 1
-      number_of_replicas: 0
-      refresh_interval: "1s"
-
-  # Security settings for development
-  security:
-    ssl_verification: false
-    trust_all_certificates: true
-
-  # Connection settings
-  connection:
-    timeout: "30s"
-    socket_timeout: "60s"
-    max_connections_per_route: 10
-    max_connections_total: 30
-
-  # Index management
-  index_management:
-    auto_create_templates: true
-    template_patterns:
-      stories: "stories_*"
-      authors: "authors_*"
-      collections: "collections_*"

backend/src/main/resources/opensearch/config/opensearch-production.yml

@@ -1,60 +0,0 @@
-# OpenSearch Production Configuration
-opensearch:
-  cluster:
-    name: "storycove-prod"
-
-  # Production settings - multi-shard, with replicas
-  indices:
-    default_settings:
-      number_of_shards: 3
-      number_of_replicas: 1
-      refresh_interval: "30s"
-      max_result_window: 50000
-
-    # Index lifecycle policies
-    lifecycle:
-      hot_phase_duration: "7d"
-      warm_phase_duration: "30d"
-      cold_phase_duration: "90d"
-      delete_after: "1y"
-
-  # Security settings for production
-  security:
-    ssl_verification: true
-    trust_all_certificates: false
-    certificate_verification: true
-    tls_version: "TLSv1.3"
-
-  # Connection settings
-  connection:
-    timeout: "10s"
-    socket_timeout: "30s"
-    max_connections_per_route: 50
-    max_connections_total: 200
-    retry_on_failure: true
-    max_retries: 3
-    retry_delay: "1s"
-
-  # Performance tuning
-  performance:
-    bulk_actions: 1000
-    bulk_size: "5MB"
-    bulk_timeout: "10s"
-    concurrent_requests: 4
-
-  # Monitoring and observability
-  monitoring:
-    health_check_interval: "30s"
-    slow_query_threshold: "5s"
-    enable_metrics: true
-
-  # Index management
-  index_management:
-    auto_create_templates: true
-    template_patterns:
-      stories: "stories_*"
-      authors: "authors_*"
-      collections: "collections_*"
-    retention_policy:
-      enabled: true
-      default_retention: "1y"

backend/src/main/resources/opensearch/mappings/authors-mapping.json

@@ -1,79 +0,0 @@
-{
-  "settings": {
-    "number_of_shards": 1,
-    "number_of_replicas": 0,
-    "analysis": {
-      "analyzer": {
-        "name_analyzer": {
-          "type": "standard",
-          "stopwords": "_english_"
-        },
-        "autocomplete_analyzer": {
-          "type": "custom",
-          "tokenizer": "standard",
-          "filter": ["lowercase", "edge_ngram"]
-        }
-      },
-      "filter": {
-        "edge_ngram": {
-          "type": "edge_ngram",
-          "min_gram": 2,
-          "max_gram": 20
-        }
-      }
-    }
-  },
-  "mappings": {
-    "properties": {
-      "id": {
-        "type": "keyword"
-      },
-      "name": {
-        "type": "text",
-        "analyzer": "name_analyzer",
-        "fields": {
-          "autocomplete": {
-            "type": "text",
-            "analyzer": "autocomplete_analyzer"
-          },
-          "keyword": {
-            "type": "keyword"
-          }
-        }
-      },
-      "bio": {
-        "type": "text",
-        "analyzer": "name_analyzer"
-      },
-      "urls": {
-        "type": "keyword"
-      },
-      "imageUrl": {
-        "type": "keyword"
-      },
-      "storyCount": {
-        "type": "integer"
-      },
-      "averageRating": {
-        "type": "float"
-      },
-      "totalWordCount": {
-        "type": "long"
-      },
-      "totalReadingTime": {
-        "type": "integer"
-      },
-      "createdAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "updatedAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "libraryId": {
-        "type": "keyword"
-      }
-    }
-  }
-}

backend/src/main/resources/opensearch/mappings/collections-mapping.json

@@ -1,73 +0,0 @@
-{
-  "settings": {
-    "number_of_shards": 1,
-    "number_of_replicas": 0,
-    "analysis": {
-      "analyzer": {
-        "collection_analyzer": {
-          "type": "standard",
-          "stopwords": "_english_"
-        },
-        "autocomplete_analyzer": {
-          "type": "custom",
-          "tokenizer": "standard",
-          "filter": ["lowercase", "edge_ngram"]
-        }
-      },
-      "filter": {
-        "edge_ngram": {
-          "type": "edge_ngram",
-          "min_gram": 2,
-          "max_gram": 20
-        }
-      }
-    }
-  },
-  "mappings": {
-    "properties": {
-      "id": {
-        "type": "keyword"
-      },
-      "name": {
-        "type": "text",
-        "analyzer": "collection_analyzer",
-        "fields": {
-          "autocomplete": {
-            "type": "text",
-            "analyzer": "autocomplete_analyzer"
-          },
-          "keyword": {
-            "type": "keyword"
-          }
-        }
-      },
-      "description": {
-        "type": "text",
-        "analyzer": "collection_analyzer"
-      },
-      "storyCount": {
-        "type": "integer"
-      },
-      "totalWordCount": {
-        "type": "long"
-      },
-      "averageRating": {
-        "type": "float"
-      },
-      "isPublic": {
-        "type": "boolean"
-      },
-      "createdAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "updatedAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "libraryId": {
-        "type": "keyword"
-      }
-    }
-  }
-}

backend/src/main/resources/opensearch/mappings/stories-mapping.json

@@ -1,120 +0,0 @@
-{
-  "settings": {
-    "number_of_shards": 1,
-    "number_of_replicas": 0,
-    "analysis": {
-      "analyzer": {
-        "story_analyzer": {
-          "type": "standard",
-          "stopwords": "_english_"
-        },
-        "autocomplete_analyzer": {
-          "type": "custom",
-          "tokenizer": "standard",
-          "filter": ["lowercase", "edge_ngram"]
-        }
-      },
-      "filter": {
-        "edge_ngram": {
-          "type": "edge_ngram",
-          "min_gram": 2,
-          "max_gram": 20
-        }
-      }
-    }
-  },
-  "mappings": {
-    "properties": {
-      "id": {
-        "type": "keyword"
-      },
-      "title": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {
-          "autocomplete": {
-            "type": "text",
-            "analyzer": "autocomplete_analyzer"
-          },
-          "keyword": {
-            "type": "keyword"
-          }
-        }
-      },
-      "content": {
-        "type": "text",
-        "analyzer": "story_analyzer"
-      },
-      "summary": {
-        "type": "text",
-        "analyzer": "story_analyzer"
-      },
-      "authorNames": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {
-          "keyword": {
-            "type": "keyword"
-          }
-        }
-      },
-      "authorIds": {
-        "type": "keyword"
-      },
-      "tagNames": {
-        "type": "keyword"
-      },
-      "seriesTitle": {
-        "type": "text",
-        "analyzer": "story_analyzer",
-        "fields": {
-          "keyword": {
-            "type": "keyword"
-          }
-        }
-      },
-      "seriesId": {
-        "type": "keyword"
-      },
-      "wordCount": {
-        "type": "integer"
-      },
-      "rating": {
-        "type": "float"
-      },
-      "readingTime": {
-        "type": "integer"
-      },
-      "language": {
-        "type": "keyword"
-      },
-      "status": {
-        "type": "keyword"
-      },
-      "createdAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "updatedAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "publishedAt": {
-        "type": "date",
-        "format": "strict_date_optional_time||epoch_millis"
-      },
-      "isRead": {
-        "type": "boolean"
-      },
-      "isFavorite": {
-        "type": "boolean"
-      },
-      "readingProgress": {
-        "type": "float"
-      },
-      "libraryId": {
-        "type": "keyword"
-      }
-    }
-  }
-}

backend/src/main/resources/opensearch/templates/index-lifecycle-policy.json

@@ -1,77 +0,0 @@
-{
-  "policy": {
-    "description": "StoryCove index lifecycle policy",
-    "default_state": "hot",
-    "states": [
-      {
-        "name": "hot",
-        "actions": [
-          {
-            "rollover": {
-              "min_size": "50gb",
-              "min_doc_count": 1000000,
-              "min_age": "7d"
-            }
-          }
-        ],
-        "transitions": [
-          {
-            "state_name": "warm",
-            "conditions": {
-              "min_age": "7d"
-            }
-          }
-        ]
-      },
-      {
-        "name": "warm",
-        "actions": [
-          {
-            "replica_count": {
-              "number_of_replicas": 0
-            }
-          },
-          {
-            "force_merge": {
-              "max_num_segments": 1
-            }
-          }
-        ],
-        "transitions": [
-          {
-            "state_name": "cold",
-            "conditions": {
-              "min_age": "30d"
-            }
-          }
-        ]
-      },
-      {
-        "name": "cold",
-        "actions": [],
-        "transitions": [
-          {
-            "state_name": "delete",
-            "conditions": {
-              "min_age": "365d"
-            }
-          }
-        ]
-      },
-      {
-        "name": "delete",
-        "actions": [
-          {
-            "delete": {}
-          }
-        ]
-      }
-    ],
-    "ism_template": [
-      {
-        "index_patterns": ["stories_*", "authors_*", "collections_*"],
-        "priority": 100
-      }
-    ]
-  }
-}

backend/src/main/resources/opensearch/templates/stories-template.json

@@ -1,124 +0,0 @@
-{
-  "index_patterns": ["stories_*"],
-  "priority": 1,
-  "template": {
-    "settings": {
-      "number_of_shards": 1,
-      "number_of_replicas": 0,
-      "analysis": {
-        "analyzer": {
-          "story_analyzer": {
-            "type": "standard",
-            "stopwords": "_english_"
-          },
-          "autocomplete_analyzer": {
-            "type": "custom",
-            "tokenizer": "standard",
-            "filter": ["lowercase", "edge_ngram"]
-          }
-        },
-        "filter": {
-          "edge_ngram": {
-            "type": "edge_ngram",
-            "min_gram": 2,
-            "max_gram": 20
-          }
-        }
-      }
-    },
-    "mappings": {
-      "properties": {
-        "id": {
-          "type": "keyword"
-        },
-        "title": {
-          "type": "text",
-          "analyzer": "story_analyzer",
-          "fields": {
-            "autocomplete": {
-              "type": "text",
-              "analyzer": "autocomplete_analyzer"
-            },
-            "keyword": {
-              "type": "keyword"
-            }
-          }
-        },
-        "content": {
-          "type": "text",
-          "analyzer": "story_analyzer"
-        },
-        "summary": {
-          "type": "text",
-          "analyzer": "story_analyzer"
-        },
-        "authorNames": {
-          "type": "text",
-          "analyzer": "story_analyzer",
-          "fields": {
-            "keyword": {
-              "type": "keyword"
-            }
-          }
-        },
-        "authorIds": {
-          "type": "keyword"
-        },
-        "tagNames": {
-          "type": "keyword"
-        },
-        "seriesTitle": {
-          "type": "text",
-          "analyzer": "story_analyzer",
-          "fields": {
-            "keyword": {
-              "type": "keyword"
-            }
-          }
-        },
-        "seriesId": {
-          "type": "keyword"
-        },
-        "wordCount": {
-          "type": "integer"
-        },
-        "rating": {
-          "type": "float"
-        },
-        "readingTime": {
-          "type": "integer"
-        },
-        "language": {
-          "type": "keyword"
-        },
-        "status": {
-          "type": "keyword"
-        },
-        "createdAt": {
-          "type": "date",
-          "format": "strict_date_optional_time||epoch_millis"
-        },
-        "updatedAt": {
-          "type": "date",
-          "format": "strict_date_optional_time||epoch_millis"
-        },
-        "publishedAt": {
-          "type": "date",
-          "format": "strict_date_optional_time||epoch_millis"
-        },
-        "isRead": {
-          "type": "boolean"
-        },
-        "isFavorite": {
-          "type": "boolean"
-        },
-        "readingProgress": {
-          "type": "float"
-        },
-        "libraryId": {
-          "type": "keyword"
-        }
-      }
-    }
-  }
-}

backend/src/test/java/com/storycove/service/CollectionServiceTest.java

@@ -0,0 +1,465 @@
+package com.storycove.service;
+
+import com.storycove.dto.CollectionDto;
+import com.storycove.dto.SearchResultDto;
+import com.storycove.entity.Collection;
+import com.storycove.entity.CollectionStory;
+import com.storycove.entity.Story;
+import com.storycove.entity.Tag;
+import com.storycove.repository.CollectionRepository;
+import com.storycove.repository.CollectionStoryRepository;
+import com.storycove.repository.StoryRepository;
+import com.storycove.repository.TagRepository;
+import com.storycove.service.exception.ResourceNotFoundException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class CollectionServiceTest {
+
+    @Mock
+    private CollectionRepository collectionRepository;
+
+    @Mock
+    private CollectionStoryRepository collectionStoryRepository;
+
+    @Mock
+    private StoryRepository storyRepository;
+
+    @Mock
+    private TagRepository tagRepository;
+
+    @Mock
+    private SearchServiceAdapter searchServiceAdapter;
+
+    @Mock
+    private ReadingTimeService readingTimeService;
+
+    @InjectMocks
+    private CollectionService collectionService;
+
+    private Collection testCollection;
+    private Story testStory;
+    private Tag testTag;
+    private UUID collectionId;
+    private UUID storyId;
+
+    @BeforeEach
+    void setUp() {
+        collectionId = UUID.randomUUID();
+        storyId = UUID.randomUUID();
+
+        testCollection = new Collection();
+        testCollection.setId(collectionId);
+        testCollection.setName("Test Collection");
+        testCollection.setDescription("Test Description");
+        testCollection.setIsArchived(false);
+
+        testStory = new Story();
+        testStory.setId(storyId);
+        testStory.setTitle("Test Story");
+        testStory.setWordCount(1000);
+
+        testTag = new Tag();
+        testTag.setId(UUID.randomUUID());
+        testTag.setName("test-tag");
+    }
+
+    // ========================================
+    // Search Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should search collections using SearchServiceAdapter")
+    void testSearchCollections() {
+        // Arrange
+        CollectionDto dto = new CollectionDto();
+        dto.setId(collectionId);
+        dto.setName("Test Collection");
+
+        SearchResultDto<CollectionDto> searchResult = new SearchResultDto<>(
+            List.of(dto), 1, 0, 10, "test", 100L
+        );
+
+        when(searchServiceAdapter.searchCollections(anyString(), anyList(), anyBoolean(), anyInt(), anyInt()))
+            .thenReturn(searchResult);
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+
+        // Act
+        SearchResultDto<Collection> result = collectionService.searchCollections("test", null, false, 0, 10);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(1, result.getTotalHits());
+        assertEquals(1, result.getResults().size());
+        assertEquals(collectionId, result.getResults().get(0).getId());
+        verify(searchServiceAdapter).searchCollections("test", null, false, 0, 10);
+    }
+
+    @Test
+    @DisplayName("Should handle search with tag filters")
+    void testSearchCollectionsWithTags() {
+        // Arrange
+        List<String> tags = List.of("fantasy", "adventure");
+        CollectionDto dto = new CollectionDto();
+        dto.setId(collectionId);
+
+        SearchResultDto<CollectionDto> searchResult = new SearchResultDto<>(
+            List.of(dto), 1, 0, 10, "test", 50L
+        );
+
+        when(searchServiceAdapter.searchCollections(anyString(), eq(tags), anyBoolean(), anyInt(), anyInt()))
+            .thenReturn(searchResult);
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+
+        // Act
+        SearchResultDto<Collection> result = collectionService.searchCollections("test", tags, false, 0, 10);
+
+        // Assert
+        assertEquals(1, result.getResults().size());
+        verify(searchServiceAdapter).searchCollections("test", tags, false, 0, 10);
+    }
+
+    @Test
+    @DisplayName("Should return empty results when search fails")
+    void testSearchCollectionsFailure() {
+        // Arrange
+        when(searchServiceAdapter.searchCollections(anyString(), anyList(), anyBoolean(), anyInt(), anyInt()))
+            .thenThrow(new RuntimeException("Search failed"));
+
+        // Act
+        SearchResultDto<Collection> result = collectionService.searchCollections("test", null, false, 0, 10);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(0, result.getTotalHits());
+        assertTrue(result.getResults().isEmpty());
+    }
+
+    // ========================================
+    // CRUD Operations Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should find collection by ID")
+    void testFindById() {
+        // Arrange
+        when(collectionRepository.findByIdWithStoriesAndTags(collectionId))
+            .thenReturn(Optional.of(testCollection));
+
+        // Act
+        Collection result = collectionService.findById(collectionId);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(collectionId, result.getId());
+        assertEquals("Test Collection", result.getName());
+    }
+
+    @Test
+    @DisplayName("Should throw exception when collection not found")
+    void testFindByIdNotFound() {
+        // Arrange
+        when(collectionRepository.findByIdWithStoriesAndTags(any()))
+            .thenReturn(Optional.empty());
+
+        // Act & Assert
+        assertThrows(ResourceNotFoundException.class, () -> {
+            collectionService.findById(UUID.randomUUID());
+        });
+    }
+
+    @Test
+    @DisplayName("Should create collection with tags")
+    void testCreateCollection() {
+        // Arrange
+        List<String> tagNames = List.of("fantasy", "adventure");
+        when(tagRepository.findByName("fantasy")).thenReturn(Optional.of(testTag));
+        when(tagRepository.findByName("adventure")).thenReturn(Optional.empty());
+        when(tagRepository.save(any(Tag.class))).thenReturn(testTag);
+        when(collectionRepository.save(any(Collection.class))).thenReturn(testCollection);
+
+        // Act
+        Collection result = collectionService.createCollection("New Collection", "Description", tagNames, null);
+
+        // Assert
+        assertNotNull(result);
+        verify(collectionRepository).save(any(Collection.class));
+        verify(tagRepository, times(2)).findByName(anyString());
+    }
+
+    @Test
+    @DisplayName("Should create collection with initial stories")
+    void testCreateCollectionWithStories() {
+        // Arrange
+        List<UUID> storyIds = List.of(storyId);
+        when(collectionRepository.save(any(Collection.class))).thenReturn(testCollection);
+        when(storyRepository.findAllById(storyIds)).thenReturn(List.of(testStory));
+        when(collectionStoryRepository.existsByCollectionIdAndStoryId(any(), any())).thenReturn(false);
+        when(collectionStoryRepository.getNextPosition(any())).thenReturn(1000);
+        when(collectionStoryRepository.save(any())).thenReturn(new CollectionStory());
+        when(collectionRepository.findByIdWithStoriesAndTags(any()))
+            .thenReturn(Optional.of(testCollection));
+
+        // Act
+        Collection result = collectionService.createCollection("New Collection", "Description", null, storyIds);
+
+        // Assert
+        assertNotNull(result);
+        verify(storyRepository).findAllById(storyIds);
+        verify(collectionStoryRepository).save(any(CollectionStory.class));
+    }
+
+    @Test
+    @DisplayName("Should update collection metadata")
+    void testUpdateCollection() {
+        // Arrange
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(collectionRepository.save(any(Collection.class)))
+            .thenReturn(testCollection);
+
+        // Act
+        Collection result = collectionService.updateCollection(
+            collectionId, "Updated Name", "Updated Description", null, 5
+        );
+
+        // Assert
+        assertNotNull(result);
+        verify(collectionRepository).save(any(Collection.class));
+    }
+
+    @Test
+    @DisplayName("Should delete collection")
+    void testDeleteCollection() {
+        // Arrange
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        doNothing().when(collectionRepository).delete(any(Collection.class));
+
+        // Act
+        collectionService.deleteCollection(collectionId);
+
+        // Assert
+        verify(collectionRepository).delete(testCollection);
+    }
+
+    @Test
+    @DisplayName("Should archive collection")
+    void testArchiveCollection() {
+        // Arrange
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(collectionRepository.save(any(Collection.class)))
+            .thenReturn(testCollection);
+
+        // Act
+        Collection result = collectionService.archiveCollection(collectionId, true);
+
+        // Assert
+        assertNotNull(result);
+        verify(collectionRepository).save(any(Collection.class));
+    }
+
+    // ========================================
+    // Story Management Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should add stories to collection")
+    void testAddStoriesToCollection() {
+        // Arrange
+        List<UUID> storyIds = List.of(storyId);
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(storyRepository.findAllById(storyIds))
+            .thenReturn(List.of(testStory));
+        when(collectionStoryRepository.existsByCollectionIdAndStoryId(collectionId, storyId))
+            .thenReturn(false);
+        when(collectionStoryRepository.getNextPosition(collectionId))
+            .thenReturn(1000);
+        when(collectionStoryRepository.save(any()))
+            .thenReturn(new CollectionStory());
+        when(collectionStoryRepository.countByCollectionId(collectionId))
+            .thenReturn(1L);
+
+        // Act
+        Map<String, Object> result = collectionService.addStoriesToCollection(collectionId, storyIds, null);
+
+        // Assert
+        assertEquals(1, result.get("added"));
+        assertEquals(0, result.get("skipped"));
+        assertEquals(1L, result.get("totalStories"));
+        verify(collectionStoryRepository).save(any(CollectionStory.class));
+    }
+
+    @Test
+    @DisplayName("Should skip duplicate stories when adding")
+    void testAddDuplicateStories() {
+        // Arrange
+        List<UUID> storyIds = List.of(storyId);
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(storyRepository.findAllById(storyIds))
+            .thenReturn(List.of(testStory));
+        when(collectionStoryRepository.existsByCollectionIdAndStoryId(collectionId, storyId))
+            .thenReturn(true);
+        when(collectionStoryRepository.countByCollectionId(collectionId))
+            .thenReturn(1L);
+
+        // Act
+        Map<String, Object> result = collectionService.addStoriesToCollection(collectionId, storyIds, null);
+
+        // Assert
+        assertEquals(0, result.get("added"));
+        assertEquals(1, result.get("skipped"));
+        verify(collectionStoryRepository, never()).save(any());
+    }
+
+    @Test
+    @DisplayName("Should throw exception when adding non-existent stories")
+    void testAddNonExistentStories() {
+        // Arrange
+        List<UUID> storyIds = List.of(storyId, UUID.randomUUID());
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(storyRepository.findAllById(storyIds))
+            .thenReturn(List.of(testStory)); // Only one story found
+
+        // Act & Assert
+        assertThrows(ResourceNotFoundException.class, () -> {
+            collectionService.addStoriesToCollection(collectionId, storyIds, null);
+        });
+    }
+
+    @Test
+    @DisplayName("Should remove story from collection")
+    void testRemoveStoryFromCollection() {
+        // Arrange
+        CollectionStory collectionStory = new CollectionStory();
+        when(collectionStoryRepository.existsByCollectionIdAndStoryId(collectionId, storyId))
+            .thenReturn(true);
+        when(collectionStoryRepository.findByCollectionIdAndStoryId(collectionId, storyId))
+            .thenReturn(collectionStory);
+        doNothing().when(collectionStoryRepository).delete(any());
+
+        // Act
+        collectionService.removeStoryFromCollection(collectionId, storyId);
+
+        // Assert
+        verify(collectionStoryRepository).delete(collectionStory);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when removing non-existent story")
+    void testRemoveNonExistentStory() {
+        // Arrange
+        when(collectionStoryRepository.existsByCollectionIdAndStoryId(any(), any()))
+            .thenReturn(false);
+
+        // Act & Assert
+        assertThrows(ResourceNotFoundException.class, () -> {
+            collectionService.removeStoryFromCollection(collectionId, storyId);
+        });
+    }
+
+    @Test
+    @DisplayName("Should reorder stories in collection")
+    void testReorderStories() {
+        // Arrange
+        List<Map<String, Object>> storyOrders = List.of(
+            Map.of("storyId", storyId.toString(), "position", 1)
+        );
+        when(collectionRepository.findById(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        doNothing().when(collectionStoryRepository).updatePosition(any(), any(), anyInt());
+
+        // Act
+        collectionService.reorderStories(collectionId, storyOrders);
+
+        // Assert
+        verify(collectionStoryRepository, times(2)).updatePosition(any(), any(), anyInt());
+    }
+
+    // ========================================
+    // Statistics Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should get collection statistics")
+    void testGetCollectionStatistics() {
+        // Arrange
+        testStory.setWordCount(1000);
+        testStory.setRating(5);
+
+        CollectionStory cs = new CollectionStory();
+        cs.setStory(testStory);
+        testCollection.setCollectionStories(List.of(cs));
+
+        when(collectionRepository.findByIdWithStoriesAndTags(collectionId))
+            .thenReturn(Optional.of(testCollection));
+        when(readingTimeService.calculateReadingTime(1000))
+            .thenReturn(5);
+
+        // Act
+        Map<String, Object> stats = collectionService.getCollectionStatistics(collectionId);
+
+        // Assert
+        assertNotNull(stats);
+        assertEquals(1, stats.get("totalStories"));
+        assertEquals(1000, stats.get("totalWordCount"));
+        assertEquals(5, stats.get("estimatedReadingTime"));
+        assertTrue(stats.containsKey("averageStoryRating"));
+    }
+
+    // ========================================
+    // Helper Method Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should find all collections with tags for indexing")
+    void testFindAllWithTags() {
+        // Arrange
+        when(collectionRepository.findAllWithTags())
+            .thenReturn(List.of(testCollection));
+
+        // Act
+        List<Collection> result = collectionService.findAllWithTags();
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(1, result.size());
+        verify(collectionRepository).findAllWithTags();
+    }
+
+    @Test
+    @DisplayName("Should get collections for a specific story")
+    void testGetCollectionsForStory() {
+        // Arrange
+        CollectionStory cs = new CollectionStory();
+        cs.setCollection(testCollection);
+        when(collectionStoryRepository.findByStoryId(storyId))
+            .thenReturn(List.of(cs));
+
+        // Act
+        List<Collection> result = collectionService.getCollectionsForStory(storyId);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(1, result.size());
+        assertEquals(collectionId, result.get(0).getId());
+    }
+}

backend/src/test/java/com/storycove/service/EPUBExportServiceTest.java

@@ -0,0 +1,721 @@
+package com.storycove.service;
+
+import com.storycove.dto.EPUBExportRequest;
+import com.storycove.entity.Author;
+import com.storycove.entity.Collection;
+import com.storycove.entity.CollectionStory;
+import com.storycove.entity.ReadingPosition;
+import com.storycove.entity.Series;
+import com.storycove.entity.Story;
+import com.storycove.entity.Tag;
+import com.storycove.repository.ReadingPositionRepository;
+import com.storycove.service.exception.ResourceNotFoundException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.core.io.Resource;
+
+import java.io.IOException;
+import java.time.LocalDateTime;
+import java.util.ArrayList;
+import java.util.Arrays;
+import java.util.Collections;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Tests for EPUBExportService.
+ * Note: These tests focus on service logic. Full EPUB validation would be done in integration tests.
+ */
+@ExtendWith(MockitoExtension.class)
+class EPUBExportServiceTest {
+
+    @Mock
+    private StoryService storyService;
+
+    @Mock
+    private ReadingPositionRepository readingPositionRepository;
+
+    @Mock
+    private CollectionService collectionService;
+
+    @InjectMocks
+    private EPUBExportService epubExportService;
+
+    private Story testStory;
+    private Author testAuthor;
+    private Series testSeries;
+    private Collection testCollection;
+    private EPUBExportRequest testRequest;
+    private UUID storyId;
+    private UUID collectionId;
+
+    @BeforeEach
+    void setUp() {
+        storyId = UUID.randomUUID();
+        collectionId = UUID.randomUUID();
+
+        testAuthor = new Author();
+        testAuthor.setId(UUID.randomUUID());
+        testAuthor.setName("Test Author");
+
+        testSeries = new Series();
+        testSeries.setId(UUID.randomUUID());
+        testSeries.setName("Test Series");
+
+        testStory = new Story();
+        testStory.setId(storyId);
+        testStory.setTitle("Test Story");
+        testStory.setDescription("Test Description");
+        testStory.setContentHtml("<p>Test content here</p>");
+        testStory.setWordCount(1000);
+        testStory.setRating(5);
+        testStory.setAuthor(testAuthor);
+        testStory.setCreatedAt(LocalDateTime.now());
+        testStory.setTags(new HashSet<>());
+
+        testCollection = new Collection();
+        testCollection.setId(collectionId);
+        testCollection.setName("Test Collection");
+        testCollection.setDescription("Test Collection Description");
+        testCollection.setCreatedAt(LocalDateTime.now());
+        testCollection.setCollectionStories(new ArrayList<>());
+
+        testRequest = new EPUBExportRequest();
+        testRequest.setStoryId(storyId);
+        testRequest.setIncludeCoverImage(false);
+        testRequest.setIncludeMetadata(false);
+        testRequest.setIncludeReadingPosition(false);
+        testRequest.setSplitByChapters(false);
+    }
+
+    // ========================================
+    // Basic Export Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should export story as EPUB successfully")
+    void testExportStoryAsEPUB() throws IOException {
+        // Arrange
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+        verify(storyService).findById(storyId);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when story not found")
+    void testExportNonExistentStory() {
+        // Arrange
+        when(storyService.findById(any())).thenThrow(new ResourceNotFoundException("Story not found"));
+
+        // Act & Assert
+        assertThrows(ResourceNotFoundException.class, () -> {
+            epubExportService.exportStoryAsEPUB(testRequest);
+        });
+    }
+
+    @Test
+    @DisplayName("Should export story with HTML content")
+    void testExportStoryWithHtmlContent() throws IOException {
+        // Arrange
+        testStory.setContentHtml("<p>HTML content</p>");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should export story with plain text content when HTML is null")
+    void testExportStoryWithPlainContent() throws IOException {
+        // Arrange
+        // Note: contentPlain is set automatically when contentHtml is set
+        // We test with HTML then clear it to simulate plain text content
+        testStory.setContentHtml("<p>Plain text content here</p>");
+        // contentPlain will be auto-populated, then we clear HTML
+        testStory.setContentHtml(null);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should handle story with no content")
+    void testExportStoryWithNoContent() throws IOException {
+        // Arrange
+        // Create a fresh story with no content (don't set contentHtml at all)
+        Story emptyContentStory = new Story();
+        emptyContentStory.setId(storyId);
+        emptyContentStory.setTitle("Story With No Content");
+        emptyContentStory.setAuthor(testAuthor);
+        emptyContentStory.setCreatedAt(LocalDateTime.now());
+        emptyContentStory.setTags(new HashSet<>());
+        // Don't set contentHtml - it will be null by default
+
+        when(storyService.findById(storyId)).thenReturn(emptyContentStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    // ========================================
+    // Metadata Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should use custom title when provided")
+    void testCustomTitle() throws IOException {
+        // Arrange
+        testRequest.setCustomTitle("Custom Title");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("Custom Title", testRequest.getCustomTitle());
+    }
+
+    @Test
+    @DisplayName("Should use custom author when provided")
+    void testCustomAuthor() throws IOException {
+        // Arrange
+        testRequest.setCustomAuthor("Custom Author");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("Custom Author", testRequest.getCustomAuthor());
+    }
+
+    @Test
+    @DisplayName("Should use story author when custom author not provided")
+    void testDefaultAuthor() throws IOException {
+        // Arrange
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("Test Author", testStory.getAuthor().getName());
+    }
+
+    @Test
+    @DisplayName("Should handle story with no author")
+    void testStoryWithNoAuthor() throws IOException {
+        // Arrange
+        testStory.setAuthor(null);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertNull(testStory.getAuthor());
+    }
+
+    @Test
+    @DisplayName("Should include metadata when requested")
+    void testIncludeMetadata() throws IOException {
+        // Arrange
+        testRequest.setIncludeMetadata(true);
+        testStory.setSeries(testSeries);
+        testStory.setVolume(1);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(testRequest.getIncludeMetadata());
+    }
+
+    @Test
+    @DisplayName("Should set custom language")
+    void testCustomLanguage() throws IOException {
+        // Arrange
+        testRequest.setLanguage("de");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("de", testRequest.getLanguage());
+    }
+
+    @Test
+    @DisplayName("Should use default language when not specified")
+    void testDefaultLanguage() throws IOException {
+        // Arrange
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertNull(testRequest.getLanguage());
+    }
+
+    @Test
+    @DisplayName("Should handle custom metadata")
+    void testCustomMetadata() throws IOException {
+        // Arrange
+        List<String> customMetadata = Arrays.asList(
+            "publisher: Test Publisher",
+            "isbn: 123-456-789"
+        );
+        testRequest.setCustomMetadata(customMetadata);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(2, testRequest.getCustomMetadata().size());
+    }
+
+    // ========================================
+    // Chapter Splitting Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should export as single chapter when splitByChapters is false")
+    void testSingleChapter() throws IOException {
+        // Arrange
+        testRequest.setSplitByChapters(false);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertFalse(testRequest.getSplitByChapters());
+    }
+
+    @Test
+    @DisplayName("Should split into chapters when requested")
+    void testSplitByChapters() throws IOException {
+        // Arrange
+        testRequest.setSplitByChapters(true);
+        testStory.setContentHtml("<h1>Chapter 1</h1><p>Content 1</p><h1>Chapter 2</h1><p>Content 2</p>");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(testRequest.getSplitByChapters());
+    }
+
+    @Test
+    @DisplayName("Should respect max words per chapter setting")
+    void testMaxWordsPerChapter() throws IOException {
+        // Arrange
+        testRequest.setSplitByChapters(true);
+        testRequest.setMaxWordsPerChapter(500);
+        String longContent = String.join(" ", Collections.nCopies(1000, "word"));
+        testStory.setContentHtml("<p>" + longContent + "</p>");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(500, testRequest.getMaxWordsPerChapter());
+    }
+
+    // ========================================
+    // Reading Position Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should include reading position when requested")
+    void testIncludeReadingPosition() throws IOException {
+        // Arrange
+        testRequest.setIncludeReadingPosition(true);
+
+        ReadingPosition position = new ReadingPosition(testStory);
+        position.setChapterIndex(5);
+        position.setWordPosition(100);
+        position.setPercentageComplete(50.0);
+        position.setEpubCfi("epubcfi(/6/4[chap01ref]!/4/2/2[page005])");
+        position.setUpdatedAt(LocalDateTime.now());
+
+        when(storyService.findById(storyId)).thenReturn(testStory);
+        when(readingPositionRepository.findByStoryId(storyId)).thenReturn(Optional.of(position));
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(testRequest.getIncludeReadingPosition());
+        verify(readingPositionRepository).findByStoryId(storyId);
+    }
+
+    @Test
+    @DisplayName("Should handle missing reading position gracefully")
+    void testMissingReadingPosition() throws IOException {
+        // Arrange
+        testRequest.setIncludeReadingPosition(true);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+        when(readingPositionRepository.findByStoryId(storyId)).thenReturn(Optional.empty());
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        verify(readingPositionRepository).findByStoryId(storyId);
+    }
+
+    // ========================================
+    // Filename Generation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should generate filename with author and title")
+    void testGenerateFilenameWithAuthor() {
+        // Act
+        String filename = epubExportService.getEPUBFilename(testStory);
+
+        // Assert
+        assertNotNull(filename);
+        assertTrue(filename.contains("Test_Author"));
+        assertTrue(filename.contains("Test_Story"));
+        assertTrue(filename.endsWith(".epub"));
+    }
+
+    @Test
+    @DisplayName("Should generate filename without author")
+    void testGenerateFilenameWithoutAuthor() {
+        // Arrange
+        testStory.setAuthor(null);
+
+        // Act
+        String filename = epubExportService.getEPUBFilename(testStory);
+
+        // Assert
+        assertNotNull(filename);
+        assertTrue(filename.contains("Test_Story"));
+        assertTrue(filename.endsWith(".epub"));
+    }
+
+    @Test
+    @DisplayName("Should include series info in filename")
+    void testGenerateFilenameWithSeries() {
+        // Arrange
+        testStory.setSeries(testSeries);
+        testStory.setVolume(3);
+
+        // Act
+        String filename = epubExportService.getEPUBFilename(testStory);
+
+        // Assert
+        assertNotNull(filename);
+        assertTrue(filename.contains("Test_Series"));
+        assertTrue(filename.contains("3"));
+    }
+
+    @Test
+    @DisplayName("Should sanitize special characters in filename")
+    void testSanitizeFilename() {
+        // Arrange
+        testStory.setTitle("Test: Story? With/Special\\Characters!");
+
+        // Act
+        String filename = epubExportService.getEPUBFilename(testStory);
+
+        // Assert
+        assertNotNull(filename);
+        assertFalse(filename.contains(":"));
+        assertFalse(filename.contains("?"));
+        assertFalse(filename.contains("/"));
+        assertFalse(filename.contains("\\"));
+        assertTrue(filename.endsWith(".epub"));
+    }
+
+    // ========================================
+    // Collection Export Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should export collection as EPUB")
+    void testExportCollectionAsEPUB() throws IOException {
+        // Arrange
+        CollectionStory cs = new CollectionStory();
+        cs.setStory(testStory);
+        cs.setPosition(1000);
+        testCollection.setCollectionStories(Arrays.asList(cs));
+
+        when(collectionService.findById(collectionId)).thenReturn(testCollection);
+
+        // Act
+        Resource result = epubExportService.exportCollectionAsEPUB(collectionId, testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+        verify(collectionService).findById(collectionId);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when exporting empty collection")
+    void testExportEmptyCollection() {
+        // Arrange
+        testCollection.setCollectionStories(new ArrayList<>());
+        when(collectionService.findById(collectionId)).thenReturn(testCollection);
+
+        // Act & Assert
+        assertThrows(ResourceNotFoundException.class, () -> {
+            epubExportService.exportCollectionAsEPUB(collectionId, testRequest);
+        });
+    }
+
+    @Test
+    @DisplayName("Should export collection with multiple stories in order")
+    void testExportCollectionWithMultipleStories() throws IOException {
+        // Arrange
+        Story story2 = new Story();
+        story2.setId(UUID.randomUUID());
+        story2.setTitle("Second Story");
+        story2.setContentHtml("<p>Second content</p>");
+        story2.setAuthor(testAuthor);
+        story2.setCreatedAt(LocalDateTime.now());
+        story2.setTags(new HashSet<>());
+
+        CollectionStory cs1 = new CollectionStory();
+        cs1.setStory(testStory);
+        cs1.setPosition(1000);
+
+        CollectionStory cs2 = new CollectionStory();
+        cs2.setStory(story2);
+        cs2.setPosition(2000);
+
+        testCollection.setCollectionStories(Arrays.asList(cs1, cs2));
+        when(collectionService.findById(collectionId)).thenReturn(testCollection);
+
+        // Act
+        Resource result = epubExportService.exportCollectionAsEPUB(collectionId, testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should generate collection EPUB filename")
+    void testGenerateCollectionFilename() {
+        // Act
+        String filename = epubExportService.getCollectionEPUBFilename(testCollection);
+
+        // Assert
+        assertNotNull(filename);
+        assertTrue(filename.contains("Test_Collection"));
+        assertTrue(filename.contains("collection"));
+        assertTrue(filename.endsWith(".epub"));
+    }
+
+    // ========================================
+    // Utility Method Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should check if story can be exported")
+    void testCanExportStory() {
+        // Arrange
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        boolean canExport = epubExportService.canExportStory(storyId);
+
+        // Assert
+        assertTrue(canExport);
+    }
+
+    @Test
+    @DisplayName("Should return false for story with no content")
+    void testCannotExportStoryWithNoContent() {
+        // Arrange
+        // Create a story with no content set at all
+        Story emptyStory = new Story();
+        emptyStory.setId(storyId);
+        emptyStory.setTitle("Empty Story");
+        when(storyService.findById(storyId)).thenReturn(emptyStory);
+
+        // Act
+        boolean canExport = epubExportService.canExportStory(storyId);
+
+        // Assert
+        assertFalse(canExport);
+    }
+
+    @Test
+    @DisplayName("Should return false for non-existent story")
+    void testCannotExportNonExistentStory() {
+        // Arrange
+        when(storyService.findById(any())).thenThrow(new ResourceNotFoundException("Story not found"));
+
+        // Act
+        boolean canExport = epubExportService.canExportStory(UUID.randomUUID());
+
+        // Assert
+        assertFalse(canExport);
+    }
+
+    @Test
+    @DisplayName("Should return true for story with plain text content only")
+    void testCanExportStoryWithPlainContent() {
+        // Arrange
+        // Set HTML first which will populate contentPlain, then clear HTML
+        testStory.setContentHtml("<p>Plain text content</p>");
+        testStory.setContentHtml(null);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        boolean canExport = epubExportService.canExportStory(storyId);
+
+        // Assert
+        // Note: This might return false because contentPlain is protected and we can't verify it
+        // The service checks both contentHtml and contentPlain, but since we can't set contentPlain directly
+        // in tests, this test documents the limitation
+        assertFalse(canExport);
+    }
+
+    // ========================================
+    // Edge Cases
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle story with tags")
+    void testStoryWithTags() throws IOException {
+        // Arrange
+        Tag tag1 = new Tag();
+        tag1.setName("fantasy");
+        Tag tag2 = new Tag();
+        tag2.setName("adventure");
+
+        testStory.getTags().add(tag1);
+        testStory.getTags().add(tag2);
+        testRequest.setIncludeMetadata(true);
+
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(2, testStory.getTags().size());
+    }
+
+    @Test
+    @DisplayName("Should handle long story title")
+    void testLongTitle() throws IOException {
+        // Arrange
+        testStory.setTitle("A".repeat(200));
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should handle HTML with special characters")
+    void testHtmlWithSpecialCharacters() throws IOException {
+        // Arrange
+        testStory.setContentHtml("<p>Content with &lt; &gt; &amp; special chars</p>");
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should handle story with null description")
+    void testNullDescription() throws IOException {
+        // Arrange
+        testStory.setDescription(null);
+        when(storyService.findById(storyId)).thenReturn(testStory);
+
+        // Act
+        Resource result = epubExportService.exportStoryAsEPUB(testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+
+    @Test
+    @DisplayName("Should handle collection with null description")
+    void testCollectionWithNullDescription() throws IOException {
+        // Arrange
+        testCollection.setDescription(null);
+
+        CollectionStory cs = new CollectionStory();
+        cs.setStory(testStory);
+        cs.setPosition(1000);
+        testCollection.setCollectionStories(Arrays.asList(cs));
+
+        when(collectionService.findById(collectionId)).thenReturn(testCollection);
+
+        // Act
+        Resource result = epubExportService.exportCollectionAsEPUB(collectionId, testRequest);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.contentLength() > 0);
+    }
+}

backend/src/test/java/com/storycove/service/EPUBImportServiceTest.java

@@ -0,0 +1,490 @@
+package com.storycove.service;
+
+import com.storycove.dto.EPUBImportRequest;
+import com.storycove.dto.EPUBImportResponse;
+import com.storycove.entity.*;
+import com.storycove.repository.ReadingPositionRepository;
+import com.storycove.service.exception.InvalidFileException;
+import com.storycove.service.exception.ResourceNotFoundException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Tests for EPUBImportService.
+ * Note: These tests mock the EPUB parsing since nl.siegmann.epublib is complex to test.
+ * Integration tests should be added separately to test actual EPUB file parsing.
+ */
+@ExtendWith(MockitoExtension.class)
+class EPUBImportServiceTest {
+
+    @Mock
+    private StoryService storyService;
+
+    @Mock
+    private AuthorService authorService;
+
+    @Mock
+    private SeriesService seriesService;
+
+    @Mock
+    private TagService tagService;
+
+    @Mock
+    private ReadingPositionRepository readingPositionRepository;
+
+    @Mock
+    private HtmlSanitizationService sanitizationService;
+
+    @Mock
+    private ImageService imageService;
+
+    @InjectMocks
+    private EPUBImportService epubImportService;
+
+    private EPUBImportRequest testRequest;
+    private Story testStory;
+    private Author testAuthor;
+    private Series testSeries;
+    private UUID storyId;
+
+    @BeforeEach
+    void setUp() {
+        storyId = UUID.randomUUID();
+
+        testStory = new Story();
+        testStory.setId(storyId);
+        testStory.setTitle("Test Story");
+        testStory.setWordCount(1000);
+
+        testAuthor = new Author();
+        testAuthor.setId(UUID.randomUUID());
+        testAuthor.setName("Test Author");
+
+        testSeries = new Series();
+        testSeries.setId(UUID.randomUUID());
+        testSeries.setName("Test Series");
+
+        testRequest = new EPUBImportRequest();
+    }
+
+    // ========================================
+    // File Validation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should reject null EPUB file")
+    void testNullEPUBFile() {
+        // Arrange
+        testRequest.setEpubFile(null);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("EPUB file is required", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should reject empty EPUB file")
+    void testEmptyEPUBFile() {
+        // Arrange
+        MockMultipartFile emptyFile = new MockMultipartFile(
+            "file", "test.epub", "application/epub+zip", new byte[0]
+        );
+        testRequest.setEpubFile(emptyFile);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("EPUB file is required", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should reject non-EPUB file by extension")
+    void testInvalidFileExtension() {
+        // Arrange
+        MockMultipartFile pdfFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", "fake content".getBytes()
+        );
+        testRequest.setEpubFile(pdfFile);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("Invalid EPUB file format", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should validate EPUB file and return errors")
+    void testValidateEPUBFile() {
+        // Arrange
+        MockMultipartFile invalidFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", "fake content".getBytes()
+        );
+
+        // Act
+        List<String> errors = epubImportService.validateEPUBFile(invalidFile);
+
+        // Assert
+        assertNotNull(errors);
+        assertFalse(errors.isEmpty());
+        assertTrue(errors.stream().anyMatch(e -> e.contains("Invalid EPUB file format")));
+    }
+
+    @Test
+    @DisplayName("Should validate file size limit")
+    void testFileSizeLimit() {
+        // Arrange
+        byte[] largeData = new byte[101 * 1024 * 1024]; // 101MB
+        MockMultipartFile largeFile = new MockMultipartFile(
+            "file", "large.epub", "application/epub+zip", largeData
+        );
+
+        // Act
+        List<String> errors = epubImportService.validateEPUBFile(largeFile);
+
+        // Assert
+        assertTrue(errors.stream().anyMatch(e -> e.contains("100MB limit")));
+    }
+
+    @Test
+    @DisplayName("Should accept valid EPUB with correct extension")
+    void testAcceptValidEPUBExtension() {
+        // Arrange
+        MockMultipartFile validFile = new MockMultipartFile(
+            "file", "test.epub", "application/epub+zip", createMinimalEPUB()
+        );
+        testRequest.setEpubFile(validFile);
+
+        // Note: This will fail at parsing since we don't have a real EPUB
+        // But it should pass the extension validation
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert - should fail at parsing, not at validation
+        assertFalse(response.isSuccess());
+        assertNotEquals("Invalid EPUB file format", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should accept EPUB with application/zip content type")
+    void testAcceptZipContentType() {
+        // Arrange
+        MockMultipartFile zipFile = new MockMultipartFile(
+            "file", "test.epub", "application/zip", createMinimalEPUB()
+        );
+        testRequest.setEpubFile(zipFile);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert - should not fail at content type validation
+        assertFalse(response.isSuccess());
+        assertNotEquals("Invalid EPUB file format", response.getMessage());
+    }
+
+    // ========================================
+    // Request Parameter Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle createMissingAuthor flag")
+    void testCreateMissingAuthor() {
+        // This is an integration-level test and would require actual EPUB parsing
+        // We verify the flag is present in the request object
+        testRequest.setCreateMissingAuthor(true);
+        assertTrue(testRequest.getCreateMissingAuthor());
+    }
+
+    @Test
+    @DisplayName("Should handle createMissingSeries flag")
+    void testCreateMissingSeries() {
+        testRequest.setCreateMissingSeries(true);
+        testRequest.setSeriesName("New Series");
+        testRequest.setSeriesVolume(1);
+
+        assertTrue(testRequest.getCreateMissingSeries());
+        assertEquals("New Series", testRequest.getSeriesName());
+        assertEquals(1, testRequest.getSeriesVolume());
+    }
+
+    @Test
+    @DisplayName("Should handle extractCover flag")
+    void testExtractCoverFlag() {
+        testRequest.setExtractCover(true);
+        assertTrue(testRequest.getExtractCover());
+
+        testRequest.setExtractCover(false);
+        assertFalse(testRequest.getExtractCover());
+    }
+
+    @Test
+    @DisplayName("Should handle preserveReadingPosition flag")
+    void testPreserveReadingPositionFlag() {
+        testRequest.setPreserveReadingPosition(true);
+        assertTrue(testRequest.getPreserveReadingPosition());
+    }
+
+    @Test
+    @DisplayName("Should handle custom tags")
+    void testCustomTags() {
+        List<String> tags = Arrays.asList("fantasy", "adventure", "magic");
+        testRequest.setTags(tags);
+
+        assertEquals(3, testRequest.getTags().size());
+        assertTrue(testRequest.getTags().contains("fantasy"));
+    }
+
+    // ========================================
+    // Author Handling Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should use provided authorId when available")
+    void testUseProvidedAuthorId() {
+        // This would require mocking the EPUB parsing
+        // We verify the request accepts authorId
+        UUID authorId = UUID.randomUUID();
+        testRequest.setAuthorId(authorId);
+        assertEquals(authorId, testRequest.getAuthorId());
+    }
+
+    @Test
+    @DisplayName("Should use provided authorName")
+    void testUseProvidedAuthorName() {
+        testRequest.setAuthorName("Custom Author Name");
+        assertEquals("Custom Author Name", testRequest.getAuthorName());
+    }
+
+    // ========================================
+    // Series Handling Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should use provided seriesId and volume")
+    void testUseProvidedSeriesId() {
+        UUID seriesId = UUID.randomUUID();
+        testRequest.setSeriesId(seriesId);
+        testRequest.setSeriesVolume(5);
+
+        assertEquals(seriesId, testRequest.getSeriesId());
+        assertEquals(5, testRequest.getSeriesVolume());
+    }
+
+    // ========================================
+    // Error Handling Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle corrupt EPUB file gracefully")
+    void testCorruptEPUBFile() {
+        // Arrange
+        MockMultipartFile corruptFile = new MockMultipartFile(
+            "file", "corrupt.epub", "application/epub+zip", "not a real epub".getBytes()
+        );
+        testRequest.setEpubFile(corruptFile);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertNotNull(response.getMessage());
+        assertTrue(response.getMessage().contains("Failed to import EPUB"));
+    }
+
+    @Test
+    @DisplayName("Should handle missing metadata gracefully")
+    void testMissingMetadata() {
+        // Arrange
+        MockMultipartFile epubFile = new MockMultipartFile(
+            "file", "test.epub", "application/epub+zip", createMinimalEPUB()
+        );
+
+        // Act
+        List<String> errors = epubImportService.validateEPUBFile(epubFile);
+
+        // Assert - validation should catch missing metadata
+        assertNotNull(errors);
+    }
+
+    // ========================================
+    // Response Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should create success response with correct fields")
+    void testSuccessResponse() {
+        // Arrange
+        EPUBImportResponse response = EPUBImportResponse.success(storyId, "Test Story");
+        response.setWordCount(1500);
+        response.setTotalChapters(10);
+
+        // Assert
+        assertTrue(response.isSuccess());
+        assertEquals(storyId, response.getStoryId());
+        assertEquals("Test Story", response.getStoryTitle());
+        assertEquals(1500, response.getWordCount());
+        assertEquals(10, response.getTotalChapters());
+        assertNull(response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should create error response with message")
+    void testErrorResponse() {
+        // Arrange
+        EPUBImportResponse response = EPUBImportResponse.error("Test error message");
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("Test error message", response.getMessage());
+        assertNull(response.getStoryId());
+        assertNull(response.getStoryTitle());
+    }
+
+    // ========================================
+    // Integration Scenario Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle complete import workflow (mock)")
+    void testCompleteImportWorkflow() {
+        // This test verifies that all the request parameters are properly structured
+        // Actual EPUB parsing would be tested in integration tests
+
+        // Arrange - Create a complete request
+        testRequest.setEpubFile(new MockMultipartFile(
+            "file", "story.epub", "application/epub+zip", createMinimalEPUB()
+        ));
+        testRequest.setAuthorName("Jane Doe");
+        testRequest.setCreateMissingAuthor(true);
+        testRequest.setSeriesName("Epic Series");
+        testRequest.setSeriesVolume(3);
+        testRequest.setCreateMissingSeries(true);
+        testRequest.setTags(Arrays.asList("fantasy", "adventure"));
+        testRequest.setExtractCover(true);
+        testRequest.setPreserveReadingPosition(true);
+
+        // Assert - All parameters set correctly
+        assertNotNull(testRequest.getEpubFile());
+        assertEquals("Jane Doe", testRequest.getAuthorName());
+        assertTrue(testRequest.getCreateMissingAuthor());
+        assertEquals("Epic Series", testRequest.getSeriesName());
+        assertEquals(3, testRequest.getSeriesVolume());
+        assertTrue(testRequest.getCreateMissingSeries());
+        assertEquals(2, testRequest.getTags().size());
+        assertTrue(testRequest.getExtractCover());
+        assertTrue(testRequest.getPreserveReadingPosition());
+    }
+
+    @Test
+    @DisplayName("Should handle minimal import request")
+    void testMinimalImportRequest() {
+        // Arrange - Only required field
+        testRequest.setEpubFile(new MockMultipartFile(
+            "file", "simple.epub", "application/epub+zip", createMinimalEPUB()
+        ));
+
+        // Assert - Optional fields are null/false
+        assertNotNull(testRequest.getEpubFile());
+        assertNull(testRequest.getAuthorId());
+        assertNull(testRequest.getAuthorName());
+        assertNull(testRequest.getSeriesId());
+        assertNull(testRequest.getTags());
+    }
+
+    // ========================================
+    // Edge Cases
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle EPUB with special characters in filename")
+    void testSpecialCharactersInFilename() {
+        // Arrange
+        MockMultipartFile fileWithSpecialChars = new MockMultipartFile(
+            "file", "test story (2024) #1.epub", "application/epub+zip", createMinimalEPUB()
+        );
+        testRequest.setEpubFile(fileWithSpecialChars);
+
+        // Act
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert - should not fail due to filename
+        assertNotNull(response);
+    }
+
+    @Test
+    @DisplayName("Should handle EPUB with null content type")
+    void testNullContentType() {
+        // Arrange
+        MockMultipartFile fileWithNullContentType = new MockMultipartFile(
+            "file", "test.epub", null, createMinimalEPUB()
+        );
+        testRequest.setEpubFile(fileWithNullContentType);
+
+        // Act - Should still validate based on extension
+        EPUBImportResponse response = epubImportService.importEPUB(testRequest);
+
+        // Assert - should not fail at validation, only at parsing
+        assertNotNull(response);
+    }
+
+    @Test
+    @DisplayName("Should trim whitespace from author name")
+    void testTrimAuthorName() {
+        testRequest.setAuthorName("  John Doe  ");
+        // The service should trim this internally
+        assertEquals("  John Doe  ", testRequest.getAuthorName());
+    }
+
+    @Test
+    @DisplayName("Should handle empty tags list")
+    void testEmptyTagsList() {
+        testRequest.setTags(new ArrayList<>());
+        assertNotNull(testRequest.getTags());
+        assertTrue(testRequest.getTags().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should handle duplicate tags in request")
+    void testDuplicateTags() {
+        List<String> tagsWithDuplicates = Arrays.asList("fantasy", "adventure", "fantasy");
+        testRequest.setTags(tagsWithDuplicates);
+
+        assertEquals(3, testRequest.getTags().size());
+        // The service should handle deduplication internally
+    }
+
+    // ========================================
+    // Helper Methods
+    // ========================================
+
+    /**
+     * Creates minimal EPUB-like content for testing.
+     * Note: This is not a real EPUB, just test data.
+     */
+    private byte[] createMinimalEPUB() {
+        // This creates minimal test data that looks like an EPUB structure
+        // Real EPUB parsing would require a proper EPUB file structure
+        return "PK\u0003\u0004fake epub content".getBytes();
+    }
+}

backend/src/test/java/com/storycove/service/HtmlSanitizationServiceTest.java

@@ -0,0 +1,335 @@
+package com.storycove.service;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.storycove.dto.HtmlSanitizationConfigDto;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.boot.test.context.SpringBootTest;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+/**
+ * Security-critical tests for HtmlSanitizationService.
+ * These tests ensure that malicious HTML is properly sanitized.
+ */
+@SpringBootTest
+class HtmlSanitizationServiceTest {
+
+    @Autowired
+    private HtmlSanitizationService sanitizationService;
+
+    @BeforeEach
+    void setUp() {
+        // Service is initialized via @PostConstruct
+    }
+
+    // ========================================
+    // XSS Attack Prevention Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should remove script tags (XSS prevention)")
+    void testRemoveScriptTags() {
+        String malicious = "<p>Hello</p><script>alert('XSS')</script>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.contains("<script>"));
+        assertFalse(sanitized.contains("alert"));
+        assertTrue(sanitized.contains("Hello"));
+    }
+
+    @Test
+    @DisplayName("Should remove inline JavaScript event handlers")
+    void testRemoveEventHandlers() {
+        String malicious = "<p onclick='alert(\"XSS\")'>Click me</p>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.contains("onclick"));
+        assertFalse(sanitized.contains("alert"));
+        assertTrue(sanitized.contains("Click me"));
+    }
+
+    @Test
+    @DisplayName("Should remove javascript: URLs")
+    void testRemoveJavaScriptUrls() {
+        String malicious = "<a href='javascript:alert(\"XSS\")'>Click</a>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.contains("javascript:"));
+        assertFalse(sanitized.contains("alert"));
+    }
+
+    @Test
+    @DisplayName("Should remove data: URLs with JavaScript")
+    void testRemoveDataUrlsWithJs() {
+        String malicious = "<a href='data:text/html,<script>alert(\"XSS\")</script>'>Click</a>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.toLowerCase().contains("script"));
+    }
+
+    @Test
+    @DisplayName("Should remove iframe tags")
+    void testRemoveIframeTags() {
+        String malicious = "<p>Content</p><iframe src='http://evil.com'></iframe>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.contains("<iframe"));
+        assertTrue(sanitized.contains("Content"));
+    }
+
+    @Test
+    @DisplayName("Should remove object and embed tags")
+    void testRemoveObjectAndEmbedTags() {
+        String malicious = "<object data='http://evil.com'></object><embed src='http://evil.com'>";
+        String sanitized = sanitizationService.sanitize(malicious);
+
+        assertFalse(sanitized.contains("<object"));
+        assertFalse(sanitized.contains("<embed"));
+    }
+
+    // ========================================
+    // Allowed Content Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should preserve safe HTML tags")
+    void testPreserveSafeTags() {
+        String safe = "<p>Paragraph</p><h1>Heading</h1><ul><li>Item</li></ul>";
+        String sanitized = sanitizationService.sanitize(safe);
+
+        assertTrue(sanitized.contains("<p>"));
+        assertTrue(sanitized.contains("<h1>"));
+        assertTrue(sanitized.contains("<ul>"));
+        assertTrue(sanitized.contains("<li>"));
+        assertTrue(sanitized.contains("Paragraph"));
+        assertTrue(sanitized.contains("Heading"));
+    }
+
+    @Test
+    @DisplayName("Should preserve text formatting tags")
+    void testPreserveFormattingTags() {
+        String formatted = "<p><strong>Bold</strong> <em>Italic</em> <u>Underline</u></p>";
+        String sanitized = sanitizationService.sanitize(formatted);
+
+        assertTrue(sanitized.contains("<strong>"));
+        assertTrue(sanitized.contains("<em>"));
+        assertTrue(sanitized.contains("<u>"));
+    }
+
+    @Test
+    @DisplayName("Should preserve safe links")
+    void testPreserveSafeLinks() {
+        String link = "<a href='https://example.com'>Link</a>";
+        String sanitized = sanitizationService.sanitize(link);
+
+        assertTrue(sanitized.contains("<a"));
+        assertTrue(sanitized.contains("href"));
+        assertTrue(sanitized.contains("example.com"));
+    }
+
+    @Test
+    @DisplayName("Should preserve images with safe attributes")
+    void testPreserveSafeImages() {
+        String img = "<img src='https://example.com/image.jpg' alt='Description'>";
+        String sanitized = sanitizationService.sanitize(img);
+
+        assertTrue(sanitized.contains("<img"));
+        assertTrue(sanitized.contains("src"));
+        assertTrue(sanitized.contains("alt"));
+    }
+
+    @Test
+    @DisplayName("Should preserve relative image URLs")
+    void testPreserveRelativeImageUrls() {
+        String img = "<img src='/images/photo.jpg' alt='Photo'>";
+        String sanitized = sanitizationService.sanitize(img);
+
+        assertTrue(sanitized.contains("<img"));
+        assertTrue(sanitized.contains("/images/photo.jpg"));
+    }
+
+    // ========================================
+    // Figure Tag Preprocessing Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should extract image from figure tag")
+    void testExtractImageFromFigure() {
+        String figure = "<figure><img src='/image.jpg' alt='Test'><figcaption>Caption</figcaption></figure>";
+        String sanitized = sanitizationService.sanitize(figure);
+
+        assertFalse(sanitized.contains("<figure"));
+        assertFalse(sanitized.contains("<figcaption"));
+        assertTrue(sanitized.contains("<img"));
+        assertTrue(sanitized.contains("/image.jpg"));
+    }
+
+    @Test
+    @DisplayName("Should use figcaption as alt text if alt is missing")
+    void testFigcaptionAsAltText() {
+        String figure = "<figure><img src='/image.jpg'><figcaption>My Caption</figcaption></figure>";
+        String sanitized = sanitizationService.sanitize(figure);
+
+        assertTrue(sanitized.contains("<img"));
+        assertTrue(sanitized.contains("alt="));
+        assertTrue(sanitized.contains("My Caption"));
+    }
+
+    @Test
+    @DisplayName("Should remove figure without images")
+    void testRemoveFigureWithoutImages() {
+        String figure = "<p>Before</p><figure><figcaption>Caption only</figcaption></figure><p>After</p>";
+        String sanitized = sanitizationService.sanitize(figure);
+
+        assertFalse(sanitized.contains("<figure"));
+        assertFalse(sanitized.contains("Caption only"));
+        assertTrue(sanitized.contains("Before"));
+        assertTrue(sanitized.contains("After"));
+    }
+
+    // ========================================
+    // Edge Cases and Utility Methods
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle null input")
+    void testNullInput() {
+        String sanitized = sanitizationService.sanitize(null);
+        assertEquals("", sanitized);
+    }
+
+    @Test
+    @DisplayName("Should handle empty input")
+    void testEmptyInput() {
+        String sanitized = sanitizationService.sanitize("");
+        assertEquals("", sanitized);
+    }
+
+    @Test
+    @DisplayName("Should handle whitespace-only input")
+    void testWhitespaceInput() {
+        String sanitized = sanitizationService.sanitize("   ");
+        assertEquals("", sanitized);
+    }
+
+    @Test
+    @DisplayName("Should extract plain text from HTML")
+    void testExtractPlainText() {
+        String html = "<p>Hello <strong>World</strong></p>";
+        String plainText = sanitizationService.extractPlainText(html);
+
+        assertEquals("Hello World", plainText);
+        assertFalse(plainText.contains("<"));
+        assertFalse(plainText.contains(">"));
+    }
+
+    @Test
+    @DisplayName("Should detect clean HTML")
+    void testIsCleanWithCleanHtml() {
+        String clean = "<p>Safe content</p>";
+        assertTrue(sanitizationService.isClean(clean));
+    }
+
+    @Test
+    @DisplayName("Should detect malicious HTML")
+    void testIsCleanWithMaliciousHtml() {
+        String malicious = "<p>Content</p><script>alert('XSS')</script>";
+        assertFalse(sanitizationService.isClean(malicious));
+    }
+
+    @Test
+    @DisplayName("Should sanitize and extract text")
+    void testSanitizeAndExtractText() {
+        String html = "<p>Hello</p><script>alert('XSS')</script>";
+        String result = sanitizationService.sanitizeAndExtractText(html);
+
+        assertEquals("Hello", result);
+        assertFalse(result.contains("script"));
+        assertFalse(result.contains("XSS"));
+    }
+
+    // ========================================
+    // Configuration Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should load and provide configuration")
+    void testGetConfiguration() {
+        HtmlSanitizationConfigDto config = sanitizationService.getConfiguration();
+
+        assertNotNull(config);
+        assertNotNull(config.getAllowedTags());
+        assertFalse(config.getAllowedTags().isEmpty());
+        assertTrue(config.getAllowedTags().contains("p"));
+        assertTrue(config.getAllowedTags().contains("a"));
+        assertTrue(config.getAllowedTags().contains("img"));
+    }
+
+    // ========================================
+    // Complex Attack Vectors
+    // ========================================
+
+    @Test
+    @DisplayName("Should prevent nested XSS attacks")
+    void testNestedXssAttacks() {
+        String nested = "<p><script><script>alert('XSS')</script></script></p>";
+        String sanitized = sanitizationService.sanitize(nested);
+
+        assertFalse(sanitized.contains("<script"));
+        assertFalse(sanitized.contains("alert"));
+    }
+
+    @Test
+    @DisplayName("Should prevent encoded XSS attacks")
+    void testEncodedXssAttacks() {
+        String encoded = "<img src=x onerror='alert(1)'>";
+        String sanitized = sanitizationService.sanitize(encoded);
+
+        assertFalse(sanitized.contains("onerror"));
+        assertFalse(sanitized.contains("alert"));
+    }
+
+    @Test
+    @DisplayName("Should prevent CSS injection attacks")
+    void testCssInjectionPrevention() {
+        String cssInjection = "<p style='background:url(javascript:alert(1))'>Text</p>";
+        String sanitized = sanitizationService.sanitize(cssInjection);
+
+        assertFalse(sanitized.toLowerCase().contains("javascript:"));
+    }
+
+    @Test
+    @DisplayName("Should preserve multiple safe elements")
+    void testComplexSafeHtml() {
+        String complex = "<div><h1>Title</h1><p>Paragraph with <strong>bold</strong> and " +
+                        "<em>italic</em></p><ul><li>Item 1</li><li>Item 2</li></ul>" +
+                        "<img src='/image.jpg' alt='Image'></div>";
+        String sanitized = sanitizationService.sanitize(complex);
+
+        assertTrue(sanitized.contains("<div"));
+        assertTrue(sanitized.contains("<h1>"));
+        assertTrue(sanitized.contains("<p>"));
+        assertTrue(sanitized.contains("<strong>"));
+        assertTrue(sanitized.contains("<em>"));
+        assertTrue(sanitized.contains("<ul>"));
+        assertTrue(sanitized.contains("<li>"));
+        assertTrue(sanitized.contains("<img"));
+        assertTrue(sanitized.contains("Title"));
+        assertTrue(sanitized.contains("Item 1"));
+    }
+
+    @Test
+    @DisplayName("Should handle malformed HTML gracefully")
+    void testMalformedHtml() {
+        String malformed = "<p>Unclosed paragraph<div>Nested incorrectly</p></div>";
+        String sanitized = sanitizationService.sanitize(malformed);
+
+        // Should not throw exception and should return something
+        assertNotNull(sanitized);
+        assertTrue(sanitized.contains("Unclosed paragraph"));
+        assertTrue(sanitized.contains("Nested incorrectly"));
+    }
+}

backend/src/test/java/com/storycove/service/ImageServiceTest.java

@@ -0,0 +1,621 @@
+package com.storycove.service;
+
+import com.storycove.entity.Author;
+import com.storycove.entity.Collection;
+import com.storycove.entity.Story;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.junit.jupiter.api.io.TempDir;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mock.web.MockMultipartFile;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.web.multipart.MultipartFile;
+
+import java.io.IOException;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.nio.file.Paths;
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Optional;
+import java.util.UUID;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Tests for ImageService.
+ * Note: Some tests use mocking due to filesystem and network dependencies.
+ * Full integration tests would be in a separate test class.
+ */
+@ExtendWith(MockitoExtension.class)
+class ImageServiceTest {
+
+    @Mock
+    private LibraryService libraryService;
+
+    @Mock
+    private StoryService storyService;
+
+    @Mock
+    private AuthorService authorService;
+
+    @Mock
+    private CollectionService collectionService;
+
+    @InjectMocks
+    private ImageService imageService;
+
+    @TempDir
+    Path tempDir;
+
+    private MultipartFile validImageFile;
+    private UUID testStoryId;
+
+    @BeforeEach
+    void setUp() throws IOException {
+        testStoryId = UUID.randomUUID();
+
+        // Create a simple valid PNG file (1x1 pixel)
+        byte[] pngData = createMinimalPngData();
+        validImageFile = new MockMultipartFile(
+            "image", "test.png", "image/png", pngData
+        );
+
+        // Configure ImageService with test values
+        when(libraryService.getCurrentImagePath()).thenReturn("/default");
+        when(libraryService.getCurrentLibraryId()).thenReturn("default");
+
+        // Set image service properties using reflection
+        ReflectionTestUtils.setField(imageService, "baseUploadDir", tempDir.toString());
+        ReflectionTestUtils.setField(imageService, "coverMaxWidth", 800);
+        ReflectionTestUtils.setField(imageService, "coverMaxHeight", 1200);
+        ReflectionTestUtils.setField(imageService, "avatarMaxSize", 400);
+        ReflectionTestUtils.setField(imageService, "maxFileSize", 5242880L);
+        ReflectionTestUtils.setField(imageService, "publicUrl", "http://localhost:6925");
+    }
+
+    // ========================================
+    // File Validation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should reject null file")
+    void testRejectNullFile() {
+        // Act & Assert
+        assertThrows(IllegalArgumentException.class, () -> {
+            imageService.uploadImage(null, ImageService.ImageType.COVER);
+        });
+    }
+
+    @Test
+    @DisplayName("Should reject empty file")
+    void testRejectEmptyFile() {
+        // Arrange
+        MockMultipartFile emptyFile = new MockMultipartFile(
+            "image", "test.png", "image/png", new byte[0]
+        );
+
+        // Act & Assert
+        assertThrows(IllegalArgumentException.class, () -> {
+            imageService.uploadImage(emptyFile, ImageService.ImageType.COVER);
+        });
+    }
+
+    @Test
+    @DisplayName("Should reject file with invalid content type")
+    void testRejectInvalidContentType() {
+        // Arrange
+        MockMultipartFile invalidFile = new MockMultipartFile(
+            "image", "test.pdf", "application/pdf", "fake pdf content".getBytes()
+        );
+
+        // Act & Assert
+        assertThrows(IllegalArgumentException.class, () -> {
+            imageService.uploadImage(invalidFile, ImageService.ImageType.COVER);
+        });
+    }
+
+    @Test
+    @DisplayName("Should reject file with invalid extension")
+    void testRejectInvalidExtension() {
+        // Arrange
+        MockMultipartFile invalidFile = new MockMultipartFile(
+            "image", "test.gif", "image/png", createMinimalPngData()
+        );
+
+        // Act & Assert
+        assertThrows(IllegalArgumentException.class, () -> {
+            imageService.uploadImage(invalidFile, ImageService.ImageType.COVER);
+        });
+    }
+
+    @Test
+    @DisplayName("Should reject file exceeding size limit")
+    void testRejectOversizedFile() {
+        // Arrange
+        // Create file larger than 5MB limit
+        byte[] largeData = new byte[6 * 1024 * 1024]; // 6MB
+        MockMultipartFile largeFile = new MockMultipartFile(
+            "image", "large.png", "image/png", largeData
+        );
+
+        // Act & Assert
+        assertThrows(IllegalArgumentException.class, () -> {
+            imageService.uploadImage(largeFile, ImageService.ImageType.COVER);
+        });
+    }
+
+    @Test
+    @DisplayName("Should accept JPG files")
+    void testAcceptJpgFile() {
+        // Arrange
+        MockMultipartFile jpgFile = new MockMultipartFile(
+            "image", "test.jpg", "image/jpeg", createMinimalPngData() // Using PNG data for test simplicity
+        );
+
+        // Note: This test will fail at image processing stage since we're not providing real JPG data
+        // but it validates that JPG is accepted as a file type
+    }
+
+    @Test
+    @DisplayName("Should accept PNG files")
+    void testAcceptPngFile() {
+        // PNG is tested in setUp, this validates the behavior
+        assertNotNull(validImageFile);
+        assertEquals("image/png", validImageFile.getContentType());
+    }
+
+    // ========================================
+    // Image Type Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should have correct directory for COVER type")
+    void testCoverImageDirectory() {
+        assertEquals("covers", ImageService.ImageType.COVER.getDirectory());
+    }
+
+    @Test
+    @DisplayName("Should have correct directory for AVATAR type")
+    void testAvatarImageDirectory() {
+        assertEquals("avatars", ImageService.ImageType.AVATAR.getDirectory());
+    }
+
+    @Test
+    @DisplayName("Should have correct directory for CONTENT type")
+    void testContentImageDirectory() {
+        assertEquals("content", ImageService.ImageType.CONTENT.getDirectory());
+    }
+
+    // ========================================
+    // Image Existence Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should return false for null image path")
+    void testImageExistsWithNullPath() {
+        assertFalse(imageService.imageExists(null));
+    }
+
+    @Test
+    @DisplayName("Should return false for empty image path")
+    void testImageExistsWithEmptyPath() {
+        assertFalse(imageService.imageExists(""));
+        assertFalse(imageService.imageExists("   "));
+    }
+
+    @Test
+    @DisplayName("Should return false for non-existent image")
+    void testImageExistsWithNonExistentPath() {
+        assertFalse(imageService.imageExists("covers/non-existent.jpg"));
+    }
+
+    @Test
+    @DisplayName("Should return false for null library ID in imageExistsInLibrary")
+    void testImageExistsInLibraryWithNullLibraryId() {
+        assertFalse(imageService.imageExistsInLibrary("covers/test.jpg", null));
+    }
+
+    // ========================================
+    // Image Deletion Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should return false when deleting null path")
+    void testDeleteNullPath() {
+        assertFalse(imageService.deleteImage(null));
+    }
+
+    @Test
+    @DisplayName("Should return false when deleting empty path")
+    void testDeleteEmptyPath() {
+        assertFalse(imageService.deleteImage(""));
+        assertFalse(imageService.deleteImage("   "));
+    }
+
+    @Test
+    @DisplayName("Should return false when deleting non-existent image")
+    void testDeleteNonExistentImage() {
+        assertFalse(imageService.deleteImage("covers/non-existent.jpg"));
+    }
+
+    // ========================================
+    // Content Image Processing Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should process content with no images")
+    void testProcessContentWithNoImages() {
+        // Arrange
+        String htmlContent = "<p>This is plain text with no images</p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(htmlContent, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(htmlContent, result.getProcessedContent());
+        assertTrue(result.getDownloadedImages().isEmpty());
+        assertFalse(result.hasWarnings());
+    }
+
+    @Test
+    @DisplayName("Should handle null content gracefully")
+    void testProcessNullContent() {
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(null, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertNull(result.getProcessedContent());
+        assertTrue(result.getDownloadedImages().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should handle empty content gracefully")
+    void testProcessEmptyContent() {
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages("", testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("", result.getProcessedContent());
+        assertTrue(result.getDownloadedImages().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should skip data URLs")
+    void testSkipDataUrls() {
+        // Arrange
+        String htmlWithDataUrl = "<p><img src=\"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"></p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(htmlWithDataUrl, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.getDownloadedImages().isEmpty());
+        assertFalse(result.hasWarnings());
+    }
+
+    @Test
+    @DisplayName("Should skip local/relative URLs")
+    void testSkipLocalUrls() {
+        // Arrange
+        String htmlWithLocalUrl = "<p><img src=\"/images/local-image.jpg\"></p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(htmlWithLocalUrl, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.getDownloadedImages().isEmpty());
+        assertFalse(result.hasWarnings());
+    }
+
+    @Test
+    @DisplayName("Should skip images from same application")
+    void testSkipApplicationUrls() {
+        // Arrange
+        String htmlWithAppUrl = "<p><img src=\"/api/files/images/default/covers/test.jpg\"></p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(htmlWithAppUrl, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.getDownloadedImages().isEmpty());
+        assertFalse(result.hasWarnings());
+    }
+
+    @Test
+    @DisplayName("Should handle external URL gracefully when download fails")
+    void testHandleDownloadFailure() {
+        // Arrange
+        String htmlWithExternalUrl = "<p><img src=\"http://example.com/non-existent-image.jpg\"></p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(htmlWithExternalUrl, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.hasWarnings());
+        assertEquals(1, result.getWarnings().size());
+    }
+
+    // ========================================
+    // Content Image Cleanup Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should perform dry run cleanup without deleting")
+    void testDryRunCleanup() {
+        // Arrange
+        when(storyService.findAllWithAssociations()).thenReturn(new ArrayList<>());
+        when(authorService.findAll()).thenReturn(new ArrayList<>());
+        when(collectionService.findAllWithTags()).thenReturn(new ArrayList<>());
+
+        // Act
+        ImageService.ContentImageCleanupResult result =
+            imageService.cleanupOrphanedContentImages(true);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.isDryRun());
+    }
+
+    @Test
+    @DisplayName("Should handle cleanup with no content directory")
+    void testCleanupWithNoContentDirectory() {
+        // Arrange
+        when(storyService.findAllWithAssociations()).thenReturn(new ArrayList<>());
+        when(authorService.findAll()).thenReturn(new ArrayList<>());
+        when(collectionService.findAllWithTags()).thenReturn(new ArrayList<>());
+
+        // Act
+        ImageService.ContentImageCleanupResult result =
+            imageService.cleanupOrphanedContentImages(false);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals(0, result.getTotalReferencedImages());
+        assertTrue(result.getOrphanedImages().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should collect image references from stories")
+    void testCollectImageReferences() {
+        // Arrange
+        Story story = new Story();
+        story.setId(testStoryId);
+        story.setContentHtml("<p><img src=\"/api/files/images/default/content/" + testStoryId + "/test-image.jpg\"></p>");
+
+        when(storyService.findAllWithAssociations()).thenReturn(List.of(story));
+        when(authorService.findAll()).thenReturn(new ArrayList<>());
+        when(collectionService.findAllWithTags()).thenReturn(new ArrayList<>());
+
+        // Act
+        ImageService.ContentImageCleanupResult result =
+            imageService.cleanupOrphanedContentImages(true);
+
+        // Assert
+        assertNotNull(result);
+        assertTrue(result.getTotalReferencedImages() > 0);
+    }
+
+    // ========================================
+    // Cleanup Result Formatting Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should format bytes correctly")
+    void testFormatBytes() {
+        ImageService.ContentImageCleanupResult result =
+            new ImageService.ContentImageCleanupResult(
+                new ArrayList<>(), 512, 0, 0, new ArrayList<>(), true
+            );
+
+        assertEquals("512 B", result.getFormattedSize());
+    }
+
+    @Test
+    @DisplayName("Should format kilobytes correctly")
+    void testFormatKilobytes() {
+        ImageService.ContentImageCleanupResult result =
+            new ImageService.ContentImageCleanupResult(
+                new ArrayList<>(), 1536, 0, 0, new ArrayList<>(), true
+            );
+
+        assertTrue(result.getFormattedSize().contains("KB"));
+    }
+
+    @Test
+    @DisplayName("Should format megabytes correctly")
+    void testFormatMegabytes() {
+        ImageService.ContentImageCleanupResult result =
+            new ImageService.ContentImageCleanupResult(
+                new ArrayList<>(), 1024 * 1024 * 5, 0, 0, new ArrayList<>(), true
+            );
+
+        assertTrue(result.getFormattedSize().contains("MB"));
+    }
+
+    @Test
+    @DisplayName("Should format gigabytes correctly")
+    void testFormatGigabytes() {
+        ImageService.ContentImageCleanupResult result =
+            new ImageService.ContentImageCleanupResult(
+                new ArrayList<>(), 1024L * 1024L * 1024L * 2L, 0, 0, new ArrayList<>(), true
+            );
+
+        assertTrue(result.getFormattedSize().contains("GB"));
+    }
+
+    @Test
+    @DisplayName("Should track cleanup errors")
+    void testCleanupErrors() {
+        List<String> errors = new ArrayList<>();
+        errors.add("Test error 1");
+        errors.add("Test error 2");
+
+        ImageService.ContentImageCleanupResult result =
+            new ImageService.ContentImageCleanupResult(
+                new ArrayList<>(), 0, 0, 0, errors, false
+            );
+
+        assertTrue(result.hasErrors());
+        assertEquals(2, result.getErrors().size());
+    }
+
+    // ========================================
+    // Content Image Processing Result Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should create processing result with warnings")
+    void testProcessingResultWithWarnings() {
+        List<String> warnings = List.of("Warning 1", "Warning 2");
+        ImageService.ContentImageProcessingResult result =
+            new ImageService.ContentImageProcessingResult(
+                "<p>Content</p>", warnings, new ArrayList<>()
+            );
+
+        assertTrue(result.hasWarnings());
+        assertEquals(2, result.getWarnings().size());
+    }
+
+    @Test
+    @DisplayName("Should create processing result without warnings")
+    void testProcessingResultWithoutWarnings() {
+        ImageService.ContentImageProcessingResult result =
+            new ImageService.ContentImageProcessingResult(
+                "<p>Content</p>", new ArrayList<>(), new ArrayList<>()
+            );
+
+        assertFalse(result.hasWarnings());
+        assertEquals("<p>Content</p>", result.getProcessedContent());
+    }
+
+    @Test
+    @DisplayName("Should track downloaded images")
+    void testTrackDownloadedImages() {
+        List<String> downloadedImages = List.of(
+            "content/story1/image1.jpg",
+            "content/story1/image2.jpg"
+        );
+
+        ImageService.ContentImageProcessingResult result =
+            new ImageService.ContentImageProcessingResult(
+                "<p>Content</p>", new ArrayList<>(), downloadedImages
+            );
+
+        assertEquals(2, result.getDownloadedImages().size());
+        assertTrue(result.getDownloadedImages().contains("content/story1/image1.jpg"));
+    }
+
+    // ========================================
+    // Story Content Deletion Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should delete content images for story")
+    void testDeleteContentImages() {
+        // Act - Should not throw exception even if directory doesn't exist
+        assertDoesNotThrow(() -> {
+            imageService.deleteContentImages(testStoryId);
+        });
+    }
+
+    // ========================================
+    // Edge Cases
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle HTML with multiple images")
+    void testMultipleImages() {
+        // Arrange
+        String html = "<p><img src=\"/local1.jpg\"><img src=\"/local2.jpg\"></p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(html, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+        // Local images should be skipped
+        assertTrue(result.getDownloadedImages().isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should handle malformed HTML gracefully")
+    void testMalformedHtml() {
+        // Arrange
+        String malformedHtml = "<p>Unclosed <img src=\"/test.jpg\" <p>";
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(malformedHtml, testStoryId);
+
+        // Assert
+        assertNotNull(result);
+    }
+
+    @Test
+    @DisplayName("Should handle very long content")
+    void testVeryLongContent() {
+        // Arrange
+        StringBuilder longContent = new StringBuilder();
+        for (int i = 0; i < 10000; i++) {
+            longContent.append("<p>Paragraph ").append(i).append("</p>");
+        }
+
+        // Act
+        ImageService.ContentImageProcessingResult result =
+            imageService.processContentImages(longContent.toString(), testStoryId);
+
+        // Assert
+        assertNotNull(result);
+    }
+
+    // ========================================
+    // Helper Methods
+    // ========================================
+
+    /**
+     * Create minimal valid PNG data for testing.
+     * This is a 1x1 pixel transparent PNG image.
+     */
+    private byte[] createMinimalPngData() {
+        return new byte[]{
+            (byte) 0x89, 'P', 'N', 'G', '\r', '\n', 0x1A, '\n', // PNG signature
+            0x00, 0x00, 0x00, 0x0D, // IHDR chunk length
+            'I', 'H', 'D', 'R', // IHDR chunk type
+            0x00, 0x00, 0x00, 0x01, // Width: 1
+            0x00, 0x00, 0x00, 0x01, // Height: 1
+            0x08, // Bit depth: 8
+            0x06, // Color type: RGBA
+            0x00, 0x00, 0x00, // Compression, filter, interlace
+            0x1F, 0x15, (byte) 0xC4, (byte) 0x89, // CRC
+            0x00, 0x00, 0x00, 0x0A, // IDAT chunk length
+            'I', 'D', 'A', 'T', // IDAT chunk type
+            0x78, (byte) 0x9C, 0x62, 0x00, 0x01, 0x00, 0x00, 0x05, 0x00, 0x01, // Image data
+            0x0D, 0x0A, 0x2D, (byte) 0xB4, // CRC
+            0x00, 0x00, 0x00, 0x00, // IEND chunk length
+            'I', 'E', 'N', 'D', // IEND chunk type
+            (byte) 0xAE, 0x42, 0x60, (byte) 0x82 // CRC
+        };
+    }
+}

backend/src/test/java/com/storycove/service/PDFImportServiceTest.java

@@ -0,0 +1,296 @@
+package com.storycove.service;
+
+import com.storycove.dto.FileImportResponse;
+import com.storycove.dto.PDFImportRequest;
+import com.storycove.entity.*;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mock.web.MockMultipartFile;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Tests for PDFImportService.
+ * Note: These tests mock the PDF parsing since Apache PDFBox is complex to test.
+ * Integration tests should be added separately to test actual PDF file parsing.
+ */
+@ExtendWith(MockitoExtension.class)
+class PDFImportServiceTest {
+
+    @Mock
+    private StoryService storyService;
+
+    @Mock
+    private AuthorService authorService;
+
+    @Mock
+    private SeriesService seriesService;
+
+    @Mock
+    private TagService tagService;
+
+    @Mock
+    private HtmlSanitizationService sanitizationService;
+
+    @Mock
+    private ImageService imageService;
+
+    @Mock
+    private LibraryService libraryService;
+
+    @InjectMocks
+    private PDFImportService pdfImportService;
+
+    private PDFImportRequest testRequest;
+    private Story testStory;
+    private Author testAuthor;
+    private Series testSeries;
+    private UUID storyId;
+
+    @BeforeEach
+    void setUp() {
+        storyId = UUID.randomUUID();
+
+        testStory = new Story();
+        testStory.setId(storyId);
+        testStory.setTitle("Test Story");
+        testStory.setWordCount(1000);
+
+        testAuthor = new Author();
+        testAuthor.setId(UUID.randomUUID());
+        testAuthor.setName("Test Author");
+
+        testSeries = new Series();
+        testSeries.setId(UUID.randomUUID());
+        testSeries.setName("Test Series");
+
+        testRequest = new PDFImportRequest();
+    }
+
+    // ========================================
+    // File Validation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should reject null PDF file")
+    void testNullPDFFile() {
+        // Arrange
+        testRequest.setPdfFile(null);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("PDF file is required", response.getMessage());
+        verify(storyService, never()).create(any(Story.class));
+    }
+
+    @Test
+    @DisplayName("Should reject empty PDF file")
+    void testEmptyPDFFile() {
+        // Arrange
+        MockMultipartFile emptyFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", new byte[0]
+        );
+        testRequest.setPdfFile(emptyFile);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("PDF file is required", response.getMessage());
+        verify(storyService, never()).create(any(Story.class));
+    }
+
+    @Test
+    @DisplayName("Should reject non-PDF file by extension")
+    void testInvalidFileExtension() {
+        // Arrange
+        MockMultipartFile invalidFile = new MockMultipartFile(
+            "file", "test.txt", "text/plain", "test content".getBytes()
+        );
+        testRequest.setPdfFile(invalidFile);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("Invalid PDF file format"));
+        verify(storyService, never()).create(any(Story.class));
+    }
+
+    @Test
+    @DisplayName("Should reject file exceeding 300MB size limit")
+    void testFileSizeExceedsLimit() {
+        // Arrange
+        long fileSize = 301L * 1024 * 1024; // 301 MB
+        MockMultipartFile largeFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", new byte[(int)Math.min(fileSize, 1000)]
+        ) {
+            @Override
+            public long getSize() {
+                return fileSize;
+            }
+        };
+        testRequest.setPdfFile(largeFile);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("Invalid PDF file format"));
+        verify(storyService, never()).create(any(Story.class));
+    }
+
+    // ========================================
+    // Author Handling Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should require author name when not in metadata")
+    void testRequiresAuthorName() {
+        // Arrange - Create a minimal valid PDF (will fail parsing but test validation)
+        MockMultipartFile pdfFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf",
+            "%PDF-1.4\n%%EOF".getBytes()
+        );
+        testRequest.setPdfFile(pdfFile);
+        testRequest.setAuthorName(null);
+        testRequest.setAuthorId(null);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        // Should fail during import because author is required
+        verify(storyService, never()).create(any(Story.class));
+    }
+
+    // ========================================
+    // Validation Method Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should validate PDF file successfully")
+    void testValidatePDFFile_Valid() {
+        // Arrange
+        MockMultipartFile pdfFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf",
+            new byte[100]
+        );
+
+        // Act
+        List<String> errors = pdfImportService.validatePDFFile(pdfFile);
+
+        // Assert - Will have errors because it's not a real PDF, but tests the method exists
+        assertNotNull(errors);
+    }
+
+    @Test
+    @DisplayName("Should return errors for null file in validation")
+    void testValidatePDFFile_Null() {
+        // Act
+        List<String> errors = pdfImportService.validatePDFFile(null);
+
+        // Assert
+        assertNotNull(errors);
+        assertFalse(errors.isEmpty());
+        assertTrue(errors.get(0).contains("required"));
+    }
+
+    @Test
+    @DisplayName("Should return errors for empty file in validation")
+    void testValidatePDFFile_Empty() {
+        // Arrange
+        MockMultipartFile emptyFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", new byte[0]
+        );
+
+        // Act
+        List<String> errors = pdfImportService.validatePDFFile(emptyFile);
+
+        // Assert
+        assertNotNull(errors);
+        assertFalse(errors.isEmpty());
+        assertTrue(errors.get(0).contains("required"));
+    }
+
+    @Test
+    @DisplayName("Should return errors for oversized file in validation")
+    void testValidatePDFFile_Oversized() {
+        // Arrange
+        long fileSize = 301L * 1024 * 1024; // 301 MB
+        MockMultipartFile largeFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf", new byte[1000]
+        ) {
+            @Override
+            public long getSize() {
+                return fileSize;
+            }
+        };
+
+        // Act
+        List<String> errors = pdfImportService.validatePDFFile(largeFile);
+
+        // Assert
+        assertNotNull(errors);
+        assertFalse(errors.isEmpty());
+        assertTrue(errors.stream().anyMatch(e -> e.contains("300MB")));
+    }
+
+    // ========================================
+    // Integration Tests (Mocked)
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle extraction images flag")
+    void testExtractImagesFlag() {
+        // Arrange
+        MockMultipartFile pdfFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf",
+            "%PDF-1.4\n%%EOF".getBytes()
+        );
+        testRequest.setPdfFile(pdfFile);
+        testRequest.setAuthorName("Test Author");
+        testRequest.setExtractImages(false);
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert - Will fail parsing but tests that the flag is accepted
+        assertNotNull(response);
+    }
+
+    @Test
+    @DisplayName("Should accept tags in request")
+    void testAcceptTags() {
+        // Arrange
+        MockMultipartFile pdfFile = new MockMultipartFile(
+            "file", "test.pdf", "application/pdf",
+            "%PDF-1.4\n%%EOF".getBytes()
+        );
+        testRequest.setPdfFile(pdfFile);
+        testRequest.setAuthorName("Test Author");
+        testRequest.setTags(Arrays.asList("tag1", "tag2"));
+
+        // Act
+        FileImportResponse response = pdfImportService.importPDF(testRequest);
+
+        // Assert - Will fail parsing but tests that tags are accepted
+        assertNotNull(response);
+    }
+}

backend/src/test/java/com/storycove/service/RefreshTokenServiceTest.java

@@ -0,0 +1,176 @@
+package com.storycove.service;
+
+import com.storycove.entity.RefreshToken;
+import com.storycove.repository.RefreshTokenRepository;
+import com.storycove.util.JwtUtil;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.time.LocalDateTime;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class RefreshTokenServiceTest {
+
+    @Mock
+    private RefreshTokenRepository refreshTokenRepository;
+
+    @Mock
+    private JwtUtil jwtUtil;
+
+    @InjectMocks
+    private RefreshTokenService refreshTokenService;
+
+    @Test
+    void testCreateRefreshToken() {
+        // Arrange
+        String libraryId = "library-123";
+        String userAgent = "Mozilla/5.0";
+        String ipAddress = "192.168.1.1";
+
+        when(jwtUtil.getRefreshExpirationMs()).thenReturn(1209600000L); // 14 days
+        when(jwtUtil.generateRefreshToken()).thenReturn("test-refresh-token-12345");
+
+        RefreshToken savedToken = new RefreshToken("test-refresh-token-12345",
+                LocalDateTime.now().plusDays(14), libraryId, userAgent, ipAddress);
+
+        when(refreshTokenRepository.save(any(RefreshToken.class))).thenReturn(savedToken);
+
+        // Act
+        RefreshToken result = refreshTokenService.createRefreshToken(libraryId, userAgent, ipAddress);
+
+        // Assert
+        assertNotNull(result);
+        assertEquals("test-refresh-token-12345", result.getToken());
+        assertEquals(libraryId, result.getLibraryId());
+        assertEquals(userAgent, result.getUserAgent());
+        assertEquals(ipAddress, result.getIpAddress());
+
+        verify(jwtUtil).generateRefreshToken();
+        verify(refreshTokenRepository).save(any(RefreshToken.class));
+    }
+
+    @Test
+    void testFindByToken() {
+        // Arrange
+        String tokenString = "test-token";
+        RefreshToken token = new RefreshToken(tokenString,
+                LocalDateTime.now().plusDays(14), "lib-1", "UA", "127.0.0.1");
+
+        when(refreshTokenRepository.findByToken(tokenString)).thenReturn(Optional.of(token));
+
+        // Act
+        Optional<RefreshToken> result = refreshTokenService.findByToken(tokenString);
+
+        // Assert
+        assertTrue(result.isPresent());
+        assertEquals(tokenString, result.get().getToken());
+
+        verify(refreshTokenRepository).findByToken(tokenString);
+    }
+
+    @Test
+    void testVerifyRefreshToken_Valid() {
+        // Arrange
+        String tokenString = "valid-token";
+        RefreshToken token = new RefreshToken(tokenString,
+                LocalDateTime.now().plusDays(14), "lib-1", "UA", "127.0.0.1");
+
+        when(refreshTokenRepository.findByToken(tokenString)).thenReturn(Optional.of(token));
+
+        // Act
+        Optional<RefreshToken> result = refreshTokenService.verifyRefreshToken(tokenString);
+
+        // Assert
+        assertTrue(result.isPresent());
+        assertTrue(result.get().isValid());
+    }
+
+    @Test
+    void testVerifyRefreshToken_Expired() {
+        // Arrange
+        String tokenString = "expired-token";
+        RefreshToken token = new RefreshToken(tokenString,
+                LocalDateTime.now().minusDays(1), "lib-1", "UA", "127.0.0.1"); // Expired
+
+        when(refreshTokenRepository.findByToken(tokenString)).thenReturn(Optional.of(token));
+
+        // Act
+        Optional<RefreshToken> result = refreshTokenService.verifyRefreshToken(tokenString);
+
+        // Assert
+        assertFalse(result.isPresent()); // Expired tokens should be filtered out
+    }
+
+    @Test
+    void testVerifyRefreshToken_Revoked() {
+        // Arrange
+        String tokenString = "revoked-token";
+        RefreshToken token = new RefreshToken(tokenString,
+                LocalDateTime.now().plusDays(14), "lib-1", "UA", "127.0.0.1");
+        token.setRevokedAt(LocalDateTime.now()); // Revoked
+
+        when(refreshTokenRepository.findByToken(tokenString)).thenReturn(Optional.of(token));
+
+        // Act
+        Optional<RefreshToken> result = refreshTokenService.verifyRefreshToken(tokenString);
+
+        // Assert
+        assertFalse(result.isPresent()); // Revoked tokens should be filtered out
+    }
+
+    @Test
+    void testRevokeToken() {
+        // Arrange
+        RefreshToken token = new RefreshToken("token",
+                LocalDateTime.now().plusDays(14), "lib-1", "UA", "127.0.0.1");
+
+        when(refreshTokenRepository.save(any(RefreshToken.class))).thenReturn(token);
+
+        // Act
+        refreshTokenService.revokeToken(token);
+
+        // Assert
+        assertNotNull(token.getRevokedAt());
+        assertTrue(token.isRevoked());
+
+        verify(refreshTokenRepository).save(token);
+    }
+
+    @Test
+    void testRevokeAllByLibraryId() {
+        // Arrange
+        String libraryId = "library-123";
+
+        // Act
+        refreshTokenService.revokeAllByLibraryId(libraryId);
+
+        // Assert
+        verify(refreshTokenRepository).revokeAllByLibraryId(eq(libraryId), any(LocalDateTime.class));
+    }
+
+    @Test
+    void testRevokeAll() {
+        // Act
+        refreshTokenService.revokeAll();
+
+        // Assert
+        verify(refreshTokenRepository).revokeAll(any(LocalDateTime.class));
+    }
+
+    @Test
+    void testCleanupExpiredTokens() {
+        // Act
+        refreshTokenService.cleanupExpiredTokens();
+
+        // Assert
+        verify(refreshTokenRepository).deleteExpiredTokens(any(LocalDateTime.class));
+    }
+}

backend/src/test/java/com/storycove/service/StoryServiceTest.java

@@ -85,7 +85,8 @@ class StoryServiceTest {
         Story result = storyService.updateReadingProgress(testId, position);
 
         assertEquals(0, result.getReadingPosition());
-        assertNotNull(result.getLastReadAt());
+        // When position is 0, lastReadAt should be reset to null so the story doesn't appear in "last read" sorting
+        assertNull(result.getLastReadAt());
         verify(storyRepository).save(testStory);
     }
 
@@ -111,7 +112,8 @@ class StoryServiceTest {
         Story result = storyService.updateReadingProgress(testId, position);
 
         assertNull(result.getReadingPosition());
-        assertNotNull(result.getLastReadAt());
+        // When position is null, lastReadAt should be reset to null so the story doesn't appear in "last read" sorting
+        assertNull(result.getLastReadAt());
         verify(storyRepository).save(testStory);
     }
 

backend/src/test/java/com/storycove/service/TagServiceTest.java

@@ -0,0 +1,490 @@
+package com.storycove.service;
+
+import com.storycove.entity.Story;
+import com.storycove.entity.Tag;
+import com.storycove.entity.TagAlias;
+import com.storycove.repository.TagAliasRepository;
+import com.storycove.repository.TagRepository;
+import com.storycove.service.exception.DuplicateResourceException;
+import com.storycove.service.exception.ResourceNotFoundException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+@ExtendWith(MockitoExtension.class)
+class TagServiceTest {
+
+    @Mock
+    private TagRepository tagRepository;
+
+    @Mock
+    private TagAliasRepository tagAliasRepository;
+
+    @InjectMocks
+    private TagService tagService;
+
+    private Tag testTag;
+    private UUID tagId;
+
+    @BeforeEach
+    void setUp() {
+        tagId = UUID.randomUUID();
+        testTag = new Tag();
+        testTag.setId(tagId);
+        testTag.setName("fantasy");
+        testTag.setStories(new HashSet<>());
+    }
+
+    // ========================================
+    // Basic CRUD Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should find tag by ID")
+    void testFindById() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+
+        Tag result = tagService.findById(tagId);
+
+        assertNotNull(result);
+        assertEquals(tagId, result.getId());
+        assertEquals("fantasy", result.getName());
+    }
+
+    @Test
+    @DisplayName("Should throw exception when tag not found by ID")
+    void testFindByIdNotFound() {
+        when(tagRepository.findById(any())).thenReturn(Optional.empty());
+
+        assertThrows(ResourceNotFoundException.class, () -> {
+            tagService.findById(UUID.randomUUID());
+        });
+    }
+
+    @Test
+    @DisplayName("Should find tag by name")
+    void testFindByName() {
+        when(tagRepository.findByName("fantasy")).thenReturn(Optional.of(testTag));
+
+        Tag result = tagService.findByName("fantasy");
+
+        assertNotNull(result);
+        assertEquals("fantasy", result.getName());
+    }
+
+    @Test
+    @DisplayName("Should create new tag")
+    void testCreateTag() {
+        when(tagRepository.existsByName("fantasy")).thenReturn(false);
+        when(tagRepository.save(any(Tag.class))).thenReturn(testTag);
+
+        Tag result = tagService.create(testTag);
+
+        assertNotNull(result);
+        verify(tagRepository).save(testTag);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when creating duplicate tag")
+    void testCreateDuplicateTag() {
+        when(tagRepository.existsByName("fantasy")).thenReturn(true);
+
+        assertThrows(DuplicateResourceException.class, () -> {
+            tagService.create(testTag);
+        });
+
+        verify(tagRepository, never()).save(any());
+    }
+
+    @Test
+    @DisplayName("Should update existing tag")
+    void testUpdateTag() {
+        Tag updates = new Tag();
+        updates.setName("sci-fi");
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagRepository.existsByName("sci-fi")).thenReturn(false);
+        when(tagRepository.save(any(Tag.class))).thenReturn(testTag);
+
+        Tag result = tagService.update(tagId, updates);
+
+        assertNotNull(result);
+        verify(tagRepository).save(testTag);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when updating to duplicate name")
+    void testUpdateToDuplicateName() {
+        Tag updates = new Tag();
+        updates.setName("sci-fi");
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagRepository.existsByName("sci-fi")).thenReturn(true);
+
+        assertThrows(DuplicateResourceException.class, () -> {
+            tagService.update(tagId, updates);
+        });
+    }
+
+    @Test
+    @DisplayName("Should delete unused tag")
+    void testDeleteUnusedTag() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        doNothing().when(tagRepository).delete(testTag);
+
+        tagService.delete(tagId);
+
+        verify(tagRepository).delete(testTag);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when deleting tag in use")
+    void testDeleteTagInUse() {
+        Story story = new Story();
+        testTag.getStories().add(story);
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+
+        assertThrows(IllegalStateException.class, () -> {
+            tagService.delete(tagId);
+        });
+
+        verify(tagRepository, never()).delete(any());
+    }
+
+    // ========================================
+    // Tag Alias Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should add alias to tag")
+    void testAddAlias() {
+        TagAlias alias = new TagAlias();
+        alias.setAliasName("sci-fantasy");
+        alias.setCanonicalTag(testTag);
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagAliasRepository.existsByAliasNameIgnoreCase("sci-fantasy")).thenReturn(false);
+        when(tagRepository.existsByNameIgnoreCase("sci-fantasy")).thenReturn(false);
+        when(tagAliasRepository.save(any(TagAlias.class))).thenReturn(alias);
+
+        TagAlias result = tagService.addAlias(tagId, "sci-fantasy");
+
+        assertNotNull(result);
+        assertEquals("sci-fantasy", result.getAliasName());
+        verify(tagAliasRepository).save(any(TagAlias.class));
+    }
+
+    @Test
+    @DisplayName("Should throw exception when alias already exists")
+    void testAddDuplicateAlias() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagAliasRepository.existsByAliasNameIgnoreCase("sci-fantasy")).thenReturn(true);
+
+        assertThrows(DuplicateResourceException.class, () -> {
+            tagService.addAlias(tagId, "sci-fantasy");
+        });
+
+        verify(tagAliasRepository, never()).save(any());
+    }
+
+    @Test
+    @DisplayName("Should throw exception when alias conflicts with tag name")
+    void testAddAliasConflictsWithTagName() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagAliasRepository.existsByAliasNameIgnoreCase("sci-fi")).thenReturn(false);
+        when(tagRepository.existsByNameIgnoreCase("sci-fi")).thenReturn(true);
+
+        assertThrows(DuplicateResourceException.class, () -> {
+            tagService.addAlias(tagId, "sci-fi");
+        });
+    }
+
+    @Test
+    @DisplayName("Should remove alias from tag")
+    void testRemoveAlias() {
+        UUID aliasId = UUID.randomUUID();
+        TagAlias alias = new TagAlias();
+        alias.setId(aliasId);
+        alias.setCanonicalTag(testTag);
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagAliasRepository.findById(aliasId)).thenReturn(Optional.of(alias));
+        doNothing().when(tagAliasRepository).delete(alias);
+
+        tagService.removeAlias(tagId, aliasId);
+
+        verify(tagAliasRepository).delete(alias);
+    }
+
+    @Test
+    @DisplayName("Should throw exception when removing alias from wrong tag")
+    void testRemoveAliasFromWrongTag() {
+        UUID aliasId = UUID.randomUUID();
+        Tag differentTag = new Tag();
+        differentTag.setId(UUID.randomUUID());
+
+        TagAlias alias = new TagAlias();
+        alias.setId(aliasId);
+        alias.setCanonicalTag(differentTag);
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagAliasRepository.findById(aliasId)).thenReturn(Optional.of(alias));
+
+        assertThrows(IllegalArgumentException.class, () -> {
+            tagService.removeAlias(tagId, aliasId);
+        });
+
+        verify(tagAliasRepository, never()).delete(any());
+    }
+
+    @Test
+    @DisplayName("Should resolve tag by name")
+    void testResolveTagByName() {
+        when(tagRepository.findByNameIgnoreCase("fantasy")).thenReturn(Optional.of(testTag));
+
+        Tag result = tagService.resolveTagByName("fantasy");
+
+        assertNotNull(result);
+        assertEquals("fantasy", result.getName());
+    }
+
+    @Test
+    @DisplayName("Should resolve tag by alias")
+    void testResolveTagByAlias() {
+        TagAlias alias = new TagAlias();
+        alias.setAliasName("sci-fantasy");
+        alias.setCanonicalTag(testTag);
+
+        when(tagRepository.findByNameIgnoreCase("sci-fantasy")).thenReturn(Optional.empty());
+        when(tagAliasRepository.findByAliasNameIgnoreCase("sci-fantasy")).thenReturn(Optional.of(alias));
+
+        Tag result = tagService.resolveTagByName("sci-fantasy");
+
+        assertNotNull(result);
+        assertEquals("fantasy", result.getName());
+    }
+
+    @Test
+    @DisplayName("Should return null when tag/alias not found")
+    void testResolveTagNotFound() {
+        when(tagRepository.findByNameIgnoreCase(anyString())).thenReturn(Optional.empty());
+        when(tagAliasRepository.findByAliasNameIgnoreCase(anyString())).thenReturn(Optional.empty());
+
+        Tag result = tagService.resolveTagByName("nonexistent");
+
+        assertNull(result);
+    }
+
+    // ========================================
+    // Tag Merge Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should merge tags successfully")
+    void testMergeTags() {
+        UUID sourceId = UUID.randomUUID();
+        Tag sourceTag = new Tag();
+        sourceTag.setId(sourceId);
+        sourceTag.setName("sci-fi");
+
+        Story story = new Story();
+        story.setTags(new HashSet<>(Arrays.asList(sourceTag)));
+        sourceTag.setStories(new HashSet<>(Arrays.asList(story)));
+
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+        when(tagRepository.findById(sourceId)).thenReturn(Optional.of(sourceTag));
+        when(tagAliasRepository.save(any(TagAlias.class))).thenReturn(new TagAlias());
+        when(tagRepository.save(any(Tag.class))).thenReturn(testTag);
+        doNothing().when(tagRepository).delete(sourceTag);
+
+        Tag result = tagService.mergeTags(List.of(sourceId), tagId);
+
+        assertNotNull(result);
+        verify(tagAliasRepository).save(any(TagAlias.class));
+        verify(tagRepository).delete(sourceTag);
+    }
+
+    @Test
+    @DisplayName("Should not merge tag with itself")
+    void testMergeTagWithItself() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+
+        assertThrows(IllegalArgumentException.class, () -> {
+            tagService.mergeTags(List.of(tagId), tagId);
+        });
+    }
+
+    @Test
+    @DisplayName("Should throw exception when no valid source tags to merge")
+    void testMergeNoValidSourceTags() {
+        when(tagRepository.findById(tagId)).thenReturn(Optional.of(testTag));
+
+        assertThrows(IllegalArgumentException.class, () -> {
+            tagService.mergeTags(Collections.emptyList(), tagId);
+        });
+    }
+
+    // ========================================
+    // Search and Query Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should find all tags")
+    void testFindAll() {
+        when(tagRepository.findAll()).thenReturn(List.of(testTag));
+
+        List<Tag> result = tagService.findAll();
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+    }
+
+    @Test
+    @DisplayName("Should search tags by name")
+    void testSearchByName() {
+        when(tagRepository.findByNameContainingIgnoreCase("fan"))
+            .thenReturn(List.of(testTag));
+
+        List<Tag> result = tagService.searchByName("fan");
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+    }
+
+    @Test
+    @DisplayName("Should find used tags")
+    void testFindUsedTags() {
+        when(tagRepository.findUsedTags()).thenReturn(List.of(testTag));
+
+        List<Tag> result = tagService.findUsedTags();
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+    }
+
+    @Test
+    @DisplayName("Should find most used tags")
+    void testFindMostUsedTags() {
+        when(tagRepository.findMostUsedTags()).thenReturn(List.of(testTag));
+
+        List<Tag> result = tagService.findMostUsedTags();
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+    }
+
+    @Test
+    @DisplayName("Should find unused tags")
+    void testFindUnusedTags() {
+        when(tagRepository.findUnusedTags()).thenReturn(List.of(testTag));
+
+        List<Tag> result = tagService.findUnusedTags();
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+    }
+
+    @Test
+    @DisplayName("Should delete all unused tags")
+    void testDeleteUnusedTags() {
+        when(tagRepository.findUnusedTags()).thenReturn(List.of(testTag));
+        doNothing().when(tagRepository).deleteAll(anyList());
+
+        List<Tag> result = tagService.deleteUnusedTags();
+
+        assertNotNull(result);
+        assertEquals(1, result.size());
+        verify(tagRepository).deleteAll(anyList());
+    }
+
+    @Test
+    @DisplayName("Should find or create tag")
+    void testFindOrCreate() {
+        when(tagRepository.findByName("fantasy")).thenReturn(Optional.of(testTag));
+
+        Tag result = tagService.findOrCreate("fantasy");
+
+        assertNotNull(result);
+        assertEquals("fantasy", result.getName());
+        verify(tagRepository, never()).save(any());
+    }
+
+    @Test
+    @DisplayName("Should create tag when not found")
+    void testFindOrCreateNew() {
+        when(tagRepository.findByName("new-tag")).thenReturn(Optional.empty());
+        when(tagRepository.existsByName("new-tag")).thenReturn(false);
+        when(tagRepository.save(any(Tag.class))).thenReturn(testTag);
+
+        Tag result = tagService.findOrCreate("new-tag");
+
+        assertNotNull(result);
+        verify(tagRepository).save(any(Tag.class));
+    }
+
+    // ========================================
+    // Tag Suggestion Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should suggest tags based on content")
+    void testSuggestTags() {
+        when(tagRepository.findAll()).thenReturn(List.of(testTag));
+
+        var suggestions = tagService.suggestTags(
+            "Fantasy Adventure",
+            "A fantasy story about magic",
+            "Epic fantasy tale",
+            5
+        );
+
+        assertNotNull(suggestions);
+        assertFalse(suggestions.isEmpty());
+    }
+
+    @Test
+    @DisplayName("Should return empty suggestions for empty content")
+    void testSuggestTagsEmptyContent() {
+        when(tagRepository.findAll()).thenReturn(List.of(testTag));
+
+        var suggestions = tagService.suggestTags("", "", "", 5);
+
+        assertNotNull(suggestions);
+        assertTrue(suggestions.isEmpty());
+    }
+
+    // ========================================
+    // Statistics Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should count all tags")
+    void testCountAll() {
+        when(tagRepository.count()).thenReturn(10L);
+
+        long count = tagService.countAll();
+
+        assertEquals(10L, count);
+    }
+
+    @Test
+    @DisplayName("Should count used tags")
+    void testCountUsedTags() {
+        when(tagRepository.countUsedTags()).thenReturn(5L);
+
+        long count = tagService.countUsedTags();
+
+        assertEquals(5L, count);
+    }
+}

backend/src/test/java/com/storycove/service/ZIPImportServiceTest.java

@@ -0,0 +1,310 @@
+package com.storycove.service;
+
+import com.storycove.dto.*;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.InjectMocks;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.mock.web.MockMultipartFile;
+
+import java.util.*;
+
+import static org.junit.jupiter.api.Assertions.*;
+import static org.mockito.ArgumentMatchers.*;
+import static org.mockito.Mockito.*;
+
+/**
+ * Tests for ZIPImportService.
+ */
+@ExtendWith(MockitoExtension.class)
+class ZIPImportServiceTest {
+
+    @Mock
+    private EPUBImportService epubImportService;
+
+    @Mock
+    private PDFImportService pdfImportService;
+
+    @InjectMocks
+    private ZIPImportService zipImportService;
+
+    private ZIPImportRequest testImportRequest;
+
+    @BeforeEach
+    void setUp() {
+        testImportRequest = new ZIPImportRequest();
+    }
+
+    // ========================================
+    // File Validation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should reject null ZIP file")
+    void testNullZIPFile() {
+        // Act
+        ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(null);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("ZIP file is required", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should reject empty ZIP file")
+    void testEmptyZIPFile() {
+        // Arrange
+        MockMultipartFile emptyFile = new MockMultipartFile(
+            "file", "test.zip", "application/zip", new byte[0]
+        );
+
+        // Act
+        ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(emptyFile);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertEquals("ZIP file is required", response.getMessage());
+    }
+
+    @Test
+    @DisplayName("Should reject non-ZIP file")
+    void testInvalidFileType() {
+        // Arrange
+        MockMultipartFile invalidFile = new MockMultipartFile(
+            "file", "test.txt", "text/plain", "test content".getBytes()
+        );
+
+        // Act
+        ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(invalidFile);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("Invalid ZIP file format"));
+    }
+
+    @Test
+    @DisplayName("Should reject oversized ZIP file")
+    void testOversizedZIPFile() {
+        // Arrange
+        long fileSize = 1025L * 1024 * 1024; // 1025 MB (> 1GB limit)
+        MockMultipartFile largeFile = new MockMultipartFile(
+            "file", "test.zip", "application/zip", new byte[1000]
+        ) {
+            @Override
+            public long getSize() {
+                return fileSize;
+            }
+        };
+
+        // Act
+        ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(largeFile);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("exceeds"));
+        assertTrue(response.getMessage().contains("1024MB") || response.getMessage().contains("1GB"));
+    }
+
+    // ========================================
+    // Import Request Validation Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should reject import with invalid session ID")
+    void testInvalidSessionId() {
+        // Arrange
+        testImportRequest.setZipSessionId("invalid-session-id");
+        testImportRequest.setSelectedFiles(Arrays.asList("file1.epub"));
+
+        // Act
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("Invalid") || response.getMessage().contains("expired"));
+    }
+
+    @Test
+    @DisplayName("Should reject import with no selected files")
+    void testNoSelectedFiles() {
+        // Arrange
+        testImportRequest.setZipSessionId("some-session-id");
+        testImportRequest.setSelectedFiles(Collections.emptyList());
+
+        // Act
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("No files selected") || response.getMessage().contains("Invalid"));
+    }
+
+    @Test
+    @DisplayName("Should reject import with null selected files")
+    void testNullSelectedFiles() {
+        // Arrange
+        testImportRequest.setZipSessionId("some-session-id");
+        testImportRequest.setSelectedFiles(null);
+
+        // Act
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("No files selected") || response.getMessage().contains("Invalid"));
+    }
+
+    // ========================================
+    // ZIP Analysis Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should handle corrupted ZIP file gracefully")
+    void testCorruptedZIPFile() {
+        // Arrange
+        MockMultipartFile corruptedFile = new MockMultipartFile(
+            "file", "test.zip", "application/zip",
+            "PK\3\4corrupted data".getBytes()
+        );
+
+        // Act
+        ZIPAnalysisResponse response = zipImportService.analyzeZIPFile(corruptedFile);
+
+        // Assert
+        assertFalse(response.isSuccess());
+        assertNotNull(response.getMessage());
+    }
+
+    // ========================================
+    // Helper Method Tests
+    // ========================================
+
+    @Test
+    @DisplayName("Should accept default metadata in import request")
+    void testDefaultMetadata() {
+        // Arrange
+        testImportRequest.setZipSessionId("test-session");
+        testImportRequest.setSelectedFiles(Arrays.asList("file1.epub"));
+        testImportRequest.setDefaultAuthorName("Default Author");
+        testImportRequest.setDefaultTags(Arrays.asList("tag1", "tag2"));
+
+        // Act - will fail due to invalid session, but tests that metadata is accepted
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertNotNull(response);
+        assertFalse(response.isSuccess()); // Expected to fail due to invalid session
+    }
+
+    @Test
+    @DisplayName("Should accept per-file metadata in import request")
+    void testPerFileMetadata() {
+        // Arrange
+        Map<String, ZIPImportRequest.FileImportMetadata> fileMetadata = new HashMap<>();
+        ZIPImportRequest.FileImportMetadata metadata = new ZIPImportRequest.FileImportMetadata();
+        metadata.setAuthorName("Specific Author");
+        metadata.setTags(Arrays.asList("tag1"));
+        fileMetadata.put("file1.epub", metadata);
+
+        testImportRequest.setZipSessionId("test-session");
+        testImportRequest.setSelectedFiles(Arrays.asList("file1.epub"));
+        testImportRequest.setFileMetadata(fileMetadata);
+
+        // Act - will fail due to invalid session, but tests that metadata is accepted
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertNotNull(response);
+        assertFalse(response.isSuccess()); // Expected to fail due to invalid session
+    }
+
+    @Test
+    @DisplayName("Should accept createMissing flags")
+    void testCreateMissingFlags() {
+        // Arrange
+        testImportRequest.setZipSessionId("test-session");
+        testImportRequest.setSelectedFiles(Arrays.asList("file1.epub"));
+        testImportRequest.setCreateMissingAuthor(false);
+        testImportRequest.setCreateMissingSeries(false);
+        testImportRequest.setExtractImages(false);
+
+        // Act - will fail due to invalid session, but tests that flags are accepted
+        ZIPImportResponse response = zipImportService.importFromZIP(testImportRequest);
+
+        // Assert
+        assertNotNull(response);
+    }
+
+    // ========================================
+    // Response Object Tests
+    // ========================================
+
+    @Test
+    @DisplayName("ZIPImportResponse should calculate statistics correctly")
+    void testZIPImportResponseStatistics() {
+        // Arrange
+        List<FileImportResponse> results = new ArrayList<>();
+
+        FileImportResponse success1 = FileImportResponse.success(UUID.randomUUID(), "Story 1", "EPUB");
+        FileImportResponse success2 = FileImportResponse.success(UUID.randomUUID(), "Story 2", "PDF");
+        FileImportResponse failure = FileImportResponse.error("Import failed", "story3.epub");
+
+        results.add(success1);
+        results.add(success2);
+        results.add(failure);
+
+        // Act
+        ZIPImportResponse response = ZIPImportResponse.create(results);
+
+        // Assert
+        assertNotNull(response);
+        assertEquals(3, response.getTotalFiles());
+        assertEquals(2, response.getSuccessfulImports());
+        assertEquals(1, response.getFailedImports());
+        assertTrue(response.isSuccess()); // Partial success
+        assertTrue(response.getMessage().contains("2 imported"));
+    }
+
+    @Test
+    @DisplayName("ZIPImportResponse should handle all failures")
+    void testZIPImportResponseAllFailures() {
+        // Arrange
+        List<FileImportResponse> results = new ArrayList<>();
+        results.add(FileImportResponse.error("Error 1", "file1.epub"));
+        results.add(FileImportResponse.error("Error 2", "file2.pdf"));
+
+        // Act
+        ZIPImportResponse response = ZIPImportResponse.create(results);
+
+        // Assert
+        assertNotNull(response);
+        assertEquals(2, response.getTotalFiles());
+        assertEquals(0, response.getSuccessfulImports());
+        assertEquals(2, response.getFailedImports());
+        assertFalse(response.isSuccess());
+        assertTrue(response.getMessage().contains("failed"));
+    }
+
+    @Test
+    @DisplayName("ZIPImportResponse should handle all successes")
+    void testZIPImportResponseAllSuccesses() {
+        // Arrange
+        List<FileImportResponse> results = new ArrayList<>();
+        results.add(FileImportResponse.success(UUID.randomUUID(), "Story 1", "EPUB"));
+        results.add(FileImportResponse.success(UUID.randomUUID(), "Story 2", "PDF"));
+
+        // Act
+        ZIPImportResponse response = ZIPImportResponse.create(results);
+
+        // Assert
+        assertNotNull(response);
+        assertEquals(2, response.getTotalFiles());
+        assertEquals(2, response.getSuccessfulImports());
+        assertEquals(0, response.getFailedImports());
+        assertTrue(response.isSuccess());
+        assertTrue(response.getMessage().contains("All files imported successfully"));
+    }
+}

backend/src/test/resources/application-test.yml

@@ -19,11 +19,14 @@ storycove:
   auth:
     password: test-password
   search:
-    engine: opensearch
+    engine: solr
-  opensearch:
+  solr:
     host: localhost
-    port: 9200
+    port: 8983
     scheme: http
+    cores:
+      stories: storycove_stories
+      authors: storycove_authors
   images:
     storage-path: /tmp/test-images
 

deploy.sh

@@ -1,35 +1,91 @@
 #!/bin/bash
 
 # StoryCove Deployment Script
-# Usage: ./deploy.sh [environment]
+# This script handles deployment with automatic Solr volume cleanup
-# Environments: development, staging, production
 
 set -e
 
-ENVIRONMENT=${1:-development}
+echo "🚀 Starting StoryCove deployment..."
-ENV_FILE=".env.${ENVIRONMENT}"
 
-echo "Deploying StoryCove for ${ENVIRONMENT} environment..."
+# Colors for output
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m' # No Color
 
-# Check if environment file exists
+# Check if docker-compose is available
-if [ ! -f "$ENV_FILE" ]; then
+if ! command -v docker-compose &> /dev/null; then
-    echo "Error: Environment file $ENV_FILE not found."
+    echo -e "${RED}❌ docker-compose not found. Please install docker-compose first.${NC}"
-    echo "Available environments: development, staging, production"
     exit 1
 fi
 
-# Copy environment file to .env
+# Stop existing containers
-cp "$ENV_FILE" .env
+echo -e "${YELLOW}📦 Stopping existing containers...${NC}"
-echo "Using environment configuration from $ENV_FILE"
-
-# Build and start services
-echo "Building and starting Docker services..."
 docker-compose down
-docker-compose build --no-cache
-docker-compose up -d
 
-echo "Deployment complete!"
+# Remove Solr volume to force recreation with fresh cores
-echo "StoryCove is running at: $(grep STORYCOVE_PUBLIC_URL $ENV_FILE | cut -d'=' -f2)"
+echo -e "${YELLOW}🗑️  Removing Solr data volume...${NC}"
+docker volume rm storycove_solr_data 2>/dev/null || echo "Solr volume doesn't exist yet (first run)"
+
+# Build and start containers
+echo -e "${YELLOW}🏗️  Building and starting containers...${NC}"
+docker-compose up -d --build
+
+# Wait for services to be healthy
+echo -e "${YELLOW}⏳ Waiting for services to be healthy...${NC}"
+sleep 5
+
+# Check if backend is ready
+echo -e "${YELLOW}🔍 Checking backend health...${NC}"
+MAX_RETRIES=30
+RETRY_COUNT=0
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if docker-compose exec -T backend curl -f http://localhost:8080/api/health &>/dev/null; then
+        echo -e "${GREEN}✅ Backend is healthy${NC}"
+        break
+    fi
+    RETRY_COUNT=$((RETRY_COUNT+1))
+    echo "Waiting for backend... ($RETRY_COUNT/$MAX_RETRIES)"
+    sleep 2
+done
+
+if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
+    echo -e "${RED}❌ Backend failed to start${NC}"
+    docker-compose logs backend
+    exit 1
+fi
+
+# Apply database migrations
+echo -e "${YELLOW}🗄️  Applying database migrations...${NC}"
+docker-compose run --rm migrations
+echo -e "${GREEN}✅ Database migrations applied${NC}"
+
+# Check if Solr is ready
+echo -e "${YELLOW}🔍 Checking Solr health...${NC}"
+RETRY_COUNT=0
+while [ $RETRY_COUNT -lt $MAX_RETRIES ]; do
+    if docker-compose exec -T backend curl -f http://solr:8983/solr/admin/ping &>/dev/null; then
+        echo -e "${GREEN}✅ Solr is healthy${NC}"
+        break
+    fi
+    RETRY_COUNT=$((RETRY_COUNT+1))
+    echo "Waiting for Solr... ($RETRY_COUNT/$MAX_RETRIES)"
+    sleep 2
+done
+
+if [ $RETRY_COUNT -eq $MAX_RETRIES ]; then
+    echo -e "${RED}❌ Solr failed to start${NC}"
+    docker-compose logs solr
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Deployment complete!${NC}"
 echo ""
-echo "To view logs: docker-compose logs -f"
+echo "📊 Service status:"
-echo "To stop: docker-compose down"
+docker-compose ps
+echo ""
+echo "🌐 Application is available at http://localhost:6925"
+echo "🔧 Solr Admin UI is available at http://localhost:8983"
+echo ""
+echo "📝 Note: The application will automatically perform bulk reindexing on startup."
+echo "   Check backend logs with: docker-compose logs -f backend"