Documentation Index
Fetch the complete documentation index at: https://grantmaster.dev/llms.txt
Use this file to discover all available pages before exploring further.
EventBus Gap Report
This document catalogues all known places in GrantMaster where the EventBus Rule (emit events for significant transactional data changes) is not satisfied. Each gap was identified during the feature-level documentation pass in March 2026.
EventBus Rule (from base-service-and-eventbus.md): Services MUST emit EventBus events for approval/rejection workflows, entity lifecycle events, critical business thresholds, compliance and audit events, and submission events requiring manager attention.
Gaps are grouped by domain, ordered by business impact (high → low).
Priority: High — Audit & Compliance Impact
1. grantors — No Funder Relationship Events
File: src/features/grantors/services/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
GRANTOR_INTERACTION_LOGGED | createInteraction() | Compliance audit trail for funder engagement |
GRANTOR_FOLLOW_UP_COMPLETED | completeFollowUp() | Relationship health tracking |
GRANTOR_DEADLINE_CREATED | createDeadline() | Deadline pipeline for compliance monitoring |
GRANTOR_DEADLINE_COMPLETED | completeDeadline() | Compliance close-out event |
GRANTOR_ENGAGEMENT_CHANGED | calculateEngagementScore() when level changes | Risk escalation trigger |
GrantorRelationshipService, ReportingCalendarService
Impact if missing: Compliance auditors cannot reconstruct funder engagement history from the EventBus; they must rely on auditLogs alone.
File: src/features/relations/services/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
CONTACT_CREATED | createContact() | CRM audit trail |
CONTACT_INTERACTION_LOGGED | logInteraction() | Engagement history |
CONTACT_SEGMENT_UPDATED | evaluateContactSegments() when segments change | Downstream marketing/comms triggers |
contactService, segmentService
Impact if missing: No EventBus-sourced audit trail for contact management; no ability for downstream modules to react to CRM changes.
3. settings — No Policy Change Events
File: src/features/settings/services/settingsCanonical.ts and src/shared/auth/securityPolicyService.ts
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
SECURITY_POLICY_UPDATED | MFA/password/session policy change | Compliance audit requirement |
APPROVAL_ROUTING_CHANGED | Approval threshold or approver assignment change | Affects audit chain integrity |
NOTIFICATION_PREFERENCES_UPDATED | Org-wide notification setting change | Low priority — informational only |
securityPolicyService.updateMfaPolicy(), settingsCanonical.ts approval routing changes
Impact if missing: Security policy changes are invisible to the EventBus. Auditors cannot detect if MFA was disabled or approval thresholds were lowered.
Priority: Medium — Business Process Integrity
4. partnerships — No Partnership Lifecycle Events
File: src/shared/partnerships/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
PARTNER_JOINED | PartnerInvitationService.acceptInvitation() | Partnership onboarding audit |
REFERRAL_CREDIT_AWARDED | ReferralCreditService.awardReferralCredits() | Credit accounting audit trail |
REVENUE_SHARE_PAID | RevenueShareService.markPayoutComplete() | Financial reconciliation |
PartnerInvitationService, ReferralCreditService, RevenueShareService
Impact if missing: Partnership and credit events are only traceable via Postmark emails — no in-system event history.
5. workflows — No Workflow Lifecycle Events
File: src/features/workflows/services/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
WORKFLOW_CREATED | New task/approval chain created | Visibility into operational workload |
WORKFLOW_TASK_COMPLETED | Individual task completed | Progress tracking |
WORKFLOW_APPROVAL_REQUESTED | Approval step triggered | Audit trail for approval chains |
WORKFLOW_COMPLETED | All steps done | Business process completion |
WORKFLOW_OVERDUE | Deadline passed without completion | Escalation trigger |
workflowService, taskExecutionService
Impact if missing: The workflows feature is purely a consumer and executor; it produces no observable events. Other features (compliance, reports) cannot react to workflow completions.
6. reports — No Report Generation Events
File: src/features/reports/services/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
REPORT_GENERATED | Report created or exported | Template usage tracking (required by EventBus rule) |
REPORT_SCHEDULED | Automated report configured | Auditability of reporting cadence |
REPORT_SHARED | Report distributed to external party | Compliance disclosure audit |
reportGenerationService, reportSchedulerService
Impact if missing: Report generation is unobservable. The EventBus rule explicitly calls out template usage as a required emission trigger.
Priority: Low — Operational Observability
7. auth — No API Key or Session Policy Events
File: src/shared/auth/apiKeyService.ts, src/shared/auth/securityPolicyService.ts
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
API_KEY_CREATED | createApiKey() | Security audit trail |
API_KEY_ROTATED | rotateApiKey() | Key lifecycle tracking |
API_KEY_REVOKED | revokeApiKey() | Immediate security event |
API_KEY_REVOKED may warrant High priority if used for emergency key invalidation.
Where to add: apiKeyService — each lifecycle method.
8. integrations — No Third-Party Sync Events
File: src/shared/integrations/hubspot/, src/shared/integrations/xero/
Missing events:
| Suggested Event | Trigger | Why It Matters |
|---|
HUBSPOT_SYNC_COMPLETED | HubSpotSyncService.runFullSync() | Sync health monitoring |
HUBSPOT_SYNC_FAILED | Sync error | Error alerting |
XERO_SYNC_FAILED | Xero sync error | Financial data integrity alert |
WEBHOOK_DELIVERY_FAILED | Outbound webhook failure | Integration reliability tracking |
HubSpotSyncService, XeroAuthService, integrationService.logWebhookEvent()
Implementation Notes
When adding missing events:
- Use
emitCanonicalSystemEvent() from src/shared/events/canonicalEventEmitter.ts — not raw eventBus.emit().
- Add the new event type to
SystemEventType in @grantmaster/shared/events.
- Add the payload type to
EventPayloadMap in src/shared/events/canonicalEventMap.ts.
- Register a canonical consumer in
src/shared/events/canonicalConsumers.ts if a downstream service should react.
- Emit after the Firestore write succeeds — never before (to avoid phantom events on failure).
- Use
EventSeverity.INFO for lifecycle events, EventSeverity.WARNING for threshold/policy events, EventSeverity.CRITICAL for security events.
See shared/events API reference for the full emission pattern.
Summary Table
| Domain | Missing Events | Priority | Effort |
|---|
grantors | 5 events | High | Medium |
relations | 3 events | High | Low |
settings / auth/security | 3 events | High | Low |
partnerships | 3 events | Medium | Low |
workflows | 5 events | Medium | Medium |
reports | 3 events | Medium | Low |
auth/apiKeyService | 3 events | Low–High | Low |
integrations | 4 events | Low | Medium |
| Total | 29 events | | |
