Skip to main content

Architecture — Event Bus Map

LumisCare Event Bus — Current State Map

Date: 2026-04-04 Author: Martin Kleppmann (Distributed Systems Audit) Method: Static analysis of all publisher and listener classes in backend/services/ Source of truth: Actual Java source files, not design documents

Architecture

Azure Service Bus Premium tier, topics/subscriptions model. Each service owns its own topic and publishes events to it. Consumers subscribe to specific topics with SQL filters on event_type.

The design document (Service-Bus-Subscriptions-Design.md) specifies three topics: visit-events, schedule-events, notification-events. The actual implementation has diverged — publishers use five distinct topic names across six services, and the notification-service listener is wired to a different topic (domain-events) than what the visit and scheduling publishers write to.

Event Flow Diagram

graph LR
  subgraph WIRED["FULLY WIRED"]
    HR["hr-service<br/>(HrEventPublisher)"]
    SCHED["scheduling-service<br/>(AppointmentEventPublisher)"]
    SCHED_AVAIL["scheduling-service<br/>(HrAvailabilityUpdatedEventHandler)"]
    NOTIF_PUB["notification-service<br/>(NotificationEventPublisher)"]
  end

  subgraph PARTIAL["PARTIALLY WIRED — publisher exists, consumer absent or mis-wired"]
    VISITS["visits-service<br/>(VisitEventPublisher)"]
    INCIDENTS["incidents-service<br/>(EventPublisher)"]
    SAFETY["safety-service<br/>(SafetyEventPublisher)"]
    NOTIF_LISTEN["notification-service<br/>(ServiceBusEventListener)"]
    SCHED_CAREPLAN["scheduling-service<br/>(CarePlanPublishedEventHandler)"]
  end

  subgraph BROKEN["BROKEN — no publisher class exists"]
    ASSESS["assessment-service"]
    CAREPLAN["careplan-service"]
    FINANCE["finance-service<br/>(OutboxEvent entity only)"]
  end

  HR -->|"employee.created/updated<br/>availability.updated<br/>leave.approved<br/>certification.expiring<br/>topic: domain-events"| SCHED_AVAIL
  HR -->|"leave.approved<br/>topic: domain-events"| NOTIF_LISTEN
  VISITS -->|"visit.started/completed/missed<br/>visit.task.completed<br/>topic: visits-events"| NOTIF_LISTEN
  VISITS -->|"visit.completed<br/>topic: visits-events"| FINANCE_STUB["finance-service<br/>(NO listener class)"]
  SCHED -->|"schedule.published/updated<br/>appointment.created/updated/cancelled<br/>topic: scheduling-events"| NOTIF_LISTEN
  NOTIF_PUB -->|"notification.sent/failed/acknowledged<br/>topic: notification-events"| ANALYTICS_STUB["analytics-service<br/>(NOT IMPLEMENTED)"]
  INCIDENTS -->|"incident.created<br/>topic: incidents-events"| NOTIF_LISTEN
  SAFETY -->|"lwp.escalation.*<br/>topic: safety-events"| NOTIF_LISTEN
  CAREPLAN_STUB["careplan-service<br/>(NO publisher)"] -.->|"careplan.published — MISSING"| SCHED_CAREPLAN
  ASSESS -.->|"assessment.completed — MISSING"| CAREPLAN_STUB

  style WIRED fill:#1a4731,color:#fff
  style PARTIAL fill:#713f12,color:#fff
  style BROKEN fill:#7f1d1d,color:#fff

Critical Architectural Finding: Topic Name Mismatch

The notification-service ServiceBusEventListener subscribes to topic domain-events (default configured at ServiceBusConfig.java:29):

azure.servicebus.topic-name:domain-events

The visits-service VisitEventPublisher publishes to topic visits-events (default configured at VisitEventPublisher.java:45):

azure.servicebus.visits-topic-name:visits-events

The scheduling-service AppointmentEventPublisher publishes to topic scheduling-events (default configured at AppointmentEventPublisher.java:45):

