Build a web app with the AI Unified Process

Review the Vision

The vision is the only artifact you write by hand. Everything else is generated from it.

For this tutorial the vision is already prepared at docs/vision.md — open it and read it before continuing. It is the source of truth for every step that follows. Keep it short — one page is plenty: the problem, the solution, the target users, the goals, and the non-goals.

Generate the Requirements Catalog

This skill reads docs/vision.md and produces a structured requirements catalog in docs/requirements.md, including:

• Functional requirements as user stories (As a member, I want to search the catalog so that I can find a book quickly).
• Non-functional requirements (performance, usability, maintainability).
• Constraints (the tech stack from the README, the non-goals from the vision, ...).

Review the catalog before continuing — this is your last chance to course-correct cheaply. Every later step compounds on this list.

Build the Entity Model

From the requirements the skill identifies the domain entities and produces a Mermaid ER diagram in docs/architecture/entity-model.md, including entities and attributes with types, relationships and cardinalities, and validation rules (required fields, lengths, uniqueness).

For the Book Library you should expect roughly:

• Book (id, title, author, isbn, copies)
• Member (id, user_id, name, email) — a library patron, linked 1:1 to an existing app_user row.
• Loan (id, book_id, member_id, borrowed_at, returned_at)

The AppUser entity (id, username, password_hash, role) is part of the starter and does not need to appear in the entity model — treat it as an external boundary.

Draw the Use Case Diagram

The skill renders a PlantUML use case diagram from the requirements at docs/architecture/use-case-diagram.puml. It shows the two actors (Member, Librarian) and the use cases they participate in:

Use the diagram to confirm coverage: every requirement should land on at least one use case, and every use case should trace back to a requirement.

Write the First Use Case Specification

Pick the use case that unblocks the others to go first. For the Book Library that is UC-001 Search catalog — it has no preconditions, gives the member something to do the moment they land on the page, and produces the data structures that UC-002 needs.

The skill writes docs/use_cases/UC-001-search-catalog.md with actors and stakeholders, preconditions and postconditions, the main success flow as numbered steps, alternative flows, and acceptance criteria.

Generate the Flyway Migration

The skill reads the entity model and the use case spec and emits a versioned Flyway script under src/main/resources/db/migration/. The starter already contains V001__create_app_user.sql, so the skill produces a new version (e.g. V002__create_member_book_loan.sql) for the missing tables, including:

• CREATE TABLE statements for member, book, and loan
• Primary and foreign keys including member.user_id → app_user.id
• NOT NULL constraints driven by the validation rules in the entity model
• Useful indexes e.g. on loan.book_id and loan.member_id
• Seed data linking the seeded alice user to a freshly inserted member row

Run ./mvnw compile once after this step — it will start a Testcontainers Postgres, apply the migration, and regenerate the jOOQ metamodel so the next step has typed references to your new tables.

Implement the Use Case

This is where the chain pays off. The skill reads the use case spec, the entity model, and the generated jOOQ classes, and produces:

• A jOOQ-based repository (BookRepository) in the domain package
• A service layer if the flow needs business logic
• A Vaadin view (SearchCatalogView) in the ui package, wired to MainLayout
• DTOs / records for the data passed between layers

Run the app via TestApplication from your IDE and click through the flow. You should be able to type a query, see the Grid filter, and see the results sorted as the spec requires.

Write Browserless UI Tests

The skill creates a UI unit test under src/test/java/.../SearchCatalogViewTest.java that extends AbstractBrowserlessTest. It exercises the view without a browser by driving the Vaadin component tree directly: navigate to the view, look up the search field and the grid, type a query, assert the grid shows the expected rows, and cover the alternative flows from the spec.

Run it with ./mvnw test. These tests are fast — under a second per test — so they form the inner feedback loop while you iterate on the view.

Write the End-to-End Test

The final skill produces a Playwright + Mopo E2E test under src/test/java/.../SearchCatalogIT.java extending PlaywrightIT. It boots the full Spring Boot app on a random port and drives a real browser through the use case: start the app with a fresh database, open the catalog page, type a search query, and assert the visible rows match what the spec requires.

Run with ./mvnw verify to execute the integration tests. This is your outer feedback loop — slower than the browserless tests, but it proves that the JavaScript, CSS, routing, and database layers all line up.