ADR-00002: Define a preferred stack

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Approved	2026-06-24
CTN Technical Advisory Board	Approved	2026-07-08
CTN Steering Committee	Not Required	2026-07-08
BDI Conformance Team	Proposed	2026-07-08
BDI Framework Team	Not Required	2026-07-08

Context and Problem Statement

To align all development efforts and minimize rework, we need to define a preferred technology stack. A common stack allows for easier shifting of functionality between components and team members, ensures better integration, and leverages existing knowledge from previous living labs. We need a stack that is open source, in common use, and integrates well with our chosen Identity and Access Management (IAM) solution.

Furthermore, the stack is guided by the following principles:

• Open Source: Preference for open-source technologies to ensure transparency, avoid vendor lock-in, and leverage community support.
• Broad Adoption: Choosing technologies with wide industry adoption to ensure a large pool of talent, long-term stability, and rich documentation.
• Uniformity: Promoting a consistent technology landscape across components to reduce cognitive load for developers and simplify maintenance.
• Alternative Implementations: While a preferred stack is defined, the architecture should remain open to alternative implementations when there is a strong justification (e.g., specialized performance requirements or specific integration needs), provided they adhere to the overall system architecture and standards.

Considered Options

Option 1: The Preferred Stack (Quarkus, PostgreSQL, Keycloak)

• Description: Use Quarkus (https://quarkus.io) as the primary runtime/framework, PostgreSQL (https://www.postgresql.org) as the relational database, and Keycloak (https://www.keycloak.org) for IAM.
• Pros:
  • Keycloak is already a given based on learnings from living labs.
  • Quarkus and PostgreSQL align naturally with Keycloak (Red Hat ecosystem, Java-based).
  • All components are open source and have significant community and industry support.
  • High performance and developer productivity.
• Cons: Requires Java/Quarkus expertise.

What Quarkus is (for thos who aren’t familiar)

Quarkus is Red Hat’s Kubernetes-native Java stack (current LTS is 3.33; latest is 3.35). Its selling point is “supersonic subatomic Java”: it pushes work to build time and supports GraalVM native compilation, so you get fast cold starts and a small memory footprint compared to traditional JVM apps. It offers a unified imperative + reactive model (Vert.x/Mutiny under the hood), Hibernate ORM with Panache, first-class OIDC/OAuth2, and standards-based MicroProfile/Jakarta EE APIs.

Quarkus is fully cloud-agnostic at container level. You build a standard OCI image, and it runs identically on AWS (ECS, EKS, App Runner, or Lambda via container images), GCP (Cloud Run, GKE), Azure (AKS), or your own Kubernetes cluster. There’s no vendor-specific runtime lock-in: the same artifact, just a different destination.

It lines up well with the envisioned ASR architecture:

• Kubernetes (AKS) — Quarkus is built for containers; native binaries start in tens of milliseconds, which suits Kubernetes horizontal pod autoscaling and keeps resource use (and cost) down. Deployed via Helm + ArgoCD (GitOps).
• OAuth 2.0 (VAD) — quarkus-oidc is mature as a resource server; Token Exchange and token propagation are available if later phases need them.
• PostgreSQL — first-class via Panache and the reactive PG client.
• External PDP (later phases) — when a separate Policy Decision Point is added in a future phase, Quarkus calls it as an external service over REST; the 2026 architecture does not yet include such a component.
• Security posture — relevant given NIS2/cyber-insurance work: standards-based, regular CVE-patched LTS streams (e.g. the recent CVE-2026-39852 fix).

Option 2: .NET Stack

• Description: Use the .NET ecosystem for implementation.
• Pros: Strong enterprise support, good performance.
• Cons: Does not align as well with Keycloak as the Java-based ecosystem does. Less emphasis on open source in some traditional contexts (though .NET Core is open source).

Option 3: Clojure Stack

• Description: Use Clojure for implementation. Used in living labs.
• Pros: Concise, powerful functional programming.
• Cons: Not in common use compared to the other options, which might make staffing and long-term maintenance more challenging. Does not fit the “common use” criteria as well as Quarkus.

Decision Outcome

Chosen option: Option 1: Quarkus, PostgreSQL, and Keycloak.

Component	Technology	Summary
Runtime/Framework	Quarkus	Java-based framework optimized for cloud-native and serverless environments.
Database	PostgreSQL	Robust, open-source relational database for structured data.
Schema migration	Liquibase	Open-source, dialect-portable schema migrations (YAML changesets) owning the DB schema across dev/test/prod. Detailed rationale in TDR-0001.
IAM	Keycloak	Open-source identity and access management for authentication and authorization.
Code formatting	Spotless (Eclipse JDT profile)	Build-enforced Java formatting via spotless-maven-plugin driving a shared Eclipse JDT profile consumed by all IDEs; CI gate fails on unformatted code. First adopted in asr-service. Detailed rationale in ADR-00018.

Rationale

Keycloak is selected based on successful results from previous living labs. To complement this, we chose Quarkus and PostgreSQL because they align well with Keycloak’s architecture and deployment patterns. This choice reflects our core principles:

• It is entirely open source.
• It enjoys broad adoption in the enterprise Java ecosystem.
• It promotes uniformity by aligning with the tools used in our IAM solution.

By defining this as the preferred stack, we establish a standard path while still allowing for alternative implementations if specific requirements necessitate them, as long as they maintain compatibility with the broader system.

Consequences

• Positive:
  • Alignment across different components and teams.
  • Reduced rework when moving functionality.
  • Leverages existing experience from living labs.
  • Strong integration between IAM, database, and runtime.
• Negative:
  • Teams must be proficient in the Java/Quarkus ecosystem.
• Neutral:
  • This ADR will be extended over time as the stack evolves or more specific components are added.

Implementation Plan

1. Phase 1: Update project documentation and initial scaffolding to reflect the preferred stack.
2. Phase 2: Implement core services using Quarkus and PostgreSQL, integrating with Keycloak.
3. Phase 3: Extend this ADR with more specific guidelines as implementation progresses.

Compliance and Validation

• Security review completed
• Performance impact assessed
• Integration impact evaluated
• Documentation updated
• Stakeholder approval obtained

Related Documents

• TDR-0001 — Liquibase owns the database schema (the schema-migration choice in the stack table)
• ADR-00018 — Build-enforced Java formatting via Spotless (the code-formatting choice in the stack table)

Status History

Date	Status	Notes
2026-05-28	Proposed	Initial proposal
2026-05-29	Approved	Approved by CTN Project Team
2026-06-13	Approved	Extended (per Phase 3 / “extended over time”): added Liquibase as the schema-migration component — see TDR-0001
2026-06-24	Approved	Extended (per Phase 3 / “extended over time”): added Spotless as the code-formatting component — see ADR-00018