104 lines
4.7 KiB
Markdown
104 lines
4.7 KiB
Markdown
# 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.
|