Zygarde Entity-First Development

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

Essential Commands

Build & Test

```bash

Full build with tests and coverage

./gradlew build

Run tests only

./gradlew test

Test specific module

./gradlew -p modules-core/zygarde-core test

Run sample application

./gradlew :samples:todo-legacy:bootRun

```

Code Quality

```bash

Auto-format code (do this before committing)

./gradlew ktlintFormat

Check formatting

./gradlew ktlintCheck

Run static analysis

./gradlew detekt

```

Development

```bash

Refresh dependency locks

./scripts/deps.sh

Run single test class

./gradlew test --tests "ClassName"

Run KAPT code generation

./gradlew kaptKotlin

```

Module Architecture

Structure

```

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.

Two-Tier Code Generation System

1. KAPT-Based (Annotation Processors)

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**:

2. DSL-Based (Standalone Codegen)

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.

Type-Safe JPA Search DSL

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**:

Model Mapping Pattern

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**:

Web/REST Utilities

Three-Layer Generation Pattern

**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

Exception Handling

API Response Standardization

Coding Standards

Kotlin Style

Testing Standards

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**:

Package Naming

Git Workflow

Commit Message Format

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

```

Pre-Commit Checklist

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

Common Patterns

Type Extension Pattern

Common Data Structures

Loggable Mixin

Troubleshooting

**Build fails with KAPT errors**:

**ktlint failures**:

**Test failures**:

**Coverage decreased**:

Key Architectural Insights

Code Generation Philosophy

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.

JPA Criteria Abstraction

The search DSL completely abstracts JPA Criteria API complexity through:

Module Dependency Pattern

**Strict separation**:

This ensures the framework's runtime libraries remain lightweight and independent of code generation infrastructure.