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

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