Lifecycle & Journeys

The lifecycle is an institution-wide state machine that defines every stage a profile can occupy and the allowed transitions between them. It powers the journey from first contact to alumni status, tracks withdrawal, and enforces valid state changes.

Overview

Each institution has a single lifecycle definition. The lifecycle is a tree of states, each containing one or more substates, connected by transitions:

stateDiagram-v2
    direction LR
    [*] --> prospect
    prospect --> applicant
    applicant --> student
    student --> alumnus
    prospect --> contact
    student --> withdrawn

A profile's position in the lifecycle is stored on each of its roles. Since a profile can have roles in multiple contexts (institution, classes, courses), it can be at different lifecycle stages simultaneously — for example, student::enrolled in one class and applicant::submitted in another.

States and Substates

States

States are the top-level stages of the lifecycle. Common states include:

State	Description
prospect	A person who has shown interest but has not applied
applicant	A person with an active application
student	An enrolled student
alumnus	A graduated student
contact	An external contact (not in the student pipeline)
staff	An institutional staff member
admin	A platform administrator
lecturer	An instructor or professor

Substates

Each state contains one or more substates that add granularity:

Example substates for the applicant state:

Substate	Description
draft	Application started but not submitted
submitted	Application submitted, awaiting review
processing	Application under review
decision_made	Decision issued

The state::substate Pair

A role's position is always expressed as a state::substate string — for example, applicant::submitted or student::enrolled. This pair is the primary key for lifecycle queries.

Transitions

Transitions define which moves between substates are valid. Each transition specifies a starting position, a destination position, and the event that triggers it. Attempting an invalid transition is blocked by the platform.

stateDiagram-v2
    direction LR
    state "applicant" as app {
        draft --> submitted: submit
        submitted --> processing: review
        processing --> decision_made: decide
    }
    state "student" as stu {
        enrolled --> active: start
    }
    decision_made --> enrolled: enroll

Transition Access by Role

Transitions can be filtered by the user's role. For example, admissions staff may see different available transitions than academic staff. This enables role-aware workflows where each team only sees the actions relevant to their responsibilities.

Journeys

A journey is the ordered path through the lifecycle's fluid states. Fluid states are the states that represent forward progression (typically prospect, applicant, student, alumnus), as opposed to lateral states like staff or contact.

flowchart LR
    subgraph "Fluid States (Journey)"
        A[prospect::cold] --> B[prospect::warm]
        B --> C[applicant::submitted]
        C --> D[student::enrolled]
        D --> E[student::active]
        E --> F[alumnus::graduated]
    end

Journey Ordering

The lifecycle defines an ordered sequence of fluid states. Within each state, substates are also ordered. This produces a fully ordered sequence that powers:

• Journey visualization — progress bars showing how far a profile has advanced
• Comparison — determining if one role is "higher" than another
• Downstream navigation — knowing which states come after the current position

Downstream Exclusions

Individual substates can define downstream_excluded_states — positions that should not be reachable from that substate. This prevents scenarios like a withdrawn student re-enrolling in the same cohort without going through readmission.

Roles in Contexts

Lifecycle states are assigned to profiles through roles, and each role belongs to a context:

Context Type	Description	Example
Institution	The institution itself	General staff, admin roles
Class (Cohort)	A specific intake or cohort	student::enrolled in "MBA 2026"
Course	An individual course	student::active in "Marketing 101"

A profile interacts with the lifecycle independently in each context. Enrolling in a new class creates a new role starting at the lifecycle's initial state.

flowchart TD
    P[Profile: Jane Smith] --> R1["Role: staff::admissions
Context: Institution"]
    P --> R2["Role: student::enrolled
Context: MBA 2026"]
    P --> R3["Role: prospect::warm
Context: MSc Data 2027"]

Adding and Removing Roles

Roles can be added, removed, and transitioned through the platform UI, automation workflows, or the API:

• Add — Creates a new role in a context and triggers automation events
• Remove — Removes the role after checking for dependencies (e.g., active applications)
• Update state — Transitions the role to a new state/substate through the lifecycle state machine

Ownership and Campus

Each role can have:

• An owner — a staff profile responsible for the person in that context
• A campus — linking the role to a specific campus location

Potential

Each role carries a potential rating used for lead scoring and prioritization:

Value	Numeric	Description
unknown	0	Not yet assessed
low	1	Low priority
medium	2	Medium priority
high	3	High priority

Potential ratings enable sorting and filtering profiles by priority level.

Withdrawal

A role can be marked as withdrawn to indicate the profile has left that context. Withdrawal is separate from lifecycle state — a student can be withdrawn from a class without changing their overall lifecycle state.

Withdrawal Details

Each withdrawal records:

• Whether the role is withdrawn
• When the withdrawal occurred
• One or more withdrawal reasons
• An optional free-text explanation

Withdrawal Reasons

Institutions can configure withdrawal reasons. The default set includes:

• unknown
• personal
• professional
• financial
• competition
• deferred

Institutions can also define custom withdrawal reasons.

Withdrawal Operations

• Withdraw — Marks the role as withdrawn, records the timestamp and reasons
• Unwithdraw — Reverses the withdrawal, clearing the flag and timestamp

Withdrawal publishes automation events, enabling workflows like sending exit surveys or updating CRM records.

Account States

Beyond lifecycle roles, every profile has a user role that tracks account-level status:

stateDiagram-v2
    [*] --> inactive: created
    inactive --> active: activate
    active --> suspended: suspend
    suspended --> active: activate
    active --> inactive: inactivate
    active --> deleted: delete
    active --> forgotten: forget
    inactive --> deleted: delete
    inactive --> forgotten: forget

Substate	Description
inactive	Account created but not yet activated
active	Account is fully active
suspended	Temporarily blocked — session invalidated, cannot log in
deleted	Soft-deleted — marked as deleted, unsubscribed from communications
forgotten	GDPR forgotten — data encrypted, journey roles removed

See Profile Operations for details on activate, suspend, delete, and forget operations. See Authentication for how account states affect login.

Initial State

The lifecycle defines an initial_state and initial_substate (typically prospect::cold). When a new profile enters a context, its role starts at the initial position unless explicitly specified.