Skip to main content

Documentation Index

Fetch the complete documentation index at: https://grantmaster.dev/llms.txt

Use this file to discover all available pages before exploring further.

​
shared/events

The canonical EventBus emission and projection infrastructure. This module wraps the raw IEventBus.emit() with type-safe helpers, schema validation, status projections, and test coverage tooling.

​
Module Map

FileRole
canonicalEventEmitter.tsPrimary entry point — emitCanonicalSystemEvent(input)
canonicalEventMap.tsMaps SystemEventType → payload type at compile time
canonicalEventSchema.tsZod schemas for every event payload
canonicalConsumers.tsDefault consumer registrations (status projections, audit log)
canonicalStatus.tsComputes domain status from event history
canonicalStatusSummary.tsAggregate status across multiple entities
canonicalProjectionHealth.tsHealth checks for projection consistency
canonicalEventVersion.tsVersion negotiation for event schema evolution
index.tsRe-exports emitCanonicalSystemEvent as shared/events default export

​
Primary API

import { emitCanonicalSystemEvent } from '@/shared/events';

// Emit a typed event (used by domain services)
await emitCanonicalSystemEvent({
  eventBus,                               // IEventBus instance (injected via DI)
  type: SystemEventType.PROJECT_CREATED,
  organizationId: 'org123',
  userId: 'user456',
  severity: EventSeverity.INFO,
  payload: { projectId: 'proj789', projectName: 'Grant Alpha' },
  source: 'ProjectService.createProject',
  correlationId: 'req-abc123',            // optional: traces related events
});
The helper enforces: consistent metadata.source, metadata.version: '1.0.0', metadata.correlationId, and timestamp.

​
Type Safety

canonicalEventMap.ts maps every SystemEventType to its payload interface, enforced at compile time: 
type EventPayloadMap = {
  [SystemEventType.PROJECT_CREATED]: ProjectCreatedPayload;
  [SystemEventType.EXPENSE_APPROVED]: ExpenseApprovedPayload;
  // ... 100+ event types
};
emitCanonicalSystemEvent<E extends keyof EventPayloadMap> constrains the payload parameter to the correct type for the given type.

​
Schema Validation

canonicalEventSchema.ts provides Zod schemas for every event payload. Used during:
  • SuperAdmin EventBus monitor (validates persisted events from Firestore)
  • Integration tests in canonicalEventSchema.test.ts

​
Status Projections

canonicalStatus.ts derives an entity’s current status by replaying its event history: 
// Derive current grant status from its event history
const status = deriveGrantStatus(events);  // e.g., 'active' | 'completed' | 'rejected'
canonicalStatusSummary.ts aggregates statuses across a collection for dashboard cards.

​
Canonical Consumers

canonicalConsumers.ts registers the default subscriptions that run for every organization:
  • Audit log writer — persists all events to auditLogs collection
  • Status projection updater — updates cached status documents on lifecycle events
  • Notification trigger — dispatches notifications for approval/rejection events
These consumers are registered at app startup via initCanonicalConsumers().