PhotoGallery/documentation.md

📖 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