aimailassistant/CLAUDE.md

AI TOOL GUIDANCE

This file provides guidance when working with code in this repository.

Technology Stack

This is a Vaadin application built with:

• Java
• Spring Boot
• Spring Data JPA with H2 database
• Maven build system

Development Commands

Running the Application

./mvnw                           # Start in development mode (default goal: spring-boot:run)
./mvnw spring-boot:run           # Explicit development mode

The application will be available at http://localhost:8080

Building for Production

./mvnw -Pproduction package      # Build production JAR
docker build -t my-application:latest .  # Build Docker image

Testing

./mvnw test                      # Run all tests
./mvnw test -Dtest=TaskServiceTest  # Run a single test class
./mvnw test -Dtest=TaskServiceTest#tasks_are_stored_in_the_database_with_the_current_timestamp  # Run a single test method

Architecture

This project follows a feature-based package structure rather than traditional layered architecture. Code is organized by functional units (features), not by technical layers.

Package Structure

• de.assecutor.aimailassistant.base: Reusable components and base classes for all features

  • base.ui.MainLayout: AppLayout with drawer navigation using SideNav, automatically populated from @Menu annotations
  • base.ui.component.ViewToolbar: Reusable toolbar component for views

• de.assecutor.aimailassistant.examplefeature: Example feature demonstrating the structure

  • Task.java: JPA entity with validation
  • TaskRepository.java: Spring Data JPA repository
  • TaskService.java: Service layer with @Transactional methods
  • ui.TaskListView.java: Vaadin Flow view component (server-side UI)
  • TaskServiceTest.java: Integration test using @SpringBootTest

• Application.java: Main entry point, annotated with @SpringBootApplication and @Theme("default")

Key Architecture Patterns

1. Feature Packages: Each feature is self-contained with its own UI, business logic, data access, and tests
2. Navigation: Views use @Route and @Menu annotations. MainLayout automatically builds navigation from menu entries
3. Service Layer: Use @Transactional for write operations and @Transactional(readOnly = true) for read operations
4. Validation: Domain validation in entity setters (see Task.setDescription)
5. Dependency Injection: Constructor injection throughout (no @Autowired on fields)

Adding New Features

When creating a new feature:

1. Create a new package under de.assecutor.aimailassistant (e.g., de.assecutor.aimailassistant.myfeature)
2. Include: Entity, Repository, Service, and UI view classes
3. Use the examplefeature package as a reference
4. Once your features are complete, delete the examplefeature package entirely

Vaadin-Specific Notes

• Server-side rendering: UI components are Java classes extending Vaadin components
• Grid lazy loading: Use VaadinSpringDataHelpers.toSpringPageRequest(query) for pagination
• Themes: Located in src/main/frontend/themes/default/, based on Lumo theme
• Routing: @Route("") for root path, @Route("path") for specific paths
• Menu: @Menu annotation controls navigation items (order, icon, title)

Database

• H2 in-memory database for development
• JPA entities use @GeneratedValue(strategy = GenerationType.SEQUENCE)
• Entity equality based on ID (see Task.equals/hashCode pattern)