### Test API Endpoints with cURL (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

Provides example cURL commands to interact with the created TODO application's REST API. It demonstrates how to create a new todo via POST, retrieve all todos via GET, and mark a todo as complete via PUT.

```bash
# Create a todo
curl -X POST http://localhost:8080/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title":"Learn Zygarde","description":"Complete the quick start guide"}'

# Get all todos
curl http://localhost:8080/api/todos

# Complete a todo
curl -X PUT http://localhost:8080/api/todos/1/complete
```

--------------------------------

### Clean and Build Project (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Performs a clean build of the project, removing previous build artifacts before compiling and packaging.

```bash
./gradlew clean build
```

--------------------------------

### Zygarde Web Module Configuration (my-app-web/build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the web module, setting up dependencies for Spring Boot web starters, Zygarde webmvc, and defining the main application class. It also includes H2 database for runtime.

```kotlin
// my-app-web/build.gradle.kts
plugins {
  kotlin("jvm")
  kotlin("plugin.spring")
  id("org.springframework.boot")
  id("io.spring.dependency-management")
}

dependencies {
  implementation(project(":my-app-service"))
  implementation("org.springframework.boot:spring-boot-starter-web:2.7.14")
  implementation("zygarde:zygarde-webmvc:VERSION")

  runtimeOnly("com.h2database:h2")

  testImplementation("org.springframework.boot:spring-boot-starter-test:2.7.14")
}

springBoot {
  mainClass.set("com.example.myapp.ApplicationKt")
}
```

--------------------------------

### Run Specific Application Module (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Uses Gradle to run a specific application module, typically a web application.

```bash
./gradlew :my-app-web:bootRun
```

--------------------------------

### Run All Tests with Gradle (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Executes all tests in the project using Gradle. This command is useful for ensuring code correctness.

```bash
# All tests
./gradlew test

# Specific module
./gradlew :my-app-service:test

# With coverage
./gradlew test jacocoTestReport
```

--------------------------------

### Zygarde Root Settings Configuration (settings.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the root project name and includes all submodules in a Zygarde multi-module setup. This file is essential for Gradle to recognize and manage all parts of the project.

```kotlin
rootProject.name = "my-app"

include(
  "my-app-domain",
  "my-app-codegen",
  "my-app-service",
  "my-app-web"
)
```

--------------------------------

### Build Project with Gradle to Generate Code (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/index.md

Executes the Gradle build command to trigger the KAPT code generation process for Zygarde. Running './gradlew kaptKotlin' ensures that the code generation tasks are executed, producing DAO interfaces and search DSL extensions based on the annotated entities.

```bash
./gradlew kaptKotlin
```

--------------------------------

### Zygarde Service Module Configuration (my-app-service/build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the service module, making it depend on the codegen module and Zygarde core. It includes Spring Boot starters and testing dependencies like MockK for unit testing.

```kotlin
// my-app-service/build.gradle.kts
plugins {
  kotlin("jvm")
  kotlin("plugin.spring")
}

dependencies {
  api(project(":my-app-codegen"))
  implementation("org.springframework.boot:spring-boot-starter:2.7.14")
  implementation("zygarde:zygarde-core:VERSION")

  testImplementation("org.springframework.boot:spring-boot-starter-test:2.7.14")
  testImplementation("io.mockk:mockk:1.12.0")
}
```

--------------------------------

### Zygarde Root Build Configuration (build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Sets up the root build script for a Zygarde project, defining buildscript repositories, common plugins, and project-wide configurations like group, version, and repositories for all subprojects. It also applies Kotlin stdlib to all subprojects.

```kotlin
buildscript {
  repositories {
    mavenCentral()
  }
}

plugins {
  kotlin("jvm") version "1.8.22" apply false
  kotlin("kapt") version "1.8.22" apply false
  kotlin("plugin.spring") version "1.8.22" apply false
  id("org.springframework.boot") version "2.7.14" apply false
  id("io.spring.dependency-management") version "1.1.3" apply false
}

allprojects {
  group = "com.example.myapp"
  version = "1.0.0-SNAPSHOT"

  repositories {
    mavenCentral()
    maven("https://nexus.puni.tw/repository/maven-releases")
  }
}

subprojects {
  apply(plugin = "kotlin")

  dependencies {
    implementation(kotlin("stdlib-jdk8"))
    implementation(kotlin("reflect"))
  }
}
```

--------------------------------

### Zygarde Multi-Module Project Structure

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Defines a standard multi-module project layout for Zygarde applications. This structure separates concerns into domain models, generated code, business logic, and web controllers.

