Generate `Slots` when `PractitionerRole` is updated

[lamurian]

User Story

As a practitioner, I want the system to trigger a background worker to generate or update Slot resources every time my PractitionerRole resource is created or updated so that the system availability accurately and automatically reflects my current schedule.

Description

Currently, changes to a practitioner's availability stored in the PractitionerRole are not automatically reflected as Slot resources. This requires waiting for the daily cron job to execute or when unavailable time trigger is set. We need a reliable mechanism where any creation or update to PractitionerRole with active status emits an event that causes the worker to generate the appropriate Slot resources for that practitioner role.

Key requirements:

• Changes to PractitionerRole (create, update, patch, delete, activation toggles) must cause slot generation.
• Generated Slot resources must be idempotent, consistent, and auditable.
• Existing appointment bookings must be respected (do not delete Slot which status is busy or busy-tentative).

Proposed Flow

• Emit a domain event when PractitionerRole is created, updated, or deleted. The event payload should include practitionerRoleId, practitionerId, timestamp, and a diff/summary of changed availability-related fields (if available).
• Worker consumes the event and performs the following steps atomically where possible:
  • Load the authoritative PractitionerRole and related Practitioner and Location resources.
  • Compute desired Slot set for a configurable window (e.g., next 90 days) using availability rules.
  • Compare computed slots against persisted Slot resources:
    • Upsert new Slots where missing.
    • Update changed Slot metadata (status, start/end) where safe.
    • Delete obsolete Slot only if the status is free.
    • Never delete or override Slots that are linked to confirmed appointments.
  • Persist changes using bulk/batched FHIR operations where available (e.g., transaction bundles).
  • Emit a completion event with counts (created/updated/retired/retained/conflicts) and diagnostics.
• Add monitoring and alerts: Log detailed audit trails that capture inputs, computed slot list, and decisions for conflict cases.
• Document the behavior and provide guidance for practitioners/admins on how changes in PractitionerRole translate into slots and how to request manual regeneration.

Notes:

• Idempotency: ensure each run can be safely re-applied (e.g., include a generationRunId / sourceEventId in Slot metadata) to prevent duplicate slots.
• Concurrency & Ordering: handle concurrent updates to the same PractitionerRole (use event ordering, versioning, or optimistic locking).
• Timezone and DST: compute slots in the practitioner's primary timezone and store slot timestamps in UTC with timezone metadata.
• Appointments: treat Slots with linked confirmed Appointments as immutable; do not remove or convert them without special reconciliation.
• Performance: use batched FHIR transactions for writes and paginate comparisons to avoid memory pressure.

[luckyAkbar]

Mas @lamurian , there is several things I want to ask related to this feature.

Starting from the trigger mechanism. In the desc, only changes to PractitionerRole needs to trigger the Slot regeneration mechanism, however changes to Schedule resource (in the comment field) I think should also be included since update to practitioner's session duration and buffer time also impact the generated Slots.

When a practitioner updates either the buffer time / session duration (in Schedule resource) or daily available time (in PractitionerRole resource) each of them will happen on two different page, the former on profile/edit-practice page and the latter on /profile page. Not only that, all update operations will be sent directly from frontend to FHIR server without preprocessing from backend aside from proxy's auth.

Based on this observation, I found that watching the changes to either PractitionerRole or Schedule as the trigger mechanism for Slots regeneration will become too complex. The backend will also have to implement the watcher in the proxy service, which will make the proxy have multiple jobs at once (violating Single Responsibility Principle).

What I'm suggesting is to create a custom endpoint, provided by the backend, to act as the trigger to Slots regeneration mechanism. When practitioner updates relevant information that affect Slots regeneration, the frontend will first detect whether something is changed or not. If yes, say the practitioner update their availability schedule, the frontend will call the endpoint. The backend will then read the requester information and proceed to perform the Slots regeneration. This way, the backend doesn't need to watch the changes to the relevant resources, doesn't even have to check whether some information has changed or not that require the Slots regeneration mechanism to run. The detail of how the backend perform the Slots regeneration mechanism will be discussed next.

The downside of this approach is the fact that we will need to make changes in the frontend code to make it able to decide whether or not to trigger the Slots regeneration mechanism. Although the changes should be minimal. One more thing as the downside, because the trigger endpoint will be exposed publicly, any practitioner can actually trigger the endpoint unnecessarily. We can make the endpoint can only be triggered by x amount per time range to still allow the practitioner to update their schedule while simultaneously preventing abuse.

What do you think, mas?

[luckyAkbar]

