ADR 016: Configuration Adapter (CA) SDK Language
Date: 2026-03-10
Status: Reviewed
Decision Makers: CIVITAS/CORE Architecture Board
Context
The Configuration Adapter (CA) SDK is intended to simplify the implementation of adapters that translate CIVITAS/CORE configuration events into concrete configuration changes in external systems such as IAM, GIS, or other platform services.
The SDK must be suitable as a reusable library, not as a full application framework. It therefore has to stay lightweight, easy to embed into different runtime environments, and predictable in operation. The SDK also has to integrate well with the technical building blocks already used in CIVITAS/CORE, especially Kafka, CloudEvents, JSON-based payloads, and HTTP-based service APIs.
For this use case, the most important requirements are:
- low runtime overhead and fast startup behavior
- minimal dependency footprint
- broad developer familiarity and maintainability
- good library support for Kafka, CloudEvents, JSON, HTTP clients, and Keycloak integration
- no hard coupling to a heavyweight opinionated application framework
The current technical direction of the CA SDK already points toward a small dependency set around CloudEvents, Kafka clients, Jackson, JAX-RS/Jersey, and a few utility libraries. This favors a plain Java implementation over a framework-centric approach.
Checked Architecture Principles
- [partial] Model-centric data flow – models are supported by Jackson
- [full] Distributed architecture with unified user experience
- [full] Modular design
- [full] Integration capability through defined interfaces
- [full] Open source as the default
- [partial] Cloud-native architecture – plain Java
- [full] Prefer standard solutions over custom development
- [full] Self-contained deployment
- [full] Technological consistency to ensure maintainability
- [none] Multi-tenancy
- [partial] Security by design
Comments on partial ratings:
- Model-centric data flow: The SDK itself is a technical integration library. It supports model-driven configuration flows, but it does not define domain models by itself.
- Cloud-native architecture: Plain Java works well in containers, but cloud-native behavior such as health checks, secret injection, and runtime management must still be provided by the surrounding adapter service.
- Security by design: The language and dependency choice reduce attack surface and complexity, but secure credential handling, transport security, and authorization still depend on the implementing adapter.
Decision
The CA SDK is implemented in plain Java with a minimal and explicit dependency set.
This means:
- Java is the default implementation language for the reusable SDK and for reference adapters built on top of it.
- The SDK avoids heavyweight frameworks such as Spring Boot or Quarkus in its core library.
- Required integrations are provided through focused libraries such as Kafka clients, CloudEvents, Jackson, JAX-RS/Jersey, and selected utility dependencies.
- Adapter implementations may still use additional frameworks in their own runtime layer if there is a justified need, but the shared SDK remains framework-neutral.
Consequences
- The SDK remains lightweight and easier to embed in different adapter runtimes.
- Dependency management stays transparent, which reduces operational surprises and long-term maintenance effort.
- The project keeps control over its abstractions instead of inheriting framework conventions that are not needed for a library use case.
- More infrastructure concerns have to be handled explicitly by adapter implementations, for example dependency injection, runtime configuration, or health endpoints.
- Documentation and reference implementations become more important, because plain Java provides fewer guardrails than an opinionated framework stack.
Alternatives
- Spring Boot: Rejected for the SDK core because it adds significant framework overhead and couples the shared library to a specific runtime model.
- Quarkus: Rejected because it optimizes service runtimes well, but still introduces framework assumptions that are unnecessary for a reusable SDK layer.
- Kotlin: Rejected as default language because Java offers broader familiarity in the current team and ecosystem, while still meeting all technical requirements.