```text
my-app/
├── settings.gradle.kts
├── build.gradle.kts
├── my-app-domain/          # Domain models
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       └── model/
├── my-app-codegen/         # Generated code
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       └── codegen/
├── my-app-service/         # Business logic
│   ├── build.gradle.kts
│   └── src/main/kotlin/
│       └── service/
└── my-app-web/             # REST controllers
    ├── build.gradle.kts
    └── src/main/kotlin/
        └── controller/
```

--------------------------------

### Integration Test for Todo Service (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

An integration test for the TodoService using Spring Boot. It verifies the functionality of creating and retrieving a todo item, ensuring data integrity.

```kotlin
@SpringBootTest
@TestPropertySource(locations = ["classpath:application-test.yml"])
class TodoServiceIntegrationTest {

  @Autowired
  lateinit var todoService: TodoService

  @Test
  fun `should create and retrieve todo`() {
    // given
    val title = "Test Todo"

    // when
    val created = todoService.createTodo(title, null)
    val retrieved = todoService.getTodoById(created.id!!)

    // then
    retrieved shouldNotBe null
    retrieved?.title shouldBe title
  }
}
```

--------------------------------

### Configure Detekt with Kotlin

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the Detekt static analysis tool for Kotlin projects. It enables building upon the default configuration and specifies the path to the custom configuration file.

```kotlin
plugins {
  id("io.gitlab.arturbosch.detekt") version "1.18.1"
}

detekt {
  buildUponDefaultConfig = true
  config = files("${rootProject.projectDir}/detekt.yml")
}
```

--------------------------------

### Zygarde Domain Module Configuration (my-app-domain/build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the domain module for Zygarde projects, applying necessary Kotlin plugins and defining dependencies for JPA, Zygarde JPA, and code generation. It also sets up Kapt arguments for Zygarde code generation.

```kotlin
// my-app-domain/build.gradle.kts
plugins {
  kotlin("jvm")
  kotlin("plugin.spring")
  kotlin("kapt")
}

dependencies {
  api("org.springframework.boot:spring-boot-starter-data-jpa:2.7.14")
  api("zygarde:zygarde-jpa:VERSION")
  kapt("zygarde:zygarde-jpa-codegen:VERSION")
}

kapt {
  arguments {
    arg("zygarde.codegen.base.package", "com.example.myapp.codegen")
    arg("zygarde.codegen.dao.inherit", "zygarde.data.jpa.dao.ZygardeEnhancedDao")
  }
}
```

--------------------------------

### Create REST Controller for TODOs (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

Defines a Spring Boot REST controller ('TodoController') to expose the 'TodoService' functionality via HTTP endpoints. It includes methods for getting all todos, getting a todo by ID, creating a new todo, and marking a todo as complete. A DTO 'CreateTodoRequest' is also defined.

```kotlin
package com.example.todo.controller

import com.example.todo.service.TodoService
import org.springframework.web.bind.annotation.*

@RestController
@RequestMapping("/api/todos")
class TodoController(private val todoService: TodoService) {

  @GetMapping
  fun getAllTodos() = todoService.getAllTodos()

  @GetMapping("/{id}")
  fun getTodoById(@PathVariable id: Long) = todoService.getTodoById(id)

  @PostMapping
  fun createTodo(@RequestBody request: CreateTodoRequest) =
    todoService.createTodo(request.title, request.description)

  @PutMapping("/{id}/complete")
  fun completeTodo(@PathVariable id: Long) = todoService.completeTodo(id)
}

data class CreateTodoRequest(
  val title: String,
  val description: String?
)
```

--------------------------------

### KAPT and DSL Configuration Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/architecture.md

Provides examples of configuring code generation using both KAPT arguments and a DSL-like syntax. The KAPT example shows setting a base package, while the DSL example demonstrates defining a DTO mapping.

```kotlin
// KAPT configuration
kapt {
  arguments {
    arg("zygarde.codegen.base.package", "com.example.codegen")
  }
}

// DSL configuration
MyDto {
  fromAutoIntId(Entity::id)
  from(Entity::description)
}
```

--------------------------------

### Spring Boot Main Application Class (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

The main entry point for the Spring Boot 'TodoApplication'. It uses the '@SpringBootApplication' annotation to enable auto-configuration and component scanning, and the 'runApplication' function to start the application.

```kotlin
package com.example.todo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication
class TodoApplication

fun main(args: Array<String>) {
  runApplication<TodoApplication>(*args)
}
```

