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

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.

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/ - MQTT message handling
src/main/java/de/assecutor/votianlt/repository/ - MongoDB data access

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

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.

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
photos, barcodes, signatures - Task completion data
users - Web interface users
app_user - Mobile app users
cargo_item - Job cargo/delivery items

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

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

Key Integration Points

When adding new task types:

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

When modifying job status flow:

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

MQTT message routing follows pattern: extract taskType from payload, route to appropriate processor method in MessageController.

3.4 KiB Raw Blame History