mongodb viewer

CLAUDE.md

@@ -7,10 +7,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - **Start development server**: `./mvnw` (runs Spring Boot with Vaadin dev mode)
 - **Build for production**: `./mvnw -Pproduction package`
 - **Clean build**: `./mvnw clean compile`
+- **Format code**: `./mvnw spotless:apply` (applies Eclipse formatter for Java, Prettier for TypeScript)
+- **Check formatting**: `./mvnw spotless:check`
 
 ## Architecture Overview
 
-This is a **Vaadin Spring Boot** application for job/task management with real-time mobile app communication via MQTT. The system manages logistics jobs with tasks that mobile app users complete.
+This is a **Vaadin Spring Boot** application for job/task management with real-time mobile app communication via a pluggable messaging transport layer. The system manages logistics jobs with tasks that mobile app users complete.
 
 ### Core Architecture Layers
 
@@ -20,9 +22,15 @@ This is a **Vaadin Spring Boot** application for job/task management with real-t
 
 **Backend Services**:
 - `src/main/java/de/assecutor/votianlt/service/` - Business logic
-- `src/main/java/de/assecutor/votianlt/controller/` - MQTT message handling
+- `src/main/java/de/assecutor/votianlt/controller/` - Message handling (routes inbound messages to processors)
 - `src/main/java/de/assecutor/votianlt/repository/` - MongoDB data access
 
+**Messaging Layer** (`src/main/java/de/assecutor/votianlt/messaging/`):
+- `plugin/` - Transport plugin interface and implementations (MQTT, extensible for WebSocket, gRPC)
+- `delivery/` - Reliable message delivery with acknowledgment tracking, retries, and expiry
+- `model/` - Message envelopes, delivery status, pending deliveries
+- `config/` - Messaging configuration and wiring
+
 **Models**:
 - `src/main/java/de/assecutor/votianlt/model/` - Domain entities
 - Task hierarchy: `BaseTask` with subtypes (`PhotoTask`, `BarcodeTask`, `SignatureTask`, etc.)
@@ -36,10 +44,15 @@ This is a **Vaadin Spring Boot** application for job/task management with real-t
 - `AppUser` - Mobile app users (task executors)
 - `AppUser.owner` field links to `User` for notifications
 
-**MQTT Communication**:
-- `MqttV5ClientManager` handles bidirectional communication with mobile apps
-- `MessageController` routes inbound MQTT messages and processes task completions
-- Topics: `/server/{clientId}/task_completed`, `/server/login`, etc.
+**Messaging Plugin Architecture**:
+- `MessagingPlugin` interface abstracts transport protocols (currently MQTT via HiveMQ)
+- `MessageDeliveryService` provides guaranteed delivery with acknowledgment tracking
+- `AcknowledgmentHandler` processes ACKs and updates delivery status
+- Plugins are responsible for topic/channel structure; delivery layer uses `clientId` and `messageType`
+
+**Client Connection Monitoring**:
+- `ClientConnectionService` tracks connected mobile clients via ping/pong mechanism
+- Server sends ping to `/client/{clientId}/ping`, client responds on `/server/{clientId}/pong`
 
 **History Tracking**: `JobHistoryService` logs all job/task changes with detailed audit trail displayed in `JobHistoryView`.
 
@@ -51,6 +64,7 @@ This is a **Vaadin Spring Boot** application for job/task management with real-t
 - `jobs` - Main job entities with status tracking
 - `tasks` - Polymorphic task storage (discriminated by `taskType`)
 - `job_history` - Audit trail for all job changes
+- `pending_deliveries` - Message delivery tracking for retries
 - `photos`, `barcodes`, `signatures` - Task completion data
 - `users` - Web interface users
 - `app_user` - Mobile app users
@@ -58,15 +72,16 @@ This is a **Vaadin Spring Boot** application for job/task management with real-t
 
 ## Configuration
 
-**Database**: MongoDB at `192.168.180.25:27017/votianlt`
-**MQTT**: HiveMQ client connects to `mqtt-2.assecutor.de` with credentials `app`/`apppwd`
-**Email**: SMTP via `mailhub.assecutor.org:587` using Spring Boot mail auto-configuration
+**Database**: MongoDB (configurable via `spring.data.mongodb.uri`)
+**Messaging**: Plugin-based, currently MQTT via HiveMQ (`app.messaging.plugin.*` properties)
+**Email**: SMTP via Spring Boot mail auto-configuration
 
 ## Development Environment
 
 **Java 21** with **Spring Boot 3.4.3** and **Vaadin 24.7.0**
 **Security**: Spring Security with role-based access (`USER` role required)
-**Profiles**: `production` profile available for optimized builds
+**Formatting**: Spotless Maven plugin with Eclipse formatter (Java) and Prettier (TypeScript)
+**Profiles**: `production` profile for optimized builds, `integration-test` profile for failsafe plugin
 
 ## Key Integration Points
 
@@ -80,4 +95,9 @@ When modifying job status flow:
 2. Modify `EmailService.updateJobStatusToCompleted()` logic
 3. Consider email notification templates
 
-MQTT message routing follows pattern: extract `taskType` from payload, route to appropriate processor method in `MessageController`.
+When adding new messaging transports:
+1. Implement `MessagingPlugin` interface
+2. Register in `PluginMessagingConfig`
+3. Add configuration properties under `app.messaging.plugin.<type>.*`
+
+Message routing follows pattern: `MessageController` receives messages via `MessageDeliveryService`, extracts `taskType`/`messageType` from payload, routes to appropriate processor method.