azure.servicebus.scheduling-topic-name:scheduling-events

The HR-service HrEventPublisher publishes to topic domain-events (default configured at HrEventPublisher.java:40):

azure.servicebus.topic-name:domain-events

This means: the notification-service listener will receive HR events but will silently miss all visit and schedule events at runtime unless the application properties are overridden in deployment configuration. There are no application.properties or application.yml files with explicit topic overrides found in the source tree — only Spring @Value defaults. This must be validated against the actual Azure Container Apps environment variables before treating any visit-to-notification flow as working.

Event-by-Event Status

Event Topic (default) Producer Service Publisher Class Consumer Service Listener Class Status
employee.created domain-events hr-service HrEventPublisher scheduling-service HrAvailabilityUpdatedEventHandler WIRED — both sides present
employee.updated domain-events hr-service HrEventPublisher scheduling-service HrAvailabilityUpdatedEventHandler WIRED — both sides present
availability.updated domain-events hr-service HrEventPublisher (via AvailabilityPreferencesService) scheduling-service HrAvailabilityUpdatedEventHandler (listens for hr.availability.updated) WIRED — subject used in code is hr.availability.updated, design doc says availability.updated — schema mismatch risk
leave.approved domain-events hr-service HrEventPublisher (via LeaveManagementService) notification-service ServiceBusEventListener (case leave.approved) WIRED — both sides on same topic
certification.expiring domain-events hr-service HrEventPublisher (via CertificationExpiryScheduler) notification-service ServiceBusEventListener (case certification.expiring) WIRED — both sides on same topic
visit.started visits-events visits-service VisitEventPublisher.publishVisitStarted() notification-service ServiceBusEventListener (case visit.checkedin — event name mismatch) BROKEN — publisher emits visit.started, listener handles visit.checkedin; different names
visit.completed visits-events visits-service VisitEventPublisher.publishVisitCompleted() notification-service ServiceBusEventListener (case visit.completed) TOPIC MISMATCH — publisher on visits-events, listener on domain-events
visit.completed visits-events visits-service VisitEventPublisher.publishVisitCompleted() finance-service No listener class found NOT WIRED — finance has no Service Bus consumer
visit.missed visits-events visits-service VisitEventPublisher.publishVisitMissed() notification-service No explicit case in listener NOT HANDLED — listener has no visit.missed case
visit.task.completed visits-events visits-service VisitEventPublisher.publishTaskCompleted() notification-service No explicit case in listener NOT HANDLED
checkin.timeout visits-events visits-service NOT FOUND in VisitEventPublisher methods notification-service ServiceBusEventListener (case checkin.timeout) PUBLISHER ABSENT — listener expects this event but publisher has no publishCheckinTimeout() method
assistance.requested visits-events visits-service NOT FOUND in VisitEventPublisher methods notification-service ServiceBusEventListener (case assistance.requested) PUBLISHER ABSENT — listener expects this event but publisher has no method
task.flagged visits-events visits-service NOT FOUND in VisitEventPublisher methods notification-service ServiceBusEventListener (case task.flagged) PUBLISHER ABSENT — listener expects this but only visit.task.completed is published
redflag.detected unknown unknown NOT FOUND notification-service ServiceBusEventListener (case redflag.detected) PUBLISHER ABSENT — no publisher produces this event
visit.reassigned unknown unknown NOT FOUND notification-service ServiceBusEventListener (case visit.reassigned) PUBLISHER ABSENT
schedule.published scheduling-events scheduling-service AppointmentEventPublisher.publishSchedulePublished() notification-service ServiceBusEventListener (case schedule.published) TOPIC MISMATCH — publisher on scheduling-events, listener on domain-events
schedule.updated scheduling-events scheduling-service AppointmentEventPublisher (no explicit publishScheduleUpdated found — has publishScheduleApproved) notification-service ServiceBusEventListener (case not found) PARTIAL — method naming diverges from design doc
careplan.published careplan-events careplan-service NO PUBLISHER CLASS scheduling-service CarePlanPublishedEventHandler (subscribes to careplan-events) BROKEN — listener fully implemented, publisher does not exist
careplan.updated unknown careplan-service NO PUBLISHER CLASS notification-service ServiceBusEventListener (case careplan.updated) BROKEN — no publisher
assessment.completed unknown assessment-service NO PUBLISHER CLASS careplan-service NO LISTENER CLASS NOT WIRED — entire chain absent
incident.created incidents-events incidents-service EventPublisher notification-service ServiceBusEventListener — no incident.created case found in routing switch TOPIC MISMATCH + case absent — publisher on incidents-events, listener on domain-events
lwp.escalation.level1/2/3/4 safety-events safety-service SafetyEventPublisher.publishLWPEscalation() notification-service ServiceBusEventListener (cases lwp.escalation.level1 through level4) TOPIC MISMATCH — publisher on safety-events, listener on domain-events
invoice.created none finance-service NO PUBLISHER — only OutboxEvent entity + repository notification-service ServiceBusEventListener (no case found) NOT WIRED — outbox pattern incomplete, no dispatcher daemon
invoice.paid none finance-service NO PUBLISHER analytics-service NOT IMPLEMENTED NOT WIRED
timesheet.created none finance-service NO PUBLISHER — TimesheetBatchJobProcessor writes OutboxEvent but no Service Bus dispatch notification-service ServiceBusEventListener (no case found) NOT WIRED — outbox records written to DB but no relay to Service Bus
notification.sent notification-events notification-service NotificationEventPublisher.publishNotificationSent() analytics-service NOT IMPLEMENTED PUBLISHER WIRED, consumer service does not exist
notification.failed notification-events notification-service NotificationEventPublisher.publishNotificationFailed() analytics-service NOT IMPLEMENTED PUBLISHER WIRED, consumer service does not exist
daily.summary unknown unknown NOT FOUND notification-service ServiceBusEventListener (case daily.summary) PUBLISHER ABSENT