Next thing I want to discuss is Slots regeneration mechanism itself. After the feature has been triggered, either by watching the changes to relevant resources or invoked directly to a specialized endpoint, you want to make the implementation to utilize queue by emitting an event every time this feature is invoked. Is there a specific reason why you choose that way?

One thing to consider when we choose to use queue system is the inherent nature of its asynchronous processing. It can makes Slot regeneration lags thus the practitioner may see their schedule not updated despite already updating it in the settings. From my perspective, I also feel this feature has little potential for high processing load due to the low frequency of changes a practitioner makes to their scheduling system. The relatively low number of users with practitioner roles makes it likely this feature will only be used occasionally. Based on this assumption, this feature will not gain much from utilizing queue service (e.g batch processing, async-retry, etc)

What I want to propose instead is to just make the implementation like an ordinary feature, when invoked, backend process the request directly and returning the result without making the user wait. That way, when the practitioner updates their schedule, it will directly applied (assuming no error happens)

Consider this case:
At 08.00 AM a practitioner just finished a session and the next available Slot is at 08.05 AM. Suddenly, at 08.03 he has an urgent case that makes his assistant update his schedule in the app. If the system uses async processing, the Slot may not get updated until past 08.05 which may permit a patient to books a session with him. Whereas when done synchronously, it should gets updated immediately

[lamurian]

Mas @lamurian , there is several things I want to ask related to this feature.

Starting from the trigger mechanism. In the desc, only changes to PractitionerRole needs to trigger the Slot regeneration mechanism, however changes to Schedule resource (in the comment field) I think should also be included since update to practitioner's session duration and buffer time also impact the generated Slots.

This is well noted Mas @luckyAkbar. You're right that both PractitionerRole and Schedule must be considered as a trigger.

When a practitioner updates either the buffer time / session duration (in Schedule resource) or daily available time (in PractitionerRole resource) each of them will happen on two different page, the former on profile/edit-practice page and the latter on /profile page. Not only that, all update operations will be sent directly from frontend to FHIR server without preprocessing from backend aside from proxy's auth.

Based on this observation, I found that watching the changes to either PractitionerRole or Schedule as the trigger mechanism for Slots regeneration will become too complex. The backend will also have to implement the watcher in the proxy service, which will make the proxy have multiple jobs at once (violating Single Responsibility Principle).

What I'm suggesting is to create a custom endpoint, provided by the backend, to act as the trigger to Slots regeneration mechanism. When practitioner updates relevant information that affect Slots regeneration, the frontend will first detect whether something is changed or not. If yes, say the practitioner update their availability schedule, the frontend will call the endpoint. The backend will then read the requester information and proceed to perform the Slots regeneration. This way, the backend doesn't need to watch the changes to the relevant resources, doesn't even have to check whether some information has changed or not that require the Slots regeneration mechanism to run. The detail of how the backend perform the Slots regeneration mechanism will be discussed next.

I'm also thinking about reducing the complexity from the user's experience Mas. Of course, your approach is a good way to handle the issue from a system standpoint. Another way to handle it is by moving the availability drawer (the one that pops up when we click the Edit Schedule button) to the profile/edit-practice page. The UX should be more fluid that way, and we can localize the trigger to the profile/edit-practice page. API request from this page must then be handled as a bundle request. Therefore, the worker needs to only watch for (a) a Bundle request that contains modifications of a PractitionerRole or Schedule resource; (b) direct single request to modify PractitionerRole and Schedule resource (not bundled).

Please note that in the edit availability drawer the Save Changes button directly send the request to fhir/PractitionerRole endpoint. We need to modify this behavior so that the Save Changes button only save to localStorage and the request will only be made once the user clicks the Save button at the bottom of profile/edit-practice page.

On a second note, I have made several UX improvement to the profile and profile/edit-practice pages, which significantly improve the flow. However, if you think that we can tweak the visual appearance further to make it more intuitive to the user, I'd be happy to hear your suggestions.

The downside of this approach is the fact that we will need to make changes in the frontend code to make it able to decide whether or not to trigger the Slots regeneration mechanism. Although the changes should be minimal. One more thing as the downside, because the trigger endpoint will be exposed publicly, any practitioner can actually trigger the endpoint unnecessarily. We can make the endpoint can only be triggered by x amount per time range to still allow the practitioner to update their schedule while simultaneously preventing abuse.

I think using my proposed approach would be safer Mas Lucky, because it should be more straightforward to enforce ownership check for each resources as the first step to prevent abuse. Moreover, gatekeeping the trigger-activation frequency as you proposed should also be feasible with my proposal. Wdyt Mas?

---