--------------------------------

### Zygarde PostgreSQL Database Configuration (application-prod.yml)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configuration for a PostgreSQL database for production environments in a Zygarde project. It specifies connection details, credentials (using environment variables), and sets JPA to validate the schema.

```yaml
# src/main/resources/application-prod.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/myapp
    driver-class-name: org.postgresql.Driver
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  jpa:
    hibernate:
      ddl-auto: validate
    properties:
      hibernate:
        dialect: org.hibernate.dialect.PostgreSQLDialect
```

--------------------------------

### Zygarde H2 Database Configuration (application-dev.yml)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configuration for an in-memory H2 database for development environments in a Zygarde project. It enables the H2 console and sets JPA to create and drop tables.

```yaml
# src/main/resources/application-dev.yml
spring:
  datasource:
    url: jdbc:h2:mem:myapp
    driver-class-name: org.h2.Driver
    username: sa
    password:
  h2:
    console:
      enabled: true
      path: /h2-console
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
```

--------------------------------

### Add Zygarde Core Dependencies (Kotlin/Gradle)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/index.md

Configures the build.gradle.kts file to include the minimum Zygarde core dependencies for JPA and code generation. This involves applying the 'kotlin("kapt")' plugin, setting up necessary repositories (Nexus or GitHub Packages), and adding 'zygarde-jpa' and 'zygarde-jpa-codegen' as implementation and kapt dependencies, respectively. Ensure you replace 'VERSION' with the correct Zygarde version.

```kotlin
// build.gradle.kts
plugins {
  kotlin("kapt") version "1.8.22"  // Required for code generation
  // ... your existing plugins
}

repositories {
  maven("https://nexus.puni.tw/repository/maven-releases")
  // OR GitHub Packages
  maven {
    url = uri("https://maven.pkg.github.com/zygarde-projects/zygarde")
    credentials {
      username = System.getenv("GITHUB_ACTOR")
      password = System.getenv("GITHUB_TOKEN")
    }
  }
}

dependencies {
  // These two dependencies are all you need to start
  implementation("zygarde:zygarde-jpa:VERSION")
  kapt("zygarde:zygarde-jpa-codegen:VERSION")
}
```

--------------------------------

### Repository Test for Todo DAO (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

A repository test for the TodoDao using Spring Data JPA. It checks the ability to save todos and find them by title using a custom query.

```kotlin
@DataJpaTest
class TodoDaoTest {

  @Autowired
  lateinit var todoDao: TodoDao

  @Test
  fun `should find todos by title`() {
    // given
    val todo1 = Todo(title = "Kotlin Tutorial", completed = false)
    val todo2 = Todo(title = "Java Tutorial", completed = false)
    todoDao.saveAll(listOf(todo1, todo2))

    // when
    val results = todoDao.search {
      title() contains "Kotlin"
    }

    // then
    results.size shouldBe 1
    results[0].title shouldBe "Kotlin Tutorial"
  }
}
```

--------------------------------

### Zygarde Sample Application Run Command (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/README.md

Launches a specific sample application, in this case, the 'todo-legacy' project, using Gradle. This command is useful for testing and demonstrating the functionality of Zygarde with a practical example.

```bash
./gradlew :samples:todo-legacy:bootRun
```

--------------------------------

### Utilize Type-Safe Search DSL (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

Illustrates how to use Zygarde's generated search DSL for type-safe querying of 'Todo' entities. Examples include finding incomplete todos, searching by title (case-insensitive), complex queries using 'and', and removing completed todos.

```kotlin
// Find incomplete todos
val incompleteTodos = dao.todo.search {
  completed() eq false
}

// Find todos by title (case-insensitive)
val kotlinTodos = dao.todo.search {
  title() contains "kotlin"
}

// Complex queries
val filteredTodos = dao.todo.search {
  and {
    completed() eq false
    title() notNull()
    description() like "%important%"
  }
}

// Enhanced DAO operations (if using ZygardeEnhancedDao)
dao.todo.remove {
  completed() eq true
}
```

--------------------------------

### Zygarde Codegen Module Configuration (my-app-codegen/build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the codegen module to depend on the domain module and Zygarde JPA. It sets up the source directory to include generated code from the domain module and ensures Kotlin compilation depends on Kapt generation.