Broken Chains

Chain 1: Assessment to Care Plan AI Generation (Clinical Safety Risk)

The primary clinical workflow trigger is broken at its first link.

  • assessment-service has no event publisher class anywhere in its source tree. When an assessment is completed, no assessment.completed event is emitted.
  • careplan-service has no event listener class. Even if an event were emitted, nothing would receive it.
  • Both sides of the Assessment → CarePlan trigger are absent.

Where it breaks: assessment-service/src/main/java/ — no *Publisher*.java file exists in this directory.

Chain 2: Care Plan to Scheduling (Scheduling Cannot Start Automatically)

The CarePlanPublishedEventHandler in scheduling-service is fully implemented (300+ lines, idempotency logic, recurring schedule creation). It is waiting for a careplan.published event on topic careplan-events. That event is never published.

  • careplan-service has no publisher class. The service can mark a care plan as published in the database (CarePlan.publishedAt, CarePlan.publishedBy fields exist) but does not emit the event.

Where it breaks: careplan-service/src/main/java/ — no *Publisher*.java file exists. The handler waiting for the event is at scheduling-service/src/main/java/com/lumiscare/scheduling/event/CarePlanPublishedEventHandler.java:101.

Chain 3: Visit Check-in to Notification (Event Name Mismatch)

The design document specifies visit.checkedin. The VisitEventPublisher publishes visit.started (set at VisitEventPublisher.java:127). The ServiceBusEventListener routes on visit.checkedin (at ServiceBusEventListener.java:207). These names do not match. Even if the topic mismatch were fixed, this chain would still silently fail.

Where it breaks:

  • Publisher sets name: VisitEventPublisher.java:127 — "visit.started"
  • Listener routes on: ServiceBusEventListener.java:207 — case "visit.checkedin"

Chain 4: Visit Completed to Finance (Finance Cannot Generate Invoice Line Items)

VisitEventPublisher.publishVisitCompleted() publishes to topic visits-events. The finance-service has no ServiceBusProcessorClient, no listener class, and no subscription configuration. The billing data embedded in the visit.completed payload (rates, task categories, mileage) is never consumed. Invoice line item generation is not automated.

