diff --git a/README.md b/README.md index 7f581ea..bb87dfb 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # PhotoGallery -## PhotoGallery +![Java](https://img.shields.io/badge/Java-17%2B-orange) +![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.x-green) +![Bootstrap](https://img.shields.io/badge/Bootstrap-5-purple) +![License](https://img.shields.io/badge/License-MIT-blue) -A responsive and dynamic photo gallery web application built with Spring Boot and Thymeleaf, featuring a modern masonry-style layout for images of varying sizes. This application is optimized for performance and usability, providing a smooth experience on both desktop and mobile devices. +**PhotoGallery** is a responsive and dynamic web application built with Spring Boot and Thymeleaf. It features a modern masonry-style layout for organizing images of varying sizes, optimized for performance and usability across desktop and mobile devices. Features: - Masonry Grid Layout: Automatically arranges images of different sizes in an aesthetically pleasing masonry-style grid. @@ -10,4 +13,45 @@ Features: - Fullscreen Modal Viewer: Click an image to view it in fullscreen with previous/next navigation. - Responsive Design: Fully mobile-friendly using Bootstrap 5. - Dynamic Image Loading: Supports adding new images dynamically from the backend without changing frontend code. - - Hover Effects: Smooth zoom and shadow effects for a modern look. \ No newline at end of file + - Hover Effects: Smooth zoom and shadow effects for a modern look. +## ๐ŸŒŸ Features + +\ No newline at end of file +- **Masonry Grid Layout**: Automatically arranges images of different aspect ratios in an aesthetically pleasing grid. +- **Lazy Loading**: Images load asynchronously as you scroll, ensuring fast initial page loads. +- **Smart Ingestion**: Scans local directories to automatically compress images, generate thumbnails, and extract metadata (EXIF). +- **Fullscreen Viewer**: Immersive modal viewer with navigation controls. +- **Search & Filter**: Search photos by title or tags. +- **Metadata Extraction**: Automatically extracts and displays camera details, resolution, and file size. +- **Responsive Design**: Built with Bootstrap 5 for a seamless mobile experience. + +## ๐Ÿš€ Getting Started + +### Prerequisites +- Java 17 or higher +- Maven (wrapper included) + +### Configuration +Configure your image paths in `src/main/resources/application.properties`: + +```properties +photogallery.paths.originals=/path/to/your/images +photogallery.paths.thumbnails=/path/to/your/thumbnails +``` + +### Running the Application + +Use the included Maven wrapper to run the application: + +```bash +# Linux/macOS +./mvnw spring-boot:run + +# Windows +mvnw.cmd spring-boot:run +``` + +Access the gallery at `http://localhost:8080`. + +## ๐Ÿ“š Documentation +See documentation.md for architectural details and stack.md for the technology stack. diff --git a/documenation.md b/documenation.md new file mode 100644 index 0000000..e69de29 diff --git a/documentation.md b/documentation.md new file mode 100644 index 0000000..8e5bc13 --- /dev/null +++ b/documentation.md @@ -0,0 +1,63 @@ +# ๐Ÿ“– 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` 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 | \ No newline at end of file diff --git a/future.md b/future.md new file mode 100644 index 0000000..8aedb93 --- /dev/null +++ b/future.md @@ -0,0 +1,35 @@ +# ๐Ÿ”ฎ Future Roadmap + +## ๐Ÿšง Technical Debt & Improvements + +### Error Handling +- **Ingestion Robustness**: Currently, `DataIntegrityViolationException` is ignored during scanning. A more detailed logging or reporting mechanism for skipped files would be beneficial. +- **Path Handling**: Move away from string concatenation for paths (e.g., `"images" + "/" + ...`) to `java.nio.Path` resolution to ensure cross-platform compatibility (Windows vs Linux separators). + +### Performance +- **Caching**: Implement Spring Cache for `getPagedPhotos` and `getRandomPhotos` to reduce database load. +- **Batch Processing**: The current scanning process saves photos one by one. Implementing `saveAll()` with batching would significantly speed up large library imports. + +## โœจ Planned Features + +### AI Integration +- **Auto-Tagging**: Re-enable and implement the `taggingService` (currently commented out in `PhotoService`) to automatically generate tags using a local ML model or cloud API. +- **Face Recognition**: Group photos by detected faces. + +### User Experience +- **Dark Mode**: Toggle between light and dark themes. +- **Multi-Select**: Allow selecting multiple photos for batch tagging or deleting. +- **EXIF Editing**: Allow users to manually update incorrect EXIF data via the UI. + +### Backend +- **Cloud Storage**: Add an abstraction layer to support S3 or Azure Blob Storage instead of just local file systems. +- **User Accounts**: Add Spring Security to support multiple users with private galleries. + +## ๐Ÿงช Testing + +- **Unit Tests**: Add JUnit 5 tests for `PhotoService` logic. +- **Integration Tests**: Test the full ingestion flow with temporary directories. + +--- + +> **Note**: This document serves as a living roadmap. Priorities may change based on user feedback and technical requirements. \ No newline at end of file diff --git a/screenshots/homePage.png b/screenshots/homePage.png new file mode 100644 index 0000000..dff7330 Binary files /dev/null and b/screenshots/homePage.png differ diff --git a/screenshots/photoView.png b/screenshots/photoView.png new file mode 100644 index 0000000..44bdce7 Binary files /dev/null and b/screenshots/photoView.png differ diff --git a/screenshots/uploadPage.png b/screenshots/uploadPage.png new file mode 100644 index 0000000..c1fbae8 Binary files /dev/null and b/screenshots/uploadPage.png differ diff --git a/stack.md b/stack.md new file mode 100644 index 0000000..9f54cde --- /dev/null +++ b/stack.md @@ -0,0 +1,21 @@ +# ๐Ÿ› ๏ธ Technology Stack + +## Backend +- **Language**: Java +- **Framework**: Spring Boot (Web, Data JPA) +- **Template Engine**: Thymeleaf +- **JSON Processing**: JSON.simple +- **Concurrency**: Spring Async (`@Async`) + +## Frontend +- **Structure**: HTML5 +- **Styling**: CSS3, Bootstrap 5 +- **Scripting**: JavaScript (Vanilla) + +## Data & Storage +- **Database**: H2 (Dev) / MySQL (Prod) +- **ORM**: Hibernate (via Spring Data JPA) +- **File System**: `java.nio` for local file management + +## Build & DevOps +- **Build Tool**: Maven \ No newline at end of file