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