Skip to main content

0044: Tenant State Machine

Date: 2025-11-08

Status: Proposed

Context​

The tenant-lifecycle-service is responsible for managing the state of a tenant throughout its existence on the platform. A tenant is not simply "active" or "inactive"; it moves through various states based on business events like completing onboarding, failing to pay a subscription, or being marked for deletion.

Without a formally defined state machine, the logic for handling these transitions would be ad-hoc, difficult to reason about, and prone to errors. We need to establish a clear, predictable model for the tenant lifecycle.

Decision​

We will implement a formal state machine for the Tenant aggregate within the tenant-lifecycle-service. The service will listen for events from other parts of the platform and use them to trigger state transitions.

Tenant States​

  • Pending: The initial state. A tenant enters this state when it is first created by the onboarding-service. The tenant is not yet active.
  • Active: The normal operational state. A tenant can use the platform's features.
  • Suspended: A non-operational state. The tenant's users cannot log in or access services. This is a recoverable state.
  • PendingDeletion: A terminal state where the tenant is marked for deletion. Data may be scheduled for purging.
  • Archived: A read-only, long-term storage state.

Core State Transitions & Triggering Events​

  • Pending -> Active: Triggered by an OnboardingCompleted event from the onboarding-service.
  • Active -> Suspended: Triggered by a SubscriptionPaymentFailed event from the payment-gateway-service.
  • Suspended -> Active: Triggered by a SubscriptionPaymentSucceeded event from the payment-gateway-service.
  • Active -> PendingDeletion: Triggered by a SubscriptionCancelled event or an explicit admin action.

Consequences​

Positive​

  • Clarity & Predictability: The tenant lifecycle is clearly defined and easy to understand.
  • Maintainability: State transition logic is centralized within the tenant-lifecycle-service, making it easy to modify or extend.
  • Decoupling: The service is event-driven. The payment-gateway-service doesn't need to know how to suspend a tenant; it only needs to publish an event that a payment failed.

Negative​

  • Eventual Consistency: There will be a brief delay between a business event occurring (e.g., payment failure) and the tenant's state being updated. This is an acceptable trade-off for this business process.
  • Centralized Logic: The tenant-lifecycle-service becomes a critical component for managing tenant access. Its availability is important.