Version: V2-Next

ADR 041: Revised Topic Naming Convention for Configuration Events

Date: 2026-03-26

Status: To Be Reviewed

Decision Makers: Architecture Board

Context

ADR 021 established the initial topic naming convention for configuration events on the Kafka message bus. The original convention used the prefix ccc (CIVITAS Core Configuration) followed by a tenant identifier, domain, entity, and operation/event:

ccc.<tenant>.<domain>.<entity>.<operation|event>

During implementation, the naming convention evolved to better align with established conventions in the Java/Kafka ecosystem and to reduce unnecessary complexity. The changes were driven by the following observations:

Reverse domain name convention: The Java ecosystem and CloudEvents specification use reverse domain names as identifiers. Using de.civitascore as a prefix aligns the topic namespace with the CloudEvents type attribute convention and makes the origin of events unambiguous across systems.
Tenant segment removed: The original convention included a tenant segment in the topic name. In practice, tenant isolation is handled at the Kafka cluster or ACL level, not by encoding the tenant into every topic name. Removing the tenant segment simplifies topic names and avoids an unnecessarily deep hierarchy.
Confirmation events only: The implemented convention uses exclusively past-tense event names (e.g., user.created, route.deleted). Command topics (imperative form) are not part of the configuration event namespace. This reflects the actual event-driven architecture where configuration events represent state changes that have already occurred.
Composite event types: Some events require multi-part event names (e.g., password.changed, password.reset). The convention supports dot-separated sub-segments for the event type, which was not explicitly defined in ADR 021.

The revised convention is already in use across all implemented configuration adapters and the Portal Backend.

Checked Architecture Principles

[full] Model-centric data flow
[full] Distributed architecture with unified user experience
[full] Modular design
[full] Integration capability through defined interfaces
[full] Open source as the default
[full] Cloud-native architecture
[full] Prefer standard solutions over custom development -- reverse domain naming is a widely adopted convention
[full] Self-contained deployment
[full] Technological consistency to ensure maintainability -- consistent with CloudEvents and Java conventions
[full] Multi-tenancy -- tenant isolation via cluster/ACL level, not topic naming
[full] Security by design

Decision

The topic naming convention for configuration events defined in ADR 021 is revised as follows.

Revised Convention

Configuration event topics use the reverse domain prefix de.civitascore, followed by the platform domain, entity, and event type:

de.civitascore.<domain>.<entity>.<event>

Segment	Description	Examples
`de.civitascore`	Fixed platform prefix (reverse domain)	--
`<domain>`	Platform domain (lowercase abbreviation)	`idm`, `api`, `data`
`<entity>`	Platform entity (lowercase, no separators)	`user`, `realm`, `backend`, `route`, `project`
`<event>`	Event type (past tense, dot-separated for composites)	`created`, `updated`, `deleted`, `password.changed`

Changes Compared to ADR 021

Aspect	ADR 021	This ADR
Prefix	`ccc`	`de.civitascore`
Tenant segment	Included (`<tenant>`)	Removed -- tenant isolation via cluster/ACL
Topic types	Operations (imperative) and confirmations (past tense)	Confirmation events only (past tense)
Composite events	Not defined	Supported via dot-separated sub-segments (e.g., `password.changed`)
Domain naming	`idm`, `apim`, `geodata`	`idm`, `api`, `data` (shortened where applicable)

Configuration Event Domains

Domain	Abbreviation	Entities
Identity Management	`idm`	`user`, `realm`, `client`, `group`, `role`
API Management	`api`	`backend`, `route`
Data Management	`data`	`thing`, `location`, `sensor`, `observedproperty`, `datastream`, `project`, `pipeline`

Examples

de.civitascore.idm.user.created
de.civitascore.idm.user.deleted
de.civitascore.idm.user.password.changed
de.civitascore.idm.user.password.reset
de.civitascore.idm.realm.created
de.civitascore.idm.client.updated
de.civitascore.idm.group.deleted
de.civitascore.idm.role.created
de.civitascore.api.backend.created
de.civitascore.api.route.deleted
de.civitascore.data.project.created
de.civitascore.data.pipeline.deleted
de.civitascore.data.sensor.updated

Extending the Event Catalog

New configuration events follow the same convention:

Identify or define the domain abbreviation
Define the entity name (lowercase, no separators)
Use past tense for the event type
Use dot-separated segments for composite event types

Unchanged from ADR 021

The following aspects of ADR 021 remain in effect and are not modified by this ADR:

CloudEvents envelope: Configuration events continue to use the CloudEvents standard as the message envelope (ADR 013)
JSON payloads: Event payloads are JSON structures containing only the data required for the event
SDK requirement: All producers and consumers must use the official CloudEvents SDKs

Consequences

All existing configuration event topics already follow the revised convention. No migration is required.
New configuration events must use the de.civitascore.<domain>.<entity>.<event> format.
The ccc.* prefix from ADR 021 is deprecated and must not be used for new topics.
Topic-level ACL rules can use de.civitascore.* as a wildcard base for all configuration events, and de.civitascore.<domain>.* for domain-scoped access.
The removal of the tenant segment from topic names requires that tenant isolation is enforced at the Kafka cluster or ACL level.

Alternatives

Keep ADR 021 convention unchanged: Rejected because the implementation has already diverged, and the revised convention offers concrete advantages (ecosystem alignment, simpler names, clearer scoping).
Introduce a new prefix while keeping ccc.*: Rejected to avoid maintaining two parallel naming conventions.

Context​

Checked Architecture Principles​

Decision​

Revised Convention​

Changes Compared to ADR 021​

Configuration Event Domains​

Examples​

Extending the Event Catalog​

Unchanged from ADR 021​

Consequences​

Alternatives​

See also​