Next thing I want to discuss is Slots regeneration mechanism itself. After the feature has been triggered, either by watching the changes to relevant resources or invoked directly to a specialized endpoint, you want to make the implementation to utilize queue by emitting an event every time this feature is invoked. Is there a specific reason why you choose that way?

Pain point: In our current implementation, the practitioner needs to wait 1x24 hours to have their schedule configured. It means that after onboarding the practitioners, they can't directly use the system to help them manage their work. It will become an operational blocker for the clinic when a new practitioner is registered to Konsulin. This practitioner won't be able to accept booking through Konsulin on the day their joining date. Then the clinic will have two options: let the practitioner work on the next day, or temporarily not using Konsulin's system to manage booking. Neither of those options are practical.

My objective is to provide a snappy mechanism, where if a practitioner update their availability, it is directly reflected on the appointment booking system. We should aim to have a service level agreement (SLA) that's on par with Cal.com or Calendly, where changes in availability is directly reflected within seconds. This is the response I received from our Deepwiki Mas, do you think this is workable?

One thing to consider when we choose to use queue system is the inherent nature of its asynchronous processing. It can makes Slot regeneration lags thus the practitioner may see their schedule not updated despite already updating it in the settings. From my perspective, I also feel this feature has little potential for high processing load due to the low frequency of changes a practitioner makes to their scheduling system. The relatively low number of users with practitioner roles makes it likely this feature will only be used occasionally. Based on this assumption, this feature will not gain much from utilizing queue service (e.g batch processing, async-retry, etc)

Now that I think about it again, I'm sure that we don't need an asynchronous process. I agree that there's not much to gain by utilizing the queue service. I'll update the description accordingly and remove any parts mentioning queue mechanisms.

What I want to propose instead is to just make the implementation like an ordinary feature, when invoked, backend process the request directly and returning the result without making the user wait. That way, when the practitioner updates their schedule, it will directly applied (assuming no error happens)

Consider this case: At 08.00 AM a practitioner just finished a session and the next available Slot is at 08.05 AM. Suddenly, at 08.03 he has an urgent case that makes his assistant update his schedule in the app. If the system uses async processing, the Slot may not get updated until past 08.05 which may permit a patient to books a session with him. Whereas when done synchronously, it should gets updated immediately

Yes, I completely agree with your points here Mas 🙌🏻

[luckyAkbar]

Pain point: In our current implementation, the practitioner needs to wait 1x24 hours to have their schedule configured. It means that after onboarding the practitioners, they can't directly use the system to help them manage their work. It will become an operational blocker for the clinic when a new practitioner is registered to Konsulin. This practitioner won't be able to accept booking through Konsulin on the day their joining date. Then the clinic will have two options: let the practitioner work on the next day, or temporarily not using Konsulin's system to manage booking. Neither of those options are practical.

My objective is to provide a snappy mechanism, where if a practitioner update their availability, it is directly reflected on the appointment booking system. We should aim to have a service level agreement (SLA) that's on par with Cal.com or Calendly, where changes in availability is directly reflected within seconds. This is the response I received from our Deepwiki Mas, do you think this is workable?

It is indeed achievable, Mas. In short, this feature aims to enable practitioner's schedule to be refreshed on demand rather than having to wait the worker to run thus achieving your stated objective above. The SLA will gets even better since we will not utilize queue for async processing to reflect the changes on the practitioner's schedule.

I think using my proposed approach would be safer Mas Lucky, because it should be more straightforward to enforce ownership check for each resources as the first step to prevent abuse. Moreover, gatekeeping the trigger-activation frequency as you proposed should also be feasible with my proposal. Wdyt Mas?

For endpoint-based approach, security shouldn't be a concern, mas, since I can configure the endpoint to read practitioner id directly from auth (instead of untrusted body) and if the requester has Practitioner role, the process continue to read resources relevant to Slot regeneration to reflect changes to the practitioner schedule. This way, backend will guarantee that the Slot generation will use Practitioner-owned resource only in safe way.

I also thought another thing to consider if we proceed to use the FHIR resource update based approach. That is the dependability between updating the FHIR resources and processing the Slot regeneration. Consider scenarios below:

1. Practitioner sends PUT to PractitionerRole (contains update that impact Slot)
2. Backend validates the request (RBAC, ownership, etc)
3. Backend forwards the request to FHIR server
4. before sending the response back, the backend checks to determine whether the request must trigger Slot regeneration or not
5. If yes, then backend immediately execute Slot regeneration

