Domain Events & Integration Contracts

The Fitness (GYM) bounded context communicates with the broader Obelaw enterprise ecosystem exclusively via state-altering, immutable domain events and formal integration contracts. This decoupled, event-driven pattern allows downstream domains (Billing, CRM, Notifications, HCM) to react to membership and attendance facts without impeding turnstile decisions or booking workflows with synchronous network dependencies.

---

1. Domain Events Emitted

The following table catalogs the core domain events emitted by the Fitness bounded context:

Event Name	Source Aggregate	Emitted When	Conceptual Payload Highlights
MembershipActivated	MembershipAgreement	Joining fee and first period settle; agreement goes live.	AgreementId, MemberId, PlanSnapshot, BillingCycleAnchor, ActivationTimestamp.
MembershipRenewed	MembershipAgreement	Renewal payment settles and the agreement extends.	AgreementId, MemberId, NewPeriodStart, NewExpiryDate, PlanSnapshot.
MembershipPlanChanged	MembershipAgreement	An upgrade or downgrade takes effect.	AgreementId, FromPlanId, ToPlanId, EffectiveDate, ProrationIntent.
MembershipFreezeStarted	MembershipAgreement	An approved freeze window begins.	AgreementId, MemberId, FreezeStartDate, ScheduledEndDate, ConsumedQuotaDays.
MembershipFreezeEnded	MembershipAgreement	A freeze ends on schedule or via early resume.	AgreementId, ActualFreezeDays, ExtendedExpiryDate, RemainingQuotaDays.
MembershipPaymentSuspended	MembershipAgreement	Billing reports a failed recurring payment.	AgreementId, MemberId, OutstandingAmount, SuspensionTimestamp.
MembershipReactivated	MembershipAgreement	Outstanding balance cures during suspension.	AgreementId, MemberId, CuredAmount, ReactivationTimestamp.
MembershipExpired	MembershipAgreement	The final billing period elapses without renewal.	AgreementId, MemberId, ExpiryDate, GraceWindowDeadline.
MembershipCancelled	MembershipAgreement	The notice period elapses and the agreement closes.	AgreementId, MemberId, EffectiveDate, FinalSettlementIntent.
MembershipTerminated	MembershipAgreement	Dunning exhausts and the club terminates the contract.	AgreementId, MemberId, OutstandingAmount, TerminationReason.
ClassSessionScheduled	ScheduledClassSession	A dated class occurrence opens for booking.	SessionId, ClassTemplateId, StudioId, InstructorId, StartTime, Capacity.
ClassSessionCancelledByClub	ScheduledClassSession	The club cancels a scheduled session.	SessionId, CancellationReason, AffectedBookingIds.
ClassBookingConfirmed	ScheduledClassSession	A seat reservation is confirmed.	BookingId, SessionId, MemberId, ConfirmedTimestamp.
ClassBookingWaitlisted	ScheduledClassSession	Demand exceeds capacity; entry queued.	WaitlistEntryId, SessionId, MemberId, ArrivalPosition.
WaitlistPromotionOffered	ScheduledClassSession	A released seat is offered to the next entry.	WaitlistEntryId, SessionId, MemberId, OfferExpiryTimestamp.
WaitlistPromotionExpired	ScheduledClassSession	An offer lapses unaccepted.	WaitlistEntryId, SessionId, MemberId, PolicyOutcome (Retained / Dropped).
ClassBookingCancelled	ScheduledClassSession	A booking is cancelled before the cutoff.	BookingId, SessionId, MemberId, ReleasedSeatTimestamp.
ClassBookingLateCancelled	ScheduledClassSession	A booking is cancelled after the cutoff.	BookingId, SessionId, MemberId, StrikeId.
ClassNoShowRecorded	ScheduledClassSession	A confirmed member is absent at session start.	BookingId, SessionId, MemberId, StrikeId.
StrikeApplied	ScheduledClassSession	A penalty strike is appended to a member.	StrikeId, MemberId, OriginBookingId, RollingWindowCount.
BookingPrivilegesSuspended	ScheduledClassSession	The rolling strike threshold is crossed.	MemberId, SuspensionStart, SuspensionEnd, ActiveStrikeCount.
MemberCheckedIn	MemberAccessEvent	A credential presentation is granted.	AccessEventId, MemberId, AccessPointId, ZoneId, CheckInTimestamp.
AccessDenied	MemberAccessEvent	A credential presentation is denied.	AccessEventId, MemberId, AccessPointId, DenialReason, AttemptTimestamp.
DayPassIssued	MemberAccessEvent	A single-day access right is sold or granted.	DayPassId, HolderReference, ValidDate, EntitledZones.
PtCreditPackagePurchased	PtCreditPackage	A credit package is sold and settled.	PackageId, MemberId, CreditQuantity, ValidityPeriod, PurchaseTimestamp.
PtSessionConfirmed	PtSessionAppointment	A session is confirmed and a credit consumed.	AppointmentId, MemberId, TrainerId, SessionSlot, CreditLedgerEntryId.
PtSessionCompleted	PtSessionAppointment	The trainer signs off a delivered session.	AppointmentId, MemberId, TrainerId, DurationMinutes, CompletionTimestamp.
PtSessionCreditRestored	PtSessionAppointment	A consumed credit returns to the package.	AppointmentId, PackageId, CreditLedgerEntryId, RestorationReason.
PtSessionCreditForfeited	PtSessionAppointment	A credit is lost to late cancellation or no-show.	AppointmentId, PackageId, CreditLedgerEntryId, ForfeitureReason.

