# 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
```bash
./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
```bash
./mvnw -Pproduction package      # Build production JAR
docker build -t my-application:latest .  # Build Docker image
```

### Testing
```bash
./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)