63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# 📖 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 | |