votianlt/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

• 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 a pluggable messaging transport layer. The system manages logistics jobs with tasks that mobile app users complete.

Core Architecture Layers

Frontend: Vaadin Flow views (server-side rendered)

• src/main/java/de/assecutor/votianlt/pages/view/ - Main UI views
• src/main/java/de/assecutor/votianlt/pages/base/ui/ - Shared UI components

Backend Services:

• src/main/java/de/assecutor/votianlt/service/ - Business logic
• 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.)

Key Architectural Patterns

Job-Task Relationship: Jobs contain multiple ordered tasks. Tasks have completion states and can store completion data (photos, barcodes, signatures).

User Hierarchy:

• User - Web interface users (job managers)
• AppUser - Mobile app users (task executors)
• AppUser.owner field links to User for notifications

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.

Email Notifications: EmailService sends notifications for job creation, task completion, and job completion using Spring Mail with SMTP.

Data Storage

MongoDB Collections:

• 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
• cargo_item - Job cargo/delivery items

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

When adding new task types:

1. Extend BaseTask and add to @JsonSubTypes
2. Add completion logic in MessageController.handleTaskCompleted()
3. Update JobHistoryView for task-specific previews if needed

When modifying job status flow:

1. Update JobStatus enum
2. Modify EmailService.updateJobStatusToCompleted() logic
3. Consider email notification templates

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.