Skip to main content
Version: V2-Next

Topic Configuration

Configuration Event Topics​

Configuration events use the reverse domain name prefix de.civitascore followed by domain, entity, and event type. All configuration events are confirmation events (past tense), indicating that a state change has occurred.

Structure​

de.civitascore.<domain>.<entity>.<event>
SegmentDescriptionExamples
de.civitascoreFixed platform prefix (reverse domain)--
<domain>Platform domainidm, api, data
<entity>Platform entityuser, realm, backend, route, project
<event>Event type (past tense)created, updated, deleted

Segments are concatenated with dots (.). The total topic name must not exceed 249 characters (Kafka limit).

Domains and Events​

Identity Management (idm)​

EntityEvents
usercreated, updated, deleted, locked, unlocked, password.changed, password.reset
realmcreated, updated, deleted
clientcreated, updated, deleted
groupcreated, updated, deleted
rolecreated, updated, deleted

Examples:

de.civitascore.idm.user.created
de.civitascore.idm.user.updated
de.civitascore.idm.user.deleted
de.civitascore.idm.user.locked
de.civitascore.idm.user.unlocked
de.civitascore.idm.user.password.changed
de.civitascore.idm.user.password.reset
de.civitascore.idm.realm.created
de.civitascore.idm.client.deleted
de.civitascore.idm.group.created
de.civitascore.idm.role.updated

API Management (api)​

EntityEvents
backendcreated, updated, deleted
routecreated, updated, deleted

Examples:

de.civitascore.api.backend.created
de.civitascore.api.route.updated

Data Management (data)​

EntityEvents
thingcreated, updated, deleted
locationcreated, updated, deleted
sensorcreated, updated, deleted
observedpropertycreated, updated, deleted
datastreamcreated, updated, deleted
projectcreated, updated, deleted
pipelinecreated, updated, deleted

Examples:

de.civitascore.data.thing.created
de.civitascore.data.sensor.updated
de.civitascore.data.project.created
de.civitascore.data.pipeline.deleted

Extending the Event Catalog​

New configuration events follow the same convention:

  1. Identify the domain (idm, api, data, or a new domain abbreviation)
  2. Define the entity name (lowercase, no separators)
  3. Use past tense for the event type
  4. Composite operations use dot-separated segments (e.g., password.changed)

Saga / Orchestrator Topics​

Multi-step provisioning workflows use the core.civitas prefix, as defined in ADR 031:

core.civitas.<system>.<entity>.<operation|result>
TopicPublisherSubscriberPurpose
core.civitas.dataset.create.requestedPortal BackendOrchestratorTrigger provisioning
core.civitas.frost.project.createOrchestratorFROST AdapterCreate FROST project
core.civitas.frost.project.deleteOrchestratorFROST AdapterDelete / compensate
core.civitas.frost.project.resultFROST AdapterOrchestratorStep result
core.civitas.apisix.route.createOrchestratorAPISIX AdapterCreate route
core.civitas.apisix.route.resultAPISIX AdapterOrchestratorStep result
core.civitas.dataset.create.completedOrchestratorPortal BackendSaga succeeded
core.civitas.dataset.create.failedOrchestratorPortal BackendSaga failed

Payload Data Topics​

Status: Concept

Payload data topics are not yet implemented. The namespace structure described here is the planned approach, subject to Architecture Board review. See Authorization Concept for the full context.

Payload data (sensor readings, geodata, domain-specific content) uses a separate topic namespace. The platform supports two namespace strategies, selected during installation:

Preferred: Customer Domain Namespace​

Each installation uses the customer's own reverse domain name as the top-level prefix. This provides clear organizational ownership and avoids namespace collisions across installations.

<customer-domain>.<bundle>.<context>.<message-type>

Examples:

de.musterstadt.umwelt.luftqualitaet.raw
de.musterstadt.umwelt.luftqualitaet.enriched
de.musterstadt.verkehr.zaehlstellen.raw
ch.beispielgemeinde.energie.zaehler.validated

The customer domain is configured during platform installation.

Fallback: Platform Namespace​

If no customer domain is available, the platform prefix de.civitascore.data serves as a default namespace.

de.civitascore.data.<bundle>.<context>.<message-type>

Examples:

de.civitascore.data.umwelt.luftqualitaet.raw
de.civitascore.data.verkehr.zaehlstellen.enriched

Namespace Selection​

ScenarioNamespaceExample Prefix
Dedicated installation with known domainCustomer domainde.musterstadt.*
Shared / staging / development environmentPlatform fallbackde.civitascore.data.*

Payload Structure​

Event payloads are JSON structures. Each payload contains only the data required for the operation or event. There is no generic wrapper -- the topic provides the context.

Example: de.civitascore.idm.user.created

{
  "firstname": "Max",
  "lastname": "Mustermann",
  "email": "max.mustermann@civitas-stg.de"
}

The payload is wrapped in a CloudEvents envelope, which provides standardized metadata (source, type, subject, time, etc.) as Kafka message headers.

Access Control​

Topic-level access control follows the least privilege principle:

  • Each component is granted read/write permissions only on the topics it needs
  • Kafka ACLs enforce per-topic authorization
  • The namespace prefix enables wildcard-based ACL rules per category

For the planned authorization model with principal types, permission matrices, and operational governance, see the Authorization Concept.