3.4 KiB
Onboarding Journeys And Welcome Protocols
Status: implemented headless slice Date: 2026-06-15 Related workplan: USER-WP-0013
Purpose
This slice adds resumable onboarding journeys for newly registered or newly entitled users. Welcome protocols are templates that can be triggered by registration completion, prepared-account claims, invitations, access-profile events, or explicit manual starts.
user-engine owns journey state, audit/event correlation, lifecycle gaps, and adapter references. Notification delivery, support content, protected service tours, and external workflow/task systems remain outside the core domain.
Domain Model
WelcomeProtocol is the tenant-scoped template. It stores trigger type,
optional matching keys such as prepared journey, application, realm, service,
role, hat, factor requirements, and ordered WelcomeProtocolStep definitions.
WelcomeProtocolStep names the subsystem, task kind, optional external task
reference, optional callback reference, support reference, and whether a
subsystem callback is required.
OnboardingJourney is the persisted user state. It records tenant, user,
protocol, trigger type, source id/event, journey key, status, active step,
correlation id, and timestamps.
OnboardingStep carries step status plus optional OnboardingTask and
SubsystemHandoff references. Missing required subsystem callbacks produce
explicit lifecycle gaps such as
subsystem-callback-missing:<subsystem>:<step>.
Public Facade
UserEngineService exposes:
register_welcome_protocol(...)list_welcome_protocols(...)start_onboarding_journey(...)start_onboarding_for_registration(...)start_onboarding_for_prepared_account(...)progress_onboarding_step(...)complete_onboarding_step(...)skip_onboarding_step(...)fail_onboarding_step(...)resume_onboarding_journey(...)onboarding_diagnostics(...)
Registration completion auto-starts matching registration protocols. Prepared account claim auto-starts matching prepared-account protocols when the claimed package includes a matching onboarding journey key.
Lifecycle Rules
Journey status is derived from step state:
- a missing required callback starts the journey as
blocked; - an active non-blocked first step starts as
in_progress; - failed steps fail the journey;
- all completed/skipped steps complete the journey;
- all skipped steps skip the journey.
Resuming a pending, blocked, or failed journey can attach callback references
and returns blocked/failed steps to in_progress.
Adapter Boundary
The service defines ports for notification delivery, task systems, support content, subsystem welcome callbacks, and lifecycle task linking. The current headless slice stores adapter references but does not call external systems.
Identity Context And Diagnostics
identity_context includes onboarding journeys for the resolved user/tenant.
onboarding_diagnostics reports protocol count, journey count, status counts,
blocked step ids, and lifecycle gaps.
Diagnostics and outbox events avoid factor values and service content. Payloads carry ids, statuses, trigger types, source ids, active step keys, and lifecycle gap identifiers.
Current Limits
- No notification platform or support-content renderer is implemented.
- No protected subsystem tour is hard-coded into user-engine.
- External task and callback execution is left to adapters.
- UI surface contracts are implemented by USER-WP-0014.