Kotlin/Spring framework for progressive entity-first application development with code generation, type-safe JPA search DSL, and model mapping capabilities.
A multi-module Kotlin framework for simplifying enterprise application development with code generation (KAPT and DSL-based), JPA enhancements with type-safe search DSL, web/REST utilities, and model mapping capabilities.
**Tech Stack**: Kotlin 1.8.22, Spring Boot 2.7.14, Gradle 7.x+ (Kotlin DSL), JUnit Platform, Kotest, MockK
```bash
./gradlew build
./gradlew test
./gradlew -p modules-core/zygarde-core test
./gradlew :samples:todo-legacy:bootRun
```
```bash
./gradlew ktlintFormat
./gradlew ktlintCheck
./gradlew detekt
```
```bash
./scripts/deps.sh
./gradlew test --tests "ClassName"
./gradlew kaptKotlin
```
```
zygarde/
├── modules-core/ # Core utilities (error-handling, DI, Jackson, JWT, mail, etc.)
├── modules-jpa/ # JPA extensions, DAOs, search DSL, Envers support
├── modules-web/ # Web/REST utilities (WebMVC, WebFlux, security)
├── modules-model-mapping/ # Object mapping DSL and code generation
├── modules-codegen-support/# Code generation infrastructure and base classes
├── modules-test-support/ # Shared test fixtures and utilities
├── modules-bom/ # Bill of Materials for dependency management
├── samples/ # Example applications and generated code validation
└── doc/ # Design documentation
```
**Convention**: Each module follows standard Kotlin layout:
**Pattern**: Codegen modules (`*-codegen`) contain annotation processors; runtime modules contain base classes/interfaces/implementations.
Modules are auto-discovered in `settings.gradle.kts` via `registerModules()` function.
Compile-time annotation processing for JPA entities:
**Key Annotation**: `@ZyModel` (place on `@Entity` classes)
**Generated Artifacts**:
**KAPT Configuration** (in `build.gradle.kts`):
```kotlin
kapt {
arguments {
arg("zygarde.codegen.base.package", "my.package.codegen")
arg("zygarde.codegen.dao.inherit", "zygarde.data.jpa.dao.ZygardeEnhancedDao")
}
}
```
**Key Options**:
Runtime DSL scripts that generate complete application layers:
**Model Mapping DSL** (`ModelMappingCodegenSpec`):
```kotlin
class MyModelDsl : ModelMappingCodegenSpec({
MyDto {
fromAutoIntId(Entity::id) // Entity→DTO mapping
from(Entity::description)
}
CreateMyReq {
applyTo(Entity::description) // DTO→Entity mapping
}
})
```
**Web API DSL** (`WebMvcDslCodegen`):
Generates API interfaces, controllers, and service interfaces.
**Code Generation Workflow**:
1. Modify DSL definitions or annotation processors
2. Run code generation (KAPT or DSL script)
3. Regenerate sample outputs in `samples/todo-multimodule-dsl`
4. Review generated code diffs in version control
5. Ensure generated code compiles and passes tests
**IMPORTANT**: Never manually edit generated files. Keep them isolated in dedicated `*-codegen` modules or `doc/codegen-*` directories.
Provides a type-safe, fluent DSL for JPA queries that abstracts JPA Criteria API complexity:
```kotlin
// Generated DAO usage
bookDao.search {
name() eq "MyBook"
author().age() gt 30
status() inList listOf(Status.ACTIVE, Status.PENDING)
}
// Enhanced DAO operations
bookDao.remove {
name() eq "MyBook"
}
```
**Architecture**:
**Action Types**:
**Advanced Features**:
The model mapping DSL provides three mapping directions:
1. **Model-to-DTO** (`from`/`fromAutoId`) - generates `.toXxxDto()` extensions
2. **DTO-to-Model** (`applyTo`) - generates `.applyFrom(dto)` extensions on entities
3. **Field-level** - with custom `ValueProvider` implementations
**Mapping Features**:
**Generated Artifacts**:
1. API Interface - contract definition with Spring annotations
2. Controller Implementation - HTTP endpoint routing
3. Service Interface - business logic contract
4. Feign Client (optional) - inter-service communication
Use given/when/then pattern with Kotest assertions:
```kotlin
@Test
fun `should create user with valid data`() {
// given
val userData = UserData(name = "John")
// when
val result = userService.createUser(userData)
// then
result shouldNotBe null
result.name shouldBe "John"
}
```
**Guidelines**:
Follow Conventional Commits: `<type>(<scope>): <subject>`
**Types**: `feat`, `fix`, `refactor`, `chore`, `docs`, `test`, `perf`, `style`, `ci`
**Examples**:
```
feat(jpa): add support for composite key entities
fix(web): correct JSON serialization for LocalDateTime
chore(deps): upgrade Spring Boot to 2.7.14
```
1. Run `./gradlew ktlintFormat` to fix formatting
2. Run `./gradlew build` to ensure all tests pass
3. Run `./gradlew detekt` to verify static analysis
4. Check that coverage has not decreased
5. If touching code generation, regenerate samples and verify diffs
**Build fails with KAPT errors**:
**ktlint failures**:
**Test failures**:
**Coverage decreased**:
The framework uses two complementary code generation approaches:
1. **KAPT** for entity-driven generation (DAOs, search DSL)
2. **DSL scripts** for application-layer generation (mappings, controllers)
This separation allows entity-level metadata to be captured at compile-time while application-layer patterns remain flexible and can be regenerated independently.
The search DSL completely abstracts JPA Criteria API complexity through:
**Strict separation**:
This ensures the framework's runtime libraries remain lightweight and independent of code generation infrastructure.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/zygarde-entity-first-development/raw