chore: add code comments for readability

Signed-off-by: Yeganathan S <63534555+skwowet@users.noreply.github.com>

Author: skwowet

services/apps/members_enrichment_worker/src/activities/enrichment.ts

@@ -582,6 +582,8 @@ export async function updateMemberUsingSquashedPayload(
         isHighConfidenceSourceSelectedForWorkExperiences,
       )
 
+      // Enrichment often deletes and recreates the same orgs with identical dates.
+      // Skip the refresh when the timeline that drives activityRelations hasn't changed.
       affiliationNeedsRefresh =
         results.toUpdate.size > 0 ||
         hasMemberOrganizationTimelineChange(results.toDelete, results.toCreate)
@@ -779,6 +781,11 @@ function sanitizeWorkExperienceDateRanges(
   })
 }
 
+/**
+ * Returns true when the set of (orgId, startDate, endDate) tuples differs
+ * between deletes and creates. Fields like title or source don't affect
+ * the affiliation timeline, so they're intentionally ignored.
+ */
 function hasMemberOrganizationTimelineChange(
   toDelete: IMemberOrganizationData[],
   toCreate: IMemberEnrichmentDataNormalizedOrganization[],

services/apps/members_enrichment_worker/src/workflows/enrichMember.ts

@@ -43,7 +43,8 @@ export async function enrichMember(
   // skip enrichment if member no longer exists
   if (!member) return
 
-  // Run all sources in parallel
+  // Fetch all sources in parallel so one slow or rate-limited source doesn't block the rest.
+  // If any source fails, the member's enrichment fails immediately.
   const sourceResults = await Promise.all(
     sources.map(async (source): Promise<boolean> => {
       const caches = await findMemberEnrichmentCache([source], input.id)

services/apps/profiles_worker/src/workflows/member/memberUpdate.ts

@@ -19,16 +19,10 @@ const { updateMemberAffiliations, syncOrganization, syncMember } = proxyActiviti
 
 export const refreshAffiliationsSignal = defineSignal<[MemberUpdateInput]>('refreshAffiliations')
 
-/*
-memberUpdate is a Temporal workflow that:
-  - [Signal]: accepts 'refreshAffiliations' signals to queue affiliation refresh requests
-  - [Activity]: Refresh all affiliations for a given member in the database.
-  - [Activity]: Sync member and memberOrganizations to OpenSearch if specified.
-
-Signals are coalesced: if N requests arrive while a refresh is in progress,
-they are merged into one follow-up pass. This eliminates the TERMINATE_IF_RUNNING
-race where concurrent callers killed mid-flight refreshes.
-*/
+/**
+ * Per-member workflow that serializes async member operations (affiliations, sync, etc).
+ * Concurrent signals are coalesced into one follow-up pass instead of racing.
+ */
 export async function memberUpdate(input?: MemberUpdateInput): Promise<void> {
   let queued: MemberUpdateInput | null = input ?? null
 
@@ -50,12 +44,14 @@ export async function memberUpdate(input?: MemberUpdateInput): Promise<void> {
   })
 
   if (!queued) {
+    // signalWithStart starts with no args, so wait for the first signal to arrive
     const received = await condition(() => queued !== null, '5 minutes')
     if (!received) return
   }
 
   while (queued) {
     const pending = queued
+    // Clear before awaiting so new signals accumulate into the next pass
     queued = null
 
     const memberId = pending.member.id

services/apps/profiles_worker/src/workflows/organization/organizationUpdate.ts

@@ -56,6 +56,9 @@ export async function organizationUpdate(input: IOrganizationProfileSyncInput):
       memberOrganizationIds: [],
       syncToOpensearch: false,
     }
+    // Routes through the per-member workflow so concurrent org updates coalesce.
+    // ABANDON is needed because continueAsNew closes this execution, and without it
+    // Temporal would terminate the child refreshes we just kicked off.
     const handle = await startChild('memberUpdate', {
       workflowId: `${TemporalWorkflowId.MEMBER_UPDATE}/${DEFAULT_TENANT_ID}/${memberId}`,
       workflowIdConflictPolicy: WorkflowIdConflictPolicy.USE_EXISTING,