Topic Name Handling

Overview

Every Mindbricks service communicates through Kafka topics. Topics are generated automatically from your data model and business APIs, following strict naming conventions. While these full topic names are stable and predictable, they can be long and hard to remember when configuring Kafka controllers, event listeners, or cross-service communication.

Topic aliases let you reference topics using short, intention-revealing names like createUser:done or user:created instead of their full form my-project-auth-service-user-created. Aliases are resolved both at design time (during code generation) and at runtime (when publishing or consuming messages).

Topic Naming Conventions

Mindbricks generates two categories of Kafka topics per service:

API-Level Event Topics

When a Business API has event raising enabled, it publishes to a topic named:

<serviceCodename>-<resourceName>-<passiveAction>

Examples:

DB-Level Event Topics

Every DataObject automatically emits low-level database events (create, update, delete) to topics named:

<serviceCodename>-dbevent-<objectName>-<passiveAction>

Examples:

DB-level events fire on every database mutation, regardless of whether a Business API triggered it. API-level events only fire when a specific Business API completes.

Topic Aliases

Instead of typing full topic names, you can use short aliases anywhere a topic name is expected — in Kafka controller configuration, SSE progress listeners, PublishEventAction topics, RealtimeHub Kafka bridges, or runtime publish/subscribe calls.

Alias Format

An alias consists of one, two, or three segments separated by a delimiter:

<asset>
<asset><delimiter><event>
dbEvent<delimiter><asset><delimiter><event>

Supported delimiters: : . _

All aliases are case-insensitive. CreateUser:Done, createuser:done, and CREATEUSER:DONE all resolve identically.

Alias Resolution Rules

1. Single API Name

The simplest alias — just the API name with no event qualifier. Resolves to the API's default event topic.

Single data object names (e.g., just user) do not resolve because the intended action is ambiguous.

2. API Name + Completion Keyword

When the first segment matches a Business API name and the second segment is a completion keyword, the alias resolves to that API's main event topic.

Completion keywords: done, executed, ended, finished, completed

3. API Name + Own Action

When the second segment is the passive form of the API's own action, it resolves to the API's event topic.

4. DataObject/Resource + Standard Action

When the first segment matches a DataObject or API resource name and the second segment is a standard CRUD action in passive form:

The resolver follows a priority chain:

1. Direct resource-action match — If a Business API's resource name matches the asset and its passive action matches the event, use the API's event topic.

2. Object + CRUD type match (create/delete only) — If the asset matches a DataObject that an API operates on, and the action's CRUD type matches, use that API's topic. This only applies to created and deleted because creates and deletes are unambiguous.

3. DB-level event fallback — If the DataObject exists but no API match was found (or the action is updated), fall back to the DB-level event topic.

5. DataObject + Non-Standard Action

When the action is not a standard CRUD passive form, the resolver checks if any Business API that operates on the same DataObject has a matching action.

Explicit DB Event Override

Sometimes you want to listen to the raw database event even when an API-level event exists. Prefix the alias with dbEvent to force DB-level resolution, bypassing all API matching.

Three-Segment Form: dbEvent:asset:action

The asset can also be an API name. The resolver finds the API's underlying DataObject and returns its DB event:

Two-Segment Form: dbEvent:apiName

Shorthand for the API's default action at the DB level:

Cross-Service Resolution

Aliases are not limited to the current service. If the asset or API name doesn't match anything in the local service, the resolver searches all services in the project.

The local service is always checked first. If a name exists in both the local and a remote service, the local service wins.

Where Aliases Work

Aliases are resolved in the following places:

Design Time (Code Generation)

During code generation, the Mindbricks genesis engine resolves aliases in all topic-related configuration fields:

The resolved topic name replaces the alias in the generated code. The original alias is preserved in an originalTopic field for debugging.

Runtime (Generated Code)

The generated code includes a runtime alias resolver module (topic-alias-resolver.js) that contains a pre-computed lookup map of all aliases across the project. This module is used in:

• ServicePublisher — resolves the topic before publishing any Kafka message.
• KafkaListener — resolves the topic before subscribing to a consumer.
• kafka.js sendMessageToKafka — resolves the topic on every send call.

This means even if application code passes an alias to a publish or subscribe function at runtime, it will be transparently resolved to the real topic name.

Real Topic Names Pass Through

If you provide a full topic name (e.g., myapp-auth-service-user-created) instead of an alias, the resolver returns it unchanged. Multi-segment hyphenated strings that don't match any alias are treated as literal topic names.

Quick Reference

Delimiter options: : . _ — all are equivalent. Use whichever reads best in your context.

Case: All lookups are case-insensitive. CreateUser:Done = createuser:done = CREATEUSER:DONE.

Cross-service: All formats work across services within the same project. Local service matches take priority.