Overview and concepts#

This page provides an overview of the platform and covers many of the foundational concepts.

Structure#

The general structure of the platform can be represented as follows:

Subscriptions#

A subscription represents a chain of contracts from the customer all the way to partners.one. Customers can derive rights from having a subscription, but are billed for it. Often, a subscription goes hand in hand with provisioning digital services.

Every subscription is billable as soon as it's created, from its start date until its end date. The end date is optional, and can imply whether the subscription is active or not. The actual subscription state must be derived from its state.

State#

Every subscription has a state which is driven by a finite-state machine. This means, the subscription is always in exactly one of a finite number of states at any given time. The initial state for (new) subscriptions is always created and the final state is always archived. The stable state of a subscription is active.

The transitions, or edges, can trigger product lifecycle methods, such as provisioning, deprovisioning, suspension and unsuspension. A state transition can have constraints, or conditions, such as whether the subscription's end date is set (or not), and whether that end date is in the future (or not).

Resource#

Subscriptions on partners.one set things in motion in the real world. After all, some of them will result in a web site, domain name or active DNS zone. Some entitle their owners to something such as support. There is a mechanism to track these resources; this mechanism is explained in this section.

Furthermore, resources are:

• Not billable
• Immutable (within the platform)
• Opaque to the user
• Produced by exactly one Subscription; see below
• Has a kind; see below
• Has a handle; see below
• Each resource can be consumed by zero or one subscription at a time
• Subject to lifecycle and consumption state tracking

The handle#

A handle concretely points out the resource. They abide by a few rules:

• Handles are unique only for a (kind, producer) combination, but otherwise not
• Handles should be human-readable (and presentable in an interface)
• Handles are not empty
• Handles are deterministic
• Handles do not use localized text (text that requires translation)

The kind#

Resource kinds specify what real-world asset type they represent. These types are universal across all resources, regardless of producing subscription.

Resource Lifecycle#

Resources associated with subscriptions follow a dual state model, enabling the platform to track both their existence and their usage independently. This dual-state model allows complex interactions between subscriptions and resources, while maintaining a clear contract of ownership (producer) and usage (consumer).

State Lifecycle#

Resources are produced by asking the provisioning module of the producing Subscription for a list of Resource objects it controls. A diff is made;

• Resources produced before, will continue to exist
• Resources not produced before will start to exist
• Resources not produced anymore, will cease to exist

In reality, this is a bit more nuanced. Resources follow a certain lifecycle:

They start out either Expected or Present, depending on the way they are created. When the platform provisions a new subscription for example, it will expect some resources to be created in the near future. Initially, the resource won't exist, but the first time the platform notices the resource, it becomes Present. Each resource can be consumed by zero or one subscription at a time. However, a resource may also (from the viewpoint of the platform) just appear out of nowhere, in which case it is immediately Present.

When resources the platform is tracking aren't produced, they become Absent. Absent resources are assigned a deadline (24 hours) by which they will be Expired if they aren't produced. This state prevents losing a resource if it's temporarily inaccessible, such as during a misconfiguration. Absent resources can become Present if they are produced once again

Consumption Lifecycle#

In addition to lifecycle state, resources may enter a separate consumption state. This represents how the resource is being used:

• A resource may be consumed by another subscription (e.g., used as a dependency or component). When this happens, the platform invokes the producing module’s hook to perform any necessary provisioning or configuration

• The resource may then be released when no longer needed. This triggers a hook, allowing the module to clean up access, revoke credentials, or undo previous configuration.

These hooks are part of the provisioning contract and ensure that resource usage is not just a metadata flip, but a traceable, auditable process. Modules may implement these hooks using mechanisms that support retryable and long-running operations.

Consumption Compatibility#

Provisioning modules must explicitly declare which types of resources they support consuming. This is typically done via a registration mechanism or decorator, pairing:

• A specific Product.Key (e.g., RANK_MATH_PRO)
• supported Resource.Kind (e.g., Website)

This declaration allows the platform to:

• Validate whether a subscription is allowed to consume a given resource
• Route the consumption and release lifecycle hooks to the corresponding module.
• Prevent incompatible consumption attempts at runtime

How Consumption Affects State Transitions#

The consumption lifecycle introduces constraints that directly influence which transitions are valid in the state lifecycle. These constraints ensure consistent handling of resources that may still be in active use.

Key effects:

• Consumed resources cannot expire. However, if a consumed resource needs to expire, it must be released first.
• Only present resources can be consumed.

This separation between resource's state and consumption supports:

• Independent tracking of a resource’s creation and usage
• Enforcement of logical constraints — for example, preventing a resource from being marked as expired while it is still actively consumed
• Released resources that remain valid can be reassigned to new consumers, reducing the need for reprovisioning and improving efficiency.

Monitoring#

Taking the concept of resources a step further, one can realize that there actually is a lot of state that surrounds a resource. A domain name will have a registrar which may change. A zone will have certain default DNS records/queries we would like to monitor. A site is reachable (or not). Therefore, resources can be monitored.

By default, the platform will periodically refresh the state of all resources in all subscriptions.

Glossary#