2FATest/AGENTS.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A Spring Boot + Vaadin Flow project (Vaadin 25, Spring Boot 4, Java 25). UI is built entirely in server-side Java — no HTML/JS/TypeScript to write for views. Data layer is Spring Data JPA over H2 (file/in-memory, dev only).

Commands

./mvnw spring-boot:run      # run the app (dev), http://localhost:8080
./mvnw test                 # run all tests
./mvnw test -Dtest=TaskServiceTest                       # single test class
./mvnw test -Dtest=TaskServiceTest#tasks_are_validated_before_they_are_stored  # single test method
./mvnw package               # production build -> target/*.jar
java -jar target/*.jar       # run the built jar

No system Maven is required; always use the ./mvnw wrapper. There is no separate lint command configured.

Live hotswap (edit Java, see changes without restart) requires launching via the Vaadin IDE plugin (IntelliJ/VS Code/Eclipse) instead of spring-boot:run — not available from the CLI.

Port defaults to 8080 (override via server.port in src/main/resources/application.properties or the PORT env var).

Architecture

Feature-package structure: code is organized by feature/domain under com.example.<feature>, not by technical layer. Each feature package is self-contained: entity, repository, service, and a ui sub-package for its views. com.example.examplefeature is the template feature to copy/replace — its package-info.java has a TODO Remove this package once you have added real features.

Package visibility convention: types are package-private by default (e.g. TaskRepository, TaskService, TaskListView are not public). Only export a type outside its feature package when another package actually needs it. Follow this pattern for new features.

Null-safety: packages are annotated @NullMarked (JSpecify) in their package-info.java, so all types are non-null by default; use @Nullable explicitly where null is allowed (e.g. Task.dueDate). Apply @NullMarked to any new feature package.

Layout/routing: MainLayout (com.example.base.ui, annotated @Layout) is the shared AppLayout shell (drawer nav + header/footer) applied automatically to routed views. Side-nav entries are auto-discovered via @Menu on @Route view classes (see TaskListView) — no manual registration needed. ViewTitle is a shared composite for the per-view title bar (drawer toggle + heading).

Data access pattern: Slice<T> (via findAllBy(Pageable)) is preferred over Page<T> for grid data providers, since Slice avoids the extra COUNT query — see the comment in TaskRepository. Vaadin Grid is wired to Spring Data via VaadinSpringDataHelpers.toSpringPageRequest(query) in an in-memory/lazy DataProvider callback (see TaskListView).

Entities: JPA entities use @GeneratedValue(strategy = GenerationType.SEQUENCE), expose validation in setters (throwing IllegalArgumentException) rather than via bean-validation annotations, and implement equals/hashCode based on ID only (with a fixed hashCode, per the pattern in Task).

Schema management: spring.jpa.hibernate.ddl-auto=update is used for local dev convenience only. This is explicitly not appropriate for production — the app is meant to move to Flyway (or similar) for real schema migrations before shipping.

Frontend theming: Application sets the app-shell config (@Push, Aura theme via @StyleSheet(Aura.STYLESHEET), plus custom styles.css/view-title.css/solstice.css under src/main/resources/META-INF/resources/). No separate frontend build step is needed for typical UI work since Flow generates the client bundle; the vaadin-maven-plugin build-frontend goal runs as part of the Maven build.

Custom theme ("Solstice") and dark/light mode: solstice.css overrides Aura's -light/-dark suffixed design tokens (e.g. --aura-accent-color-light/-dark, --aura-background-color-light/-dark) rather than the unsuffixed ones — those are read-only, computed via the native CSS light-dark() function from the pair. Everything else should keep consuming the unsuffixed tokens (--aura-accent-color, --vaadin-text-color, ...) so it follows whichever scheme is active automatically. Switching schemes at runtime uses the Vaadin 25 ColorScheme API (Application declares @ColorScheme(ColorScheme.Value.SYSTEM) as the default; Page#setColorScheme(...) changes it at runtime) — do not use the older Lumo-only setAttribute("theme", ...) pattern. The feature lives in com.example.base.ui: ThemePreference (session-scoped) holds the current choice and applies it; ThemeToggle is the header button; ThemeInitializer restores the choice from a cookie (ThemeCookie) on every request/UI-init, both for a flash-free reload and to seed a fresh session, since a plain @ColorScheme annotation can't read per-visitor state on its own.

Testing

Two distinct test styles are used:

• Service/integration tests (TaskServiceTest): @SpringBootTest(webEnvironment = MOCK) + @Transactional (each test rolls back), asserting against the JPA layer directly.
• UI/browserless tests (TaskListViewTest): extend SpringBrowserlessTest (from com.vaadin:browserless-test-spring), which renders and interacts with actual Vaadin components server-side without a real browser. Use navigate(ViewClass.class), test(component) for interactions/assertions, and $(ComponentClass.class) for component lookup queries. Views expose package-private fields (e.g. taskGrid, description, createBtn) specifically so tests in the same package can drive them directly.

MCP

.mcp.json configures a Vaadin docs MCP server (https://mcp.vaadin.com/docs) and a Playwright MCP server — both available for querying live Vaadin component/API docs and browser automation if needed.