# 📖 Application Documentation

## Architecture Overview

The application follows a standard **Model-View-Controller (MVC)** architecture powered by Spring Boot.

### Core Components

#### 1. Controllers (`com.example.PhotoGallery.Controller`)
- **`PhotoHomeController`**: Manages the main gallery view, infinite scrolling pagination, and search functionality.
- **`PhotoViewController`**: Handles individual photo details, editing metadata, tagging, and favoriting.

#### 2. Services (`com.example.PhotoGallery.Services`)
- **`PhotoService`**: The central business logic unit.
  - **Scanning**: Iterates through the configured directory.
  - **Compression**: Generates thumbnails for UI performance.
  - **Database Sync**: Writes metadata to the DB, handling duplicates via `DataIntegrityViolationException`.
- **`ExtractImageMetadata`**: Parses EXIF data (Camera model, ISO, Aperture, etc.) from raw images.
- **`ImageCompression`**: Handles the resizing logic for thumbnails.

#### 3. Data Access (`com.example.PhotoGallery.Repos`)
- **`PhotoRepo`**: Spring Data JPA repository for CRUD operations and custom queries (e.g., `findAllExpect`, `getRandomPhotos`).

---

## 🔄 Key Workflows

### Image Ingestion Process
The ingestion process is triggered via the `/scanLibrary` endpoint and runs asynchronously to prevent blocking the UI.

1. **Trigger**: User clicks "Scan Library" or API call to `/scanLibrary`.
2. **Coordination**: `ImageIngestionCoordinator` ensures the task isn't already running.
3. **Execution** (`PhotoService.writeImagesFromDirToDB`):
   - Lists all files in `originalFilesPath`.
   - Checks if the file already exists in the DB.
   - **If New**:
     1. Compresses image to `thumbnailsPath`.
     2. Extracts metadata (Resolution, MIME type, EXIF).
     3. Saves `Photo` entity to the database.

### Infinite Scroll
The home page uses a "Load More" mechanism:
1. The frontend tracks the current page number.
2. When scrolling near the bottom, a request is sent to `/loadMoreImages`.
3. `PhotoHomeController` fetches the next `Page<Photo>` and returns a Thymeleaf fragment (`home :: images`).
4. The fragment is appended to the DOM.

---

## 🗄️ Database Schema (Photo Entity)

| Field | Description |
|-------|-------------|
| `id` | Primary Key |
| `filePath` | Relative path to the original image |
| `thumbnailPath` | Relative path to the compressed thumbnail |
| `title` | Display title (defaults to filename) |
| `tags` | List of string tags |
| `favourite` | Boolean flag for favorites |
| `height/width` | Image dimensions |
| `file_size` | Size in MB |
| `mimeType` | e.g., image/jpeg |
| `copyRight` | EXIF copyright data |