Enhance README and documentation: Update application overview, features, and setup instructions; add detailed architecture and workflows; introduce future roadmap and technology stack.

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.
+    - 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.

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<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 |

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.

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