Where it breaks: finance-service/src/main/java/ — no Service Bus consumer class of any kind. Finance only writes OutboxEvent records to its own database for the timesheet batch job, which itself has no Service Bus dispatcher.

Chain 5: Critical Safety Alerts Silently Dropped (Topic Mismatch)

SafetyEventPublisher publishes to topic safety-events. ServiceBusEventListener in notification-service subscribes to topic domain-events. The LWP escalation events (lwp.escalation.level1 through level4) will never reach the notification service unless an application property override is set in deployment. For lone worker protection, this is a CQC compliance risk.

Where it breaks: SafetyEventPublisher.java:39 (topic: safety-events) vs ServiceBusConfig.java:29 (subscribed to: domain-events).

Chain 6: Visit Events Unreachable by Notification Service (Topic Mismatch)

VisitEventPublisher publishes to visits-events. AppointmentEventPublisher publishes to scheduling-events. ServiceBusEventListener subscribes to domain-events. Unless deployment environment variables override these defaults, all visit and schedule events are invisible to the notification service. This silences checkin.timeout, task.flagged, assistance.requested, and schedule.published notifications.

Where it breaks: Topic default misalignment across three services — see Critical Architectural Finding section above.

Chain 7: Events Listened For But Never Published

The ServiceBusEventListener routing switch includes cases for events that have no publisher anywhere in the codebase:

Event Missing Publisher Listener Location
checkin.timeout No publisher method in VisitEventPublisher ServiceBusEventListener.java:207
assistance.requested No publisher method in VisitEventPublisher ServiceBusEventListener.java:211
redflag.detected No publisher anywhere in any service ServiceBusEventListener.java:215
visit.reassigned No publisher anywhere in any service ServiceBusEventListener.java:220
task.flagged No publisher method in VisitEventPublisher (publishes visit.task.completed instead) ServiceBusEventListener.java:224
daily.summary No publisher anywhere in any service ServiceBusEventListener.java:249

Chain 8: Notification Outbound Events Have No Consumers

NotificationEventPublisher publishes notification.sent, notification.failed, and notification.acknowledged to topic notification-events. The analytics-service and audit-service that should consume these are not implemented as standalone services. The events will be published to a topic with no subscribers, age to TTL, and be discarded.

Fix Priority

Ordered by clinical and operational impact.

Priority 1 — Fix Topic Name Coherence (All Services)

Impact: Unblocks all visit and schedule notifications in one config change.

The notification-service ServiceBusConfig must subscribe to multiple topics, or all publishers must align on a shared topic name. The least-invasive fix is to add per-topic subscription processors in ServiceBusConfig.java for visits-events and scheduling-events in addition to domain-events. Alternatively, if the design intent is a single domain-events topic, all publishers must update their @Value defaults to domain-events.

This is a configuration and wiring change, not a logic change. No new business logic required.

Files to change:

  • notification-service/src/main/java/com/lumiscare/notification/config/ServiceBusConfig.java
  • OR all publisher @Value defaults (4 publisher files)

Priority 2 — Fix visit.started / visit.checkedin Event Name

Impact: Allows check-in notifications to reach care managers.

Either rename the event type in VisitEventPublisher.java:127 from "visit.started" to "visit.checkedin", or update the listener case to "visit.started". The design document and listener both say visit.checkedin — the publisher is the outlier.

File to change: visits-service/src/main/java/com/lumiscare/visits/event/VisitEventPublisher.java:127

Priority 3 — Add Missing Publisher Methods to VisitEventPublisher

Impact: Enables checkin.timeout (clinical safety), task.flagged (care quality), assistance.requested (lone worker safety).

VisitEventPublisher needs three new publish methods. The listener routing and notification handlers for these events already exist. This is purely adding publisher-side methods and calling them from the appropriate visit execution service layer.

Events to add: checkin.timeout, task.flagged, assistance.requested File to change: visits-service/src/main/java/com/lumiscare/visits/event/VisitEventPublisher.java

Priority 4 — Add careplan.published Publisher to careplan-service

