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 + Drama Finder E2E test under src/test/java/.../SearchCatalogIT.java extending AbstractBasePlaywrightIT. 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.