```kotlin
// my-app-codegen/build.gradle.kts
plugins {
  kotlin("jvm")
  kotlin("plugin.spring")
}

dependencies {
  api(project(":my-app-domain"))
  api("org.springframework.boot:spring-boot-starter-data-jpa:2.7.14")
  api("zygarde:zygarde-jpa:VERSION")
}

sourceSets {
  main {
    java {
      srcDir("${project(":my-app-domain").buildDir}/generated/source/kapt/main")
    }
  }
}

tasks.compileKotlin {
  dependsOn(":my-app-domain:kaptKotlin")
}
```

--------------------------------

### Complete Zygarde KAPT Configuration Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/reference/kapt-options.md

A comprehensive example of a `build.gradle.kts` file configuring Zygarde's KAPT annotation processor. It includes plugin application, dependencies, and various KAPT arguments for base package, DAO naming, inheritance, and aggregation.

```kotlin
// build.gradle.kts
plugins {
  kotlin("kapt") version "1.8.22"
}

dependencies {
  implementation("zygarde:zygarde-jpa:VERSION")
  kapt("zygarde:zygarde-jpa-codegen:VERSION")
}

kapt {
  arguments {
    // Required: base package
    arg("zygarde.codegen.base.package", "com.example.bookstore.codegen")

    // Optional: customize DAO naming
    arg("zygarde.codegen.dao.package", "data.repository")
    arg("zygarde.codegen.dao.suffix", "Repository")

    // Optional: use enhanced DAO with search DSL
    arg("zygarde.codegen.dao.inherit", "zygarde.data.jpa.dao.ZygardeEnhancedDao")

    // Optional: enable aggregated Dao
    arg("zygarde.codegen.dao.combine", "true")
  }
}
```

--------------------------------

### Use Generated DAO in Service Layer (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

Demonstrates injecting and utilizing the Zygarde-generated 'Dao' interface within a Spring service ('TodoService'). It shows examples of finding all todos, finding by ID, creating a new todo, and marking a todo as complete using the generated DAO methods.

```kotlin
package com.example.todo.service

import com.example.todo.codegen.Dao
import org.springframework.stereotype.Service
import org.springframework.transaction.annotation.Transactional

@Service
class TodoService(private val dao: Dao) {

  fun getAllTodos() = dao.todo.findAll()

  fun getTodoById(id: Long) = dao.todo.findById(id)

  @Transactional
  fun createTodo(title: String, description: String?): Todo {
    val todo = Todo(title = title, description = description)
    return dao.todo.save(todo)
  }

  @Transactional
  fun completeTodo(id: Long): Todo? {
    val todo = dao.todo.findById(id).orElse(null) ?: return null
    val updated = todo.copy(completed = true)
    return dao.todo.save(updated)
  }
}
```

--------------------------------

### Kotlin Code Example for Zygarde Documentation

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

A simple Kotlin function example demonstrating basic syntax, intended to be used within Markdown code blocks for syntax highlighting in the Zygarde documentation.

```kotlin
fun example() {
  println("Hello, Zygarde!")
}
```

--------------------------------

### Configure KAPT Arguments for Zygarde Codegen (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures Kotlin Annotation Processing Tool (KAPT) arguments for Zygarde code generation. This ensures generated code is placed in a consistent package structure.

```kotlin
kapt {
  arguments {
    arg("zygarde.codegen.base.package", "com.example.codegen")
    arg("zygarde.codegen.dao.package.postfix", "dao")
  }
}
```

--------------------------------

### Zygarde ktlint Code Quality Configuration (build.gradle.kts)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/project-setup.md

Configures the ktlint Gradle plugin for code quality checks across all modules in a Zygarde project. It specifies the plugin version and ktlint version, enabling verbose output.

```kotlin
// Root build.gradle.kts
plugins {
  id("org.jlleitschuh.gradle.ktlint") version "10.2.0"
}

allprojects {
  apply(plugin = "org.jlleitschuh.gradle.ktlint")

  ktlint {
    version.set("0.45.2")
    verbose.set(true)
    android.set(false)
  }
}
```

--------------------------------

### Configure KAPT Arguments for Zygarde Code Generation (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/index.md

Sets up KAPT arguments within the build.gradle.kts file to define the package for generated DAO code and optionally specify an enhanced DAO interface. The 'zygarde.codegen.base.package' argument is mandatory, specifying where the DAO code will be placed. The 'zygarde.codegen.dao.inherit' argument is optional and allows for using a custom base DAO.

