Event Catalog

This catalog lists every event published by the platform kernel services. Module events are documented in the module's own documentation. All events follow the Event Model envelope format.

To subscribe to a kernel event, a module must declare it in module.manifest.json under events.subscribes[]. Without this declaration, the subscription is rejected with 403 Forbidden.

---

IAM Events

User Created

Published when a new user account is successfully created.

Field	Value
Event	auth.user.created
Publisher	IAM service
Topic	platform.auth.events
Schema version	1.0.0
Partition key	userId

Payload:

{
  "userId":   "01j9pa5mz700000000000000",
  "email":    "[email protected]",
  "tenantId": "01j9p3kz5f00000000000000",
  "roles":    ["member"]
}

Typical subscribers: CRM (create contact), Notify (send welcome email), Audit (log new user).

---

User Logged In

Published on every successful login (password, OAuth, wallet).

Field	Value
Event	auth.user.logged_in
Publisher	IAM service
Topic	platform.auth.events
Schema version	1.0.0
Partition key	userId

Payload:

{
  "userId":    "01j9pa5mz700000000000000",
  "tenantId":  "01j9p3kz5f00000000000000",
  "ip":        "203.0.113.42",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)..."
}

Typical subscribers: Audit (security log), Notify (suspicious login alert).

---

Role Changed

Published when a user's role assignment changes (grant or revoke).

Field	Value
Event	auth.role.changed
Publisher	IAM service
Topic	platform.auth.events
Schema version	1.0.0
Partition key	userId

Payload:

{
  "userId":   "01j9pa5mz700000000000000",
  "oldRoles": ["member"],
  "newRoles": ["member", "moderator"]
}

Typical subscribers: Audit, RBAC cache invalidation consumer.

---

Module Registry Events

Module Registered

Published when a new module is successfully registered in the Module Registry.

Field	Value
Event	module.registry.registered
Publisher	Module Registry
Topic	platform.module.events
Schema version	1.0.0
Partition key	moduleId

Payload:

{
  "moduleId": "01j9pamod100000000000000",
  "name":     "@acme/crm",
  "version":  "1.2.0"
}

---

Module Activated

Published when an installed module is activated for a tenant.

Field	Value
Event	module.registry.activated
Publisher	Module Registry
Topic	platform.module.events
Schema version	1.0.0
Partition key	moduleId

Payload:

{
  "moduleId": "01j9pamod100000000000000"
}

---

Module Deactivated

Published when a module is deactivated for a tenant.

Field	Value
Event	module.registry.deactivated
Publisher	Module Registry
Topic	platform.module.events
Schema version	1.0.0
Partition key	moduleId

Payload:

{
  "moduleId": "01j9pamod100000000000000"
}

---

Money Service Events

Security: money.* events can only be published by the Money Service. Any module attempting to publish these events receives 403 Forbidden. Consumers receiving money.* events must use permanent idempotency deduplication (PostgreSQL processed_event_ids table, not Valkey TTL) because DLQ replay may re-deliver events older than 24 hours.

Wallet Credited

Published when funds are added to a user's wallet.

Field	Value
Event	money.wallet.credited
Publisher	Money Service
Topic	platform.money.events
Schema version	1.0.0
Partition key	userId

Payload:

{
  "txId":        "01j9patx500000000000000",
  "userId":      "01j9pa5mz700000000000000",
  "amountCents": 10000,
  "currency":    "USD"
}

Typical subscribers: Notify (balance update notification), Audit, billing reconciliation.

---

Wallet Debited

Published when funds are deducted from a user's wallet.

Field	Value
Event	money.wallet.debited
Publisher	Money Service
Topic	platform.money.events
Schema version	1.0.0
Partition key	userId

Payload:

{
  "txId":        "01j9patx600000000000000",
  "userId":      "01j9pa5mz700000000000000",
  "amountCents": 2500,
  "currency":    "USD"
}

---

File Storage Events

File Uploaded

Published when a file is successfully uploaded and stored.

Field	Value
Event	files.file.uploaded
Publisher	File Storage service
Topic	platform.files.events
Schema version	1.0.0
Partition key	fileId

Payload:

{
  "fileId": "01j9paf1l000000000000000",
  "userId": "01j9pa5mz700000000000000",
  "bucket": "module-crm-attachments",
  "key":    "tenants/01j9p3kz.../contacts/01j9pa5m.../resume.pdf",
  "size":   204800
}

Typical subscribers: CRM (attach file to contact), Audit, virus scan consumer.

---

Notify Service Events

Notification Sent

Published after a notification is successfully delivered (or attempted) through any channel.

Field	Value
Event	notify.notification.sent
Publisher	Notify Service
Topic	platform.notify.events
Schema version	1.0.0
Partition key	notificationId

Payload:

{
  "notificationId": "01j9panot700000000000000",
  "channel":        "email",
  "userId":         "01j9pa5mz700000000000000"
}

---

Audit Service Events

Audit Record Created

Published when an audit record is written. The Audit Service itself writes to ClickHouse and also publishes this event for downstream consumers (e.g. SIEM integration).

Field	Value
Event	audit.record.created
Publisher	Audit Service
Topic	platform.audit.events
Retention	30 days (not the default 7 days)
Schema version	1.0.0
Partition key	auditId

Payload:

{
  "auditId":  "01j9paaud800000000000000",
  "action":   "auth.user.logged_in",
  "userId":   "01j9pa5mz700000000000000"
}

---

Billing Events

Plan Changed

Published when a tenant upgrades or downgrades their subscription plan.

Field	Value
Event	billing.plan.changed
Publisher	Billing service
Topic	platform.billing.events
Schema version	1.0.0
Partition key	tenantId

Payload:

{
  "tenantId": "01j9p3kz5f00000000000000",
  "oldPlan":  "starter",
  "newPlan":  "professional"
}

Typical subscribers: Module Registry (enable/disable plan-gated features), Notify (plan change confirmation), Audit.

---

Subscription Changed

Published when a subscription status changes (e.g. active → past_due, trialing → active).

Field	Value
Event	billing.subscription.changed
Publisher	Billing service
Topic	platform.billing.events
Schema version	1.0.0
Partition key	tenantId

Payload:

{
  "tenantId":  "01j9p3kz5f00000000000000",
  "oldStatus": "trialing",
  "newStatus": "active"
}

---

Subscribe to Kernel Events

To receive any kernel event in your module, declare it in the manifest:

{
  "events": {
    "subscribes": [
      "auth.user.created",
      "billing.subscription.changed",
      "money.wallet.credited"
    ]
  }
}

Then register a handler:

kernel.events().subscribe('auth.user.created', async (event) => {
  // event.data.userId, event.data.email, event.tenantId, etc.
});

All kernel events are read-only for modules. Modules cannot publish kernel events — any attempt returns 403 Forbidden.

---

Summary

Event	Publisher	Partition key
auth.user.created	IAM	userId
auth.user.logged_in	IAM	userId
auth.role.changed	IAM	userId
module.registry.registered	Module Registry	moduleId
module.registry.activated	Module Registry	moduleId
module.registry.deactivated	Module Registry	moduleId
money.wallet.credited	Money Service	userId
money.wallet.debited	Money Service	userId
files.file.uploaded	File Storage	fileId
notify.notification.sent	Notify Service	notificationId
audit.record.created	Audit Service	auditId
billing.plan.changed	Billing	tenantId
billing.subscription.changed	Billing	tenantId

note

Topic Mapping Topics are completely deterministic and mapped by domain: platform.<domain>.events. For example, all auth.* events are published to platform.auth.events. Check the individual event properties above to confirm exact topic routing.