It will be troublesome when the 5th steps fails. I find it difficult to determine what to do in case that happens. If we returns error, the client then must determine again whether it is just the Slot regeneration that was failed or the error comes from the step 1 - 4. Failure in step 5 means that the resources is already updated in FHIR server, but the changes to the schedule won't get reflected in the Slot resources and practically the practitioner has to wait for the periodic worker again. If we swap the 4th with 5th step, it just gets even trickier because it is possible that Slot gets updated but the updates for PractitionerRole to the FHIR server to fails and then also leads to inconsistencies.

I really need to know how we should handle those possible worst case scenario, mas. Even with the use of queue, we still have similar problem for the case when the event emitter fails to send the event to the queue.

For this part

I'm also thinking about reducing the complexity from the user's experience Mas. Of course, your approach is a good way to handle the issue from a system standpoint. Another way to handle it is by moving the availability drawer (the one that pops up when we click the Edit Schedule button) to the profile/edit-practice page. The UX should be more fluid that way, and we can localize the trigger to the profile/edit-practice page. API request from this page must then be handled as a bundle request. Therefore, the worker needs to only watch for (a) a Bundle request that contains modifications of a PractitionerRole or Schedule resource; (b) direct single request to modify PractitionerRole and Schedule resource (not bundled).

Please note that in the edit availability drawer the Save Changes button directly send the request to fhir/PractitionerRole endpoint. We need to modify this behavior so that the Save Changes button only save to localStorage and the request will only be made once the user clicks the Save button at the bottom of profile/edit-practice page.

On a second note, I have made several UX improvement to the profile and profile/edit-practice pages, which significantly improve the flow. However, if you think that we can tweak the visual appearance further to make it more intuitive to the user, I'd be happy to hear your suggestions.

I think it is better to separate this discussion, mas. This feature should be able to exists even without changing the UI

[lamurian]

I also thought another thing to consider if we proceed to use the FHIR resource update based approach. That is the dependability between updating the FHIR resources and processing the Slot regeneration. Consider scenarios below:

1. Practitioner sends `PUT` to `PractitionerRole` (contains update that impact `Slot`)

2. Backend validates the request (RBAC, ownership, etc)

3. Backend forwards the request to FHIR server

4. before sending the response back, the backend checks to determine whether the request must trigger `Slot` regeneration or not

5. If yes, then backend immediately execute `Slot` regeneration

It will be troublesome when the 5th steps fails. I find it difficult to determine what to do in case that happens. If we returns error, the client then must determine again whether it is just the Slot regeneration that was failed or the error comes from the step 1 - 4. Failure in step 5 means that the resources is already updated in FHIR server, but the changes to the schedule won't get reflected in the Slot resources and practically the practitioner has to wait for the periodic worker again. If we swap the 4th with 5th step, it just gets even trickier because it is possible that Slot gets updated but the updates for PractitionerRole to the FHIR server to fails and then also leads to inconsistencies.

I really need to know how we should handle those possible worst case scenario, mas. Even with the use of queue, we still have similar problem for the case when the event emitter fails to send the event to the queue.

I imagine this scenario might happen when the server is unreachable. How if we implement a retry logic every second for the first 3 seconds? If it still fails, we return status 202 Accepted to the client with a message The requested is accepted but the process is currently queued; at this step we will queue the request as a fallback mechanism. The queue is cancelled if the user creates another request, or if the periodic worker is triggered.

[luckyAkbar]

I imagine this scenario might happen when the server is unreachable. How if we implement a retry logic every second for the first 3 seconds? If it still fails, we return status 202 Accepted to the client with a message The requested is accepted but the process is currently queued; at this step we will queue the request as a fallback mechanism. The queue is cancelled if the user creates another request, or if the periodic worker is triggered.

I agree that we should use a queue as a fallback mechanism only after performing a best-effort retry. However, that would add extra complexity for a case that rarely happens. On the other hand, having this mechanism would mean our users don't have to retry requests just to regenerate their Slot schedules. If that trade-off is acceptable, then I think the requirement is now clear, mas @lamurian

[lamurian]

I think before adding a layer of complexity, it's best to assess the real-world use cases Mas. I suppose it's more doable to set the current goalpost up to handling a synchronous retry logic. We should implement the handover mechanism to async queue in the future issue. This way, we can gain insight from user's behavior before implementing a feature they might not use that often.

[luckyAkbar]

I think before adding a layer of complexity, it's best to assess the real-world use cases Mas. I suppose it's more doable to set the current goalpost up to handling a synchronous retry logic. We should implement the handover mechanism to async queue in the future issue. This way, we can gain insight from user's behavior before implementing a feature they might not use that often.

Okay, I think that will work, mas. For this feature request, I think all the requirements are now clear