```kotlin
kapt {
  arguments {
    // Required: where to generate DAO code
    arg("zygarde.codegen.base.package", "com.example.myapp.codegen")

    // Optional: use enhanced DAO with search() method
    arg("zygarde.codegen.dao.inherit", "zygarde.data.jpa.dao.ZygardeEnhancedDao")
  }
}
```

--------------------------------

### Build and Run Application (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/kapt-based.md

This bash command uses Gradle to build and run the Spring Boot application. It's a standard way to start the application during development.

```bash
./gradlew bootRun
```

--------------------------------

### Annotate Entity for Zygarde Code Generation (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/index.md

Demonstrates how to annotate a Kotlin data class with `@Entity` and `@ZyModel` to trigger Zygarde's code generation process. The `@ZyModel` annotation is the key to enabling Zygarde to generate a repository interface and other related code for the `Book` entity.

```kotlin
@Entity
@ZyModel  // ← Zygarde annotation triggers code generation
data class Book(
  @Id @GeneratedValue
  val id: Long? = null,
  val title: String
)
```

--------------------------------

### Install Python Dependencies with pip

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

Installs Python dependencies required for running the Zygarde documentation site locally. It can be used with or without a virtual environment.

```bash
pip install -r ../requirements.txt
```

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r ../requirements.txt
```

--------------------------------

### JPA Criteria Abstraction Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/architecture.md

Shows an example of how the search DSL abstracts JPA Criteria complexity, enabling type-safe field references and automatic join resolution for fluent querying.

```kotlin
dao.book.search {
  author().country() eq "USA"  // Automatically creates join
}
```

--------------------------------

### MkDocs Navigation Configuration

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

Example configuration for the navigation structure of the Zygarde documentation site using MkDocs. It defines the hierarchy and links for the site's navigation.

```yaml
nav:
  - Home: index.md
  - Getting Started:
    - getting-started/index.md
    - Quick Start: getting-started/quick-start.md
```

--------------------------------

### Bash Multi-Module Gradle Build

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/code-generation.md

Example commands for building a multi-module Gradle project where code generation is involved. It demonstrates running KAPT for a specific module, compiling a codegen module, and building the entire project.

```bash
# Generate code in domain module
./gradlew :my-app-domain:kaptKotlin

# Compile codegen module (depends on domain)
./gradlew :my-app-codegen:compileKotlin

# Build entire project
./gradlew build
```

--------------------------------

### Kotlin Test Structure Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/TEST_COVERAGE_IMPROVEMENT_PLAN.md

Demonstrates the standard 'given-when-then' structure for writing tests in Kotlin, utilizing Kotest assertions for clarity and MockK for dependency mocking. This structure ensures tests are readable and cover expected behaviors.

```kotlin
class ComponentNameTest {
  @Test
  fun `should handle expected behavior`() {
    // given
    val input = createTestData()
    
    // when
    val result = componentUnderTest.method(input)
    
    // then
    result shouldNotBe null
    result.property shouldBe expectedValue
  }
}
```

--------------------------------

### Markdown Link Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

Illustrates how to create internal, external, and anchor links within Markdown files for the Zygarde documentation. This helps in navigating between different sections and external resources.

```markdown
# Internal links (relative to docs/)
[Getting Started](getting-started/index.md)
[Quick Start](getting-started/quick-start.md)

