Event Bus Architecture — Overview
internal engineering docs
A service publishes a business event over HTTP; it arrives as a table anyone with the right to see it can query. The detailed design — the full authentication path, the policy source, the commit protocol, the schema rules — lives in six documents in the Event Bus repository, linked at the bottom. This page is the shape only, so there is one source and not two.
What the picture says
The identity never changes hands. The publish path is HTTP, but the endpoint forwards the caller's token to Kafka untouched, so the broker authorizes the actual publisher rather than the proxy. Nothing in the chain re-signs, substitutes, or pools identities into a shared service account.
Authorization is decided once. The broker is the only enforcement point, and it asks a policy engine sitting beside it. There is no second place where access is also decided, so there is no second place that can drift out of step.
The control plane is git. Every fact about a topic — its schema, who may publish, who may read — lives in one file. The schemas, the authorization data and the landing tables are all generated from that file, never hand-edited, and every change goes through a merge request. The policy itself contains no service names at all; names live in data.
Landing is exactly once. The sink commits events and offsets in one transaction, so a crash mid-write neither duplicates nor drops.
Known limitations
These are the four the team decided a reader should know before trusting anything else. They are recorded here in the same words the source documents use — not softened.
| Limitation | |
|---|---|
| 🔴 | Schema validation can be bypassed. Whether validation happens is decided by the caller's Content-Type, and there is no server-side setting that forces it. This is an accepted risk, paid for with a dead-letter queue and reconciliation rather than prevented. |
| 🔴 | The broker healthcheck lies. It runs on the internal listener as a super user and short-circuits before the authorizer is consulted. Measured: with authorization completely broken and every request being denied, the broker still reported healthy. Monitoring that watches only broker health will not see that failure. |
| 🔴 | Revocation is not immediate. A security incident cannot be handled by changing authorization data alone — the credential itself has to be dealt with. |
| 🔴 | An unregistered consumer group is silent on assign-type consumers. A client that assigns its own partitions keeps receiving data and looks healthy; only the offset write-back fails, as a warning. The group does not exist on the broker at all, so lag monitoring is blind and a restart replays from the beginning. |
On silent data loss. Two shapes used to lose content between Kafka and the table with no error, no dead-letter entry, and reconciliation totals that still added up: free-form JSON, and keys the schema never declared. Both are now rejected at the control plane before they can reach a topic — which is why they are no longer in the list above. 🔴 This is not the same as the risk being gone. The defence is a single lint rule, it can be waived, and a waiver is a property of the control plane rather than of the cluster: nothing at the broker or at landing time will stop a waived topic from dropping content silently. The other way to lose data silently is an operational action, described in the commit-protocol document.
Where the work is
| Item | Milestones |
|---|---|
| 28 · Event Bus (Kafka) | data platform milestones |
Carrying events between the three sites is part of this item too — the mirroring, the per-site landing, and the lag monitoring that has to be in place before the first edge carries traffic. See the data platform architecture for how that fits the three-site shape.
The six documents
Verified against a running system, not inferred from vendor documentation. Last verified 2026-08-27.
- Overview — the entry point: what the system does and which document answers what
- Publish and consume — authentication: a private key becomes a token, and the token reaches the broker intact
- Authorization — the policy and its three data files, how one query is evaluated, and revocation delay
- From topic to table — what one landing line is made of and how every name is derived
- Commit protocol — how exactly-once is actually achieved, and what happens when storage fails mid-write
- Schema guide — the six rules for writing one, how to change one, and where the three type systems disagree