Enhance README and documentation: Update application overview, features, and setup instructions; add detailed architecture and workflows; introduce future roadmap and technology stack.
This commit is contained in:
parent
a7771a769b
commit
6f8af22b62
48
README.md
48
README.md
|
|
@ -1,8 +1,11 @@
|
|||
# PhotoGallery
|
||||
|
||||
## PhotoGallery
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
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.
|
||||
|
|
@ -11,3 +14,44 @@ Features:
|
|||
- 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.
|
||||
## 🌟 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.
|
||||
|
|
|
|||
|
|
@ -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<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 |
|
||||
|
|
@ -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.
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 1.6 MiB |
Binary file not shown.
|
After Width: | Height: | Size: 1005 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 31 KiB |
|
|
@ -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
|
||||
Loading…
Reference in New Issue