# External links
[Kotlin Documentation](https://kotlinlang.org/docs/)

# Link to specific heading
[Installation](getting-started/index.md#installation)
```

--------------------------------

### GraphQL Resolver with Zygarde Search (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/faq.md

Expose Zygarde data access through GraphQL resolvers. This example demonstrates searching books based on filter criteria and mapping results to DTOs.

```kotlin
@DgsData(parentType = "Query", field = "books")
fun getBooks(@InputArgument filter: BookFilter): List<BookDto> {
  return dao.book.search {
    filter.title?.let { title() containsIgnoreCase it }
    filter.authorId?.let { author().id() eq it }
  }.map { it.toDto() }
}
```

--------------------------------

### Project Module Structure Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/code-generation.md

Illustrates a typical Zygarde project structure with separate modules for domain entities, generated code, and service logic. This separation helps manage dependencies and maintain code quality.

```text
my-app/
├── my-app-domain/       # Source entities
├── my-app-codegen/      # Zygarde-generated code
└── my-app-service/      # Uses generated code
```

--------------------------------

### Build and Generate Code with Gradle (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

This command triggers the Gradle build process, which in turn invokes Zygarde's KAPT code generation. It generates DAO interfaces and type-safe search DSL extensions based on the annotated JPA entities.

```bash
./gradlew build
```

--------------------------------

### Serve Zygarde Documentation Locally with MkDocs

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

Starts a local development server for the Zygarde documentation. The site is accessible at http://127.0.0.1:8000/ by default and supports live reloading on file changes. A different port can be specified.

```bash
mkdocs serve
```

```bash
mkdocs serve --dev-addr=127.0.0.1:8080
```

--------------------------------

### Build and Run Project with Gradle

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/dsl-based.md

Provides Gradle commands to build the Zygarde project and run the application. This includes steps for generating KAPT code, model mappings, and web API DSL code, followed by building the entire project and running the Spring Boot application. It also includes cURL commands for testing the API endpoints.

```bash
# Generate KAPT code
./gradlew :todo-domain:kaptKotlin

# Generate DSL code (model mappings)
./gradlew :todo-codegen:run \
  -Dzygarde.model.mapping.codegen.spec.class=com.example.todo.codegen.dsl.TodoModelDsl

# Generate DSL code (web API)
./gradlew :todo-codegen:run \
  -Dzygarde.webmvc.codegen.spec.class=com.example.todo.codegen.dsl.TodoApiDsl

# Build entire project
./gradlew build

# Run application
./gradlew :todo-web:bootRun
```

```bash
# Create todo
curl -X POST http://localhost:8080/api/todos \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Learn DSL Generation",
    "description": "Master Zygarde DSL-based approach",
    "priority": 5
  }'

# Get all todos
curl http://localhost:8080/api/todos

# Search todos
curl "http://localhost:8080/api/todos?search=DSL"

# Update todo
curl -X PUT http://localhost:8080/api/todos/1 \
  -H "Content-Type: application/json" \
  -d '{"completed": true}'
```

--------------------------------

### Spring Boot Application Configuration (YAML)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/quick-start.md

Provides the necessary application configuration in YAML format for a Spring Boot application using an H2 in-memory database. It includes settings for the data source URL, JPA properties like DDL auto-generation, and SQL statement formatting.

```yaml
# application.yml
spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true
    properties:
      hibernate:
        format_sql: true
```

--------------------------------

### Deploy Zygarde Documentation to GitHub Pages with MkDocs

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/README.md

Commands to build and deploy the Zygarde documentation to GitHub Pages. It builds the static site and pushes it to the 'gh-pages' branch. The --force option can be used to overwrite existing content.

```bash
mkdocs gh-deploy
```

```bash
mkdocs gh-deploy --force
```

--------------------------------

### Kotlin: Zygarde Web API Generation DSL

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/index.md

Defines a REST API using Zygarde's DSL for web API generation. This example specifies an API named 'BookApi' with a base path and defines a 'searchBooks' endpoint using HTTP GET method, including query parameters and return types. Zygarde uses this specification to automatically generate the API interface, controller implementation, and service interface.

```kotlin
api("BookApi") {
  basePath = "/api/books"

  endpoint {
    name = "searchBooks"
    method = GET
    params = listOf("title" to "String?")
    returns = "List<BookDto>"
  }
}
```

--------------------------------

### Configure Spring Boot Application

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/dsl-based.md

Sets up the main Spring Boot application class and configuration properties. The application class `TodoApplication` enables component scanning for both the main application package and the generated code package. The `application.yml` file configures the H2 in-memory database, JPA settings, and the server port.

```kotlin
// todo-web/src/main/kotlin/Application.kt
package com.example.todo

import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.boot.runApplication

@SpringBootApplication(
  scanBasePackages = [
    "com.example.todo",
    "com.example.todo.codegen"
  ]
)
class TodoApplication

fun main(args: Array<String>) {
  runApplication<TodoApplication>(*args)
}
```

```yaml
# todo-web/src/main/resources/application.yml
spring:
  datasource:
    url: jdbc:h2:mem:todo
    driver-class-name: org.h2.Driver
  jpa:
    hibernate:
      ddl-auto: create-drop
    show-sql: true

server:
  port: 8080
```

--------------------------------

### Verifying Module Build Order (Bash)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/dsl-based.md

Command-line instructions to manually verify the build order of Zygarde modules using Gradle. This is useful for troubleshooting build issues related to module dependencies.

--------------------------------

### KAPT: Generated DAO Interface Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/code-generation.md

Shows an example of a generated DAO interface for a `Book` entity. This interface extends `ZygardeEnhancedDao` and provides enhanced data access capabilities.

```kotlin
// Generated: BookDao.kt
interface BookDao : ZygardeEnhancedDao<Book, Long>
```

--------------------------------

### Example JSON Error Response

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/web-rest.md

Illustrates a typical JSON representation of an API error response, adhering to the defined `ApiErrorResponse` structure. This example shows a "BOOK_NOT_FOUND" error with relevant details.

```json
{
  "code": "BOOK_NOT_FOUND",
  "message": "Book not found: 123",
  "timestamp": 1704067200000,
  "path": "/api/books/123"
}
```

--------------------------------

### ZygardeEnhancedDao Remove DSL Example Kotlin

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/jpa-extensions.md

Shows an example of using the remove method with the DSL to perform bulk deletion of entities that match specified conditions, such as publication year and status.

```kotlin
val deleted = bookDao.remove {
  publishedYear() lt 2000
  status() eq Status.ARCHIVED
}
// Returns count of deleted entities
```

--------------------------------

### Main Application Class for Spring Boot (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/kapt-based.md

This Kotlin code defines the main entry point for a Spring Boot application. The '@SpringBootApplication' annotation enables auto-configuration and component scanning, while the 'main' function bootstraps the application.

```kotlin
@SpringBootApplication
class TodoApplication

fun main(args: Array<String>) {
  runApplication<TodoApplication>(*args)
}
```

--------------------------------

### JSON Validation Error Response Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/web-rest.md

Presents an example JSON structure for a validation error, indicating that the request failed validation. The `details` field contains specific error messages for each invalid field, such as 'Title is required' and 'must be greater than or equal to 0.01'.

```json
{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
  "timestamp": 1704067200000,
  "path": "/api/books",
  "details": {
    "title": "Title is required",
    "price": "must be greater than or equal to 0.01"
  }
}
```

--------------------------------

### Conventional Commits Format Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/CLAUDE.md

Provides examples of commit messages adhering to the Conventional Commits specification. This format helps in automating changelog generation and understanding the nature of changes at a glance, using types like `feat`, `fix`, `refactor`, etc., optionally with a scope.

```git
feat(jpa): add support for composite key entities
fix(web): correct JSON serialization for LocalDateTime
chore(deps): upgrade Spring Boot to 2.7.14
```

--------------------------------

### Zygarde exists() - Check Existence Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/jpa-extensions.md

Demonstrates the `exists` method for efficiently checking if any entities match the given criteria without loading them from the database. Examples include checking for books containing 'Kotlin' and checking for active books by a specific author.

```kotlin
val hasKotlinBooks = bookDao.exists {
  title() contains "Kotlin"
}

```

```kotlin
val hasActiveBooksByAuthor = bookDao.exists {
  author().id() eq authorId
  status() eq Status.ACTIVE
}

```

--------------------------------

### Zygarde Module Dependencies (Gradle Settings)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/dsl-based.md

Illustrates the required module dependency order for a Zygarde project in `settings.gradle.kts`. Proper ordering ensures that generated code and modules are available in the correct build sequence.

--------------------------------

### Zygarde remove() - Bulk Delete Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/jpa-extensions.md

Provides examples of using the `remove` method to perform bulk deletions based on specified criteria. Shows deleting books published before a certain year and status, and deleting books associated with inactive authors.

```kotlin
// Returns count of deleted entities
val deletedCount = bookDao.remove {
  publishedYear() lt 2000
  status() eq Status.ARCHIVED
}

```

```kotlin
// Delete with relationship conditions
val deletedInactiveAuthorBooks = bookDao.remove {
  author().status() eq AuthorStatus.INACTIVE
}

```

--------------------------------

### Zygarde count() - Count Matching Entities Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/jpa-extensions.md

Illustrates the use of the `count` method to efficiently determine the number of entities that satisfy specific criteria, without retrieving the entities themselves. Examples include counting active books and counting recently published books.

```kotlin
val activeCount = bookDao.count {
  status() eq Status.ACTIVE
}

```

```kotlin
val recentBooksCount = bookDao.count {
  publishedYear() gte 2020
}

```

--------------------------------

### Manual Spring Data JPA Repository with JPQL

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/getting-started/comparison.md

Demonstrates a traditional Spring Data JPA repository in Kotlin, using both method-name conventions and an explicit JPQL query for searching books. This approach often leads to long method names, repetitive JPQL strings, and difficulty in dynamic query composition.

```kotlin
interface BookRepository : JpaRepository<Book, Long> {
  fun findByTitleContainingIgnoreCaseAndAuthorId(
    title: String,
    authorId: Long
  ): List<Book>
  
  @Query("SELECT b FROM Book b JOIN b.author a " +
         "WHERE LOWER(b.title) LIKE LOWER(CONCAT('%', :title, '%')) " +
         "AND a.id = :authorId")
  fun searchBooks(
    @Param("title") title: String,
    @Param("authorId") authorId: Long
  ): List<Book>
}
```

--------------------------------

### Zygarde Search DSL Examples (Kotlin)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/tutorials/kapt-based.md

Demonstrates the usage of Zygarde's generated search DSL for querying 'Todo' entities. It shows how to perform simple filtering, combine conditions with AND/OR logic, and execute bulk delete operations.

```kotlin
// Find incomplete todos
dao.todo.search {
  completed() eq false
}

// Find high-priority incomplete todos
dao.todo.search {
  completed() eq false
  priority() gte 4
}

// Complex search with OR conditions
dao.todo.search {
  completed() eq false
  or {
    priority() gte 4
    title() contains "urgent"
  }
}

// Bulk operations
val deletedCount = dao.todo.remove {
  completed() eq true
}
```

--------------------------------

### Zygarde searchOne() - Find Single Entity Examples

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/jpa-extensions.md

Shows examples of using the `searchOne` method to retrieve a single entity based on specific criteria. Demonstrates finding a book by ISBN and finding an active book by title, returning either the matching entity or null.

```kotlin
val book = bookDao.searchOne {
  isbn() eq "978-1234567890"
}

```

```kotlin
val activeBook = bookDao.searchOne {
  title() eq "Kotlin in Action"
  status() eq Status.ACTIVE
}

```

--------------------------------

### Kotlin: Zygarde Enhanced Search DSL Example

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/index.md

Illustrates a complex query built using Zygarde's enhanced search system. This example showcases chaining conditions, OR logic, relationship traversal (author().country()), and range comparisons (gte, between). The DSL aims for readability and type safety, compiling to optimized JPA Criteria queries without runtime overhead.

```kotlin
// Complex query with joins, OR conditions, and comparisons
bookDao.search {
  or {
    title() contains "Kotlin"
    description() contains "Kotlin"
  }
  author().country() eq "USA"
  publishedYear() gte 2020
  price() between (10.0 to 50.0)
}
```

--------------------------------

### Build and Test Zygarde Project with Gradle

Source: https://github.com/zygarde-projects/zygarde/blob/v2/CLAUDE.md

Provides essential Gradle commands for building the Zygarde project, running tests (all, specific module, or class), and executing sample applications. These commands are fundamental for development and testing workflows.

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

--------------------------------

### Kotlin: Zygarde Model Mapping DSL for DTOs

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/index.md

Shows how Zygarde's Model Mapping DSL enables declarative Data Transfer Object (DTO) transformations. The `BookDto` example defines how to map fields from a `Book` entity to a `BookDto`, including nested object mapping (`toAuthorDto`). The `CreateBookReq` example demonstrates applying validation annotations directly within the DSL for request objects.

```kotlin
BookDto {
  fromAutoLongId(Book::id)
  from(Book::title)
  fromRef(Book::author) { it.toAuthorDto() }
}

CreateBookReq {
  applyTo(Book::title) {
    validation("@NotBlank", "@Size(min=1, max=200)")
  }
}
```

--------------------------------

### Error Response Format

Source: https://github.com/zygarde-projects/zygarde/blob/v2/docs/guide/web-rest.md

Details the standard structure for API error responses and provides an example.

```APIDOC
## Error Response Format

### Description
Standard error response structure.

### Response Example
```json
{
  "code": "BOOK_NOT_FOUND",
  "message": "Book not found: 123",
  "timestamp": 1704067200000,
  "path": "/api/books/123"
}
```
```

--------------------------------

### Zygarde Project Dependencies and Setup (Gradle Kotlin DSL)

Source: https://github.com/zygarde-projects/zygarde/blob/v2/README.md

Provides the necessary Gradle dependencies and plugin configurations for integrating Zygarde into a Kotlin project using the Kotlin DSL. It includes Kotlin, KAPT plugins, Zygarde JPA and codegen dependencies, and repository configuration.

```kotlin
// build.gradle.kts
plugins {
  kotlin("jvm") version "1.8.22"
  kotlin("kapt") version "1.8.22"
}

dependencies {
  implementation("zygarde:zygarde-jpa:VERSION")
  kapt("zygarde:zygarde-jpa-codegen:VERSION")
}

repositories {
  maven("https://nexus.puni.tw/repository/maven-releases")
}
```