Skip to content
Cyoda Documentation
Settings

Java client template

Repository: github.com/Cyoda/java-client-template · Apache-2.0

An opinionated Gradle and Spring Boot starting point for Cyoda applications in Java or Kotlin. Fork it to start a project. It includes the Cyoda integration — authentication, the REST repository layer, and the gRPC compute-node client — so application code contains only entities, processors, criteria, and REST controllers.

The template is optional. Compute nodes can be written in any language that speaks the compute-node protocol, and AI coding agents build them directly from cyoda help, the API reference, and Cyoda Skills.

Requirements

Section titled “Requirements”

Get started

Section titled “Get started”
Terminal window
git clone https://github.com/Cyoda/java-client-template.git
cd java-client-template

Configure the connection through Spring profiles or environment variables:

Terminal window
export APP_CONFIG_CYODA_HOST=<cyoda-host>:<port>
export APP_CONFIG_CYODA_CLIENT_ID=<client-id>
export APP_CONFIG_CYODA_CLIENT_SECRET=<client-secret>

Import the workflow definitions, then run the application:

Terminal window
./gradlew runApp -PmainClass=com.java_template.common.tool.WorkflowImportTool \
  --args='--spring.profiles.active=local'
./gradlew runApp --args='--spring.profiles.active=local'

The application serves Swagger UI at http://localhost:8080/swagger-ui/index.html.

Project layout

Section titled “Project layout”
Path Contents
src/main/java/com/java_template/common/ Framework code: auth, config, gRPC client, repository, EntityService, serializers, WorkflowImportTool. Not modified by applications.
src/main/java/com/java_template/application/ Application code: entity/, processor/, criterion/, controller/
src/main/resources/workflow/<entity>/version_<n>/<entity>.json Workflow definitions, one per entity model version

Core interfaces

Section titled “Core interfaces”
Interface Role
CyodaEntity Domain entity. Implements getModelKey() and isValid().
CyodaProcessor Runs business logic during a transition. Implements process() and supports().
CyodaCriterion Evaluates a transition condition. Implements check() and supports(). Must be side-effect free.
EntityWithMetadata<T> Wraps an entity with its technical metadata (ID, state).
EntityService Single interface for all Cyoda data operations.

Components are discovered through Spring’s @Component annotation. A processor cannot update the entity it is processing through EntityService.

Examples of each component type are under src/test/java/com/example/application/.

Section titled “Related”