Impact: Allows scheduling to automatically create recurring visits when a care plan is approved. This is the central automation trigger for care delivery.

The CarePlanPublishedEventHandler in scheduling-service is complete and production-ready. Only the publisher side is missing. Add a publisher class to careplan-service that emits careplan.published on topic careplan-events when a care plan transitions to published status (the state transition already exists in CarePlanMapper.java).

Files to create/change:

  • Create: careplan-service/src/main/java/com/lumiscare/event/CarePlanEventPublisher.java
  • Wire it into the publish endpoint in the careplan service controller

Priority 5 — Add assessment.completed Publisher to assessment-service

Impact: Triggers automatic AI care plan generation after assessment completion.

Create an event publisher in assessment-service and publish assessment.completed when an assessment reaches a completed status. The careplan-service needs a corresponding listener (this does not yet exist either — both sides must be built).

Files to create:

  • assessment-service/src/main/java/.../event/AssessmentEventPublisher.java
  • careplan-service/src/main/java/.../event/AssessmentCompletedEventListener.java

Priority 6 — Add Finance Service Bus Consumer for visit.completed

Impact: Automates invoice line item generation from completed visits.

Add a ServiceBusProcessorClient to finance-service that subscribes to the visits-events topic with filter event_type = 'visit.completed'. The billing data payload already contains all required fields (billing_data section with visit_type, care_types, day_type, travel_time_minutes, mileage_miles).

Files to create:

  • finance-service/src/main/java/.../event/VisitCompletedEventListener.java
  • Wire to existing rate calculation and invoice generation logic

Priority 7 — Complete the Finance Outbox Dispatcher

Impact: Enables timesheet.created and invoice.created notifications.

TimesheetBatchJobProcessor writes OutboxEvent records to the database but the comment in the code (TimesheetBatchJobProcessor.java:35) refers to an "external outbox-processor daemon" that does not exist. Either implement the outbox polling scheduler within the finance-service or replace the outbox pattern with a direct ServiceBusSenderClient call inside the existing transaction.

Files to change:

  • finance-service/src/main/java/com/lumiscare/icon/finance/service/TimesheetBatchJobProcessor.java
  • Optionally create a dedicated outbox publisher component

Priority 8 — Resolve hr.availability.updated vs availability.updated Event Name

Impact: Prevents silent message drops when carer availability changes.

HrAvailabilityUpdatedEventHandler expects message subject hr.availability.updated (at HrAvailabilityUpdatedEventHandler.java:94). HrEventPublisher publishes with event type availability.updated (called at AvailabilityPreferencesService.java:161). This is a subject field mismatch. The handler will silently complete all messages that do not match its expected subject, meaning availability changes will not trigger schedule recomputation.

Files to change: Align the event type string in AvailabilityPreferencesService.java:161 to hr.availability.updated, or update the handler constant at HrAvailabilityUpdatedEventHandler.java:94.

Summary Counts

Category Count
Fully wired event chains (publisher + consumer on matching topic) 3 (employee.created, employee.updated, leave.approved/certification.expiring via domain-events)
Partially wired (publisher exists, consumer absent or topic mismatch) 8
Events listener handles but no publisher produces 6
Events completely absent (no publisher, no consumer) 3 (assessment.completed, invoice.created, invoice.paid)
Publisher classes that exist 6 (HrEventPublisher, VisitEventPublisher, AppointmentEventPublisher, NotificationEventPublisher, SafetyEventPublisher, incidents EventPublisher)
Publisher classes missing 2 (assessment-service, careplan-service)
Services with no Service Bus integration at all 3 (assessment-service, careplan-service, finance-service consumer side)
Topic name mismatches between publisher default and notification-service subscription 3 (visits-events, scheduling-events, incidents-events, safety-events vs domain-events)

The HR to Notification chain (leave.approved, certification.expiring) is the only end-to-end path that works without deployment configuration overrides. Everything that involves visit execution events, schedule events, or safety escalations depends on either a topic name fix or missing publisher code.

Back to top