---

2. Integration Contracts & Downstream System Reactions

Downstream enterprise systems subscribe to Fitness domain events through asynchronous message brokers:

flowchart TD
    FITNESS["Fitness (GYM) Domain"]

    E1["MembershipActivated / Renewed / Cancelled"]
    E2["MembershipPaymentSuspended"]
    E3["WaitlistPromotionOffered"]
    E4["ClassNoShowRecorded / StrikeApplied"]
    E5["MemberCheckedIn / AccessDenied"]
    E6["PtSessionCompleted"]

    FITNESS --> E1
    FITNESS --> E2
    FITNESS --> E3
    FITNESS --> E4
    FITNESS --> E5
    FITNESS --> E6

    E1 -->|Generate & Settle Recurring Invoices| FMS["Accounting / Billing"]
    E2 -->|Execute Dunning & Retry Schedule| FMS
    E3 -->|Dispatch Time-Sensitive Push / SMS| NOTIFY["Notification Service"]
    E4 -->|Notify Member & Update Risk Profile| CRM["CRM / Member Master"]
    E5 -->|Refresh Occupancy & Safety Manifests| OPS["Club Operations Dashboard"]
    E6 -->|Feed Trainer Utilization & Payroll Input| HCM["Human Capital Management"]

1. Accounting / Billing Integration Contract

• Subscribed Events: MembershipActivated, MembershipRenewed, MembershipPlanChanged, MembershipCancelled, PtCreditPackagePurchased, DayPassIssued
• Reaction:
  1. Generates the recurring invoice schedule anchored to the agreement’s billing cycle day, including joining fees and plan change prorations.
  2. Executes payment collection attempts and reports outcomes back through the Billing ACL as PaymentOutcome facts.
  3. On cancellation, settles the final period, applies proration credits, and closes the receivable.
• Responsibility Boundary: The Fitness context publishes contract lifecycle facts; Billing owns invoice numbering, tax treatment, payment retry schedules, and refund execution.

---

2. Notification Service Integration Contract

• Subscribed Events: ClassBookingConfirmed, ClassBookingWaitlisted, WaitlistPromotionOffered, MembershipFreezeEnded, BookingPrivilegesSuspended, ClassSessionCancelledByClub
• Reaction:
  1. Dispatches booking confirmations and session reminders through the member’s preferred channel.
  2. Treats WaitlistPromotionOffered as time-critical: the notification must carry the offer expiry timestamp and prioritize push/SMS over email.
  3. Broadcasts club-initiated session cancellations to all confirmed and waitlisted members with rebooking guidance.
• Responsibility Boundary: Fitness publishes business context and urgency; the notification service owns templates, channel selection, delivery retries, and opt-out compliance.

---

3. CRM / Member Master Integration Contract

• Subscribed Events: MembershipExpired, MembershipCancelled, StrikeApplied, MemberCheckedIn
• Reaction:
  1. Updates the member profile with lifecycle standing, last visit date, and attendance frequency trends.
  2. Triggers win-back campaigns for expired members and retention outreach for members whose attendance streaks collapse.
  3. Feeds strike accumulation patterns into churn-risk scoring models.
• Responsibility Boundary: Fitness owns contract state and attendance facts; CRM owns campaign orchestration, segmentation, and communication history.

---

4. Access Hardware Decision Contract (ACL)

• Subscribed Events: MembershipActivated, MembershipFreezeStarted, MembershipFreezeEnded, MembershipPaymentSuspended, MembershipExpired, MembershipCancelled
• Reaction:
  1. Refreshes the signed offline eligibility snapshots cached on turnstile controllers, so access decisions remain correct during network outages.
  2. Propagates credential revocations (lost cards, compromised QR tokens) to all access points in the branch.
• Responsibility Boundary: Fitness evaluates and records every access attempt; vendor hardware owns physical gate actuation, local caching, and device health telemetry.

---

5. Human Capital Management Integration Contract

• Subscribed Events: PtSessionCompleted, ClassSessionCompleted
• Reaction:
  1. Accumulates trainer and instructor delivered-session counts per pay period.
  2. Feeds utilization analytics: session fill rates per trainer, class attendance per instructor, and peak demand coverage.
• Responsibility Boundary: Fitness publishes verified delivery facts; HCM owns compensation rules, contract terms, and statutory payroll processing.