84 lines
3.4 KiB
Markdown
84 lines
3.4 KiB
Markdown
# 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)
|