zk-architecture-evolution - SKILL.md Agent Skill

name: zk-architecture-evolution description: >- Explains the historical evolution of ZK framework architectures, from legacy Java 6/MVC to modern Java 17/Spring Boot/MVVM. This skill provides a mental model for classifying and understanding ZK projects. Use when: analyzing an unfamiliar ZK codebase, planning a modernization effort, or comparing different ZK application architectures.

Skill: Understanding ZK Application Architecture Evolution

This skill provides a framework for analyzing and classifying Java applications built with the ZK framework. It outlines three distinct "eras" of development, helping you understand the trade-offs and modernization path for a given ZK project.

The Three Eras of ZK Architecture

The evolution of ZK applications can be categorized into three main levels, primarily driven by the adoption of Java language features, the Spring Framework, and the shift to the Jakarta EE namespace.

Level 1: The Legacy Era (circa Java 6-8, ZK 3-8, No Spring)

This represents the classic, manual approach to building ZK applications.

Key Identifiers:

Java Version: 6, 7, or 8.
UI Pattern: Primarily Model-View-Controller (MVC) using GenericForwardComposer.
Configuration: Heavy reliance on XML files (web.xml, persistence.xml, hibernate.cfg.xml).
Persistence: Manual DAO (Data Access Object) pattern with explicit EntityManager or Hibernate Session management. Transaction management is manual (tx.begin(), tx.commit()).
Dependencies: Managed manually in pom.xml without a parent like Spring Boot.
Namespace: javax.* (Java EE).

Characteristics:

High Boilerplate: Significant code is required for configuration, persistence, and UI logic.
High Coupling: The UI logic in Composers is often tightly coupled to the view components.
Difficult Testing: ViewModels are not easily separable for unit testing.

Level 2: The Transitional Era (circa Java 8-11, ZK 8-9, Spring Introduction)

This era marks the adoption of modern patterns and frameworks that significantly improve developer productivity.

Key Identifiers:

Java Version: 8 or 11.
UI Pattern: Model-View-ViewModel (MVVM) becomes dominant, using ZK's @bind annotations and BindComposer.
Configuration: Spring Framework is introduced, reducing XML in favor of Java-based configuration (@Configuration) or early Spring Boot (application.properties).
Persistence: Spring ORM (@Transactional) eliminates manual transaction management. Spring Data may be introduced, but some manual DAOs might still exist.
Namespace: This is a critical transition period. Projects might use javax.* (with Spring Boot 2) or jakarta.* (with Spring Boot 3 and ZK's -jakarta artifacts). A mix of both is a common source of errors.

Characteristics:

Reduced Boilerplate: Spring's DI and autoconfiguration handle much of the setup.
Improved Testability: MVVM allows ViewModels to be tested as simple POJOs, separate from the UI.
Declarative UI: The ZUL files become more declarative, with logic moving to the ViewModel.

Level 3: The Modern Era (circa Java 17+, ZK 9-10+, Spring Boot 3)

This represents the current state-of-the-art for building robust, enterprise-grade ZK applications.

Key Identifiers:

Java Version: 17 or higher.
UI Pattern: Exclusively MVVM.
Configuration: Convention-over-configuration via Spring Boot 3. Configuration is centralized in application.yml.
Persistence: Dominated by Spring Data JPA interfaces (JpaRepository), virtually eliminating all DAO implementation boilerplate.
Namespace: Exclusively jakarta.*.
Advanced Patterns: Often includes modern security (like JWT for APIs) and sophisticated design patterns (like Strategy for services).

Characteristics:

Minimal Boilerplate: Developers focus almost entirely on business logic.
Low Coupling: Highly decoupled components thanks to DI and clear architectural layers.
High Productivity & Maintainability: Easy to develop, test, and maintain.

Analysis Workflow

To analyze a ZK project, follow these steps:

Check pom.xml:
- What are the java.version, zk.version, and spring-boot.version properties?
- Is spring-boot-starter-parent present?
- Does the ZK dependency artifact ID include -jakarta?
Inspect a ZUL file:
- Does it use apply="...YourComposer" (MVC)?
- Or does it use viewModel="@id('vm') @init('...YourViewModel')" (MVVM)?
Examine the Persistence Layer:
- Do you see manual EntityManager usage and persistence.xml? (Level 1)
- Do you see @Transactional on service methods but still some DAO-like classes? (Level 2)
- Do you see only interface ... extends JpaRepository? (Level 3)
Check Imports:
- Are the imports javax.servlet.*, javax.persistence.*? (Level 1/2)
- Or are they jakarta.servlet.*, jakarta.persistence.*? (Level 2/3)

By answering these questions, you can accurately place the project in one of the three eras and understand its architectural context.

Examples

Example: Identifying a Level 1 Project

pom.xml shows <java.version>1.6</java.version> and <zk.version>3.6.2</zk.version>. No Spring Boot parent.
login.zul has <window apply="com.example.LoginComposer">.
A UsuarioDAO.java class manually creates Session and Transaction objects.
persistence.xml exists in src/main/resources/META-INF.

Conclusion: This is a classic Level 1 application. Expect manual configuration and high boilerplate.

Example: Identifying a Level 3 Project

pom.xml shows <java.version>17</java.version> and <spring-boot.version>3.2.0</spring-boot.version>.
home.zul has <window viewModel="@id('vm') @init('com.example.HomeViewModel')">.
The data layer consists only of interfaces like public interface UserRepository extends JpaRepository<User, Long>.
All servlet/persistence imports use jakarta.*.

Conclusion: This is a modern Level 3 application. Expect high productivity and convention-over-configuration.

References

Source Material: zk-min-samples repository, specifically GUIA_COMPLETO_DA_EVOLUCAO.md.
ZK Framework Official Website: https://www.zkoss.org/
Spring Boot Official Website: https://spring.io/projects/spring-boot
Jakarta EE Official Website: https://jakarta.ee/