Skip to main content

0037: Onboarding Adapter Architecture

Date: 2025-11-08

Status: Proposed

Context​

The platform requires a service to manage complex, multi-step onboarding processes for new tenants and users. These processes are long-running and may involve human interaction, external API calls, and internal service orchestration.

We have two primary architectural options:

  1. Stateful Service: Build the onboarding-service as a stateful microservice that manages its own state machine, persistence, and retry logic.
  2. Stateless Adapter: Build the onboarding-service as a stateless adapter that provides a domain-specific API but delegates the actual orchestration and state management to a generic, platform-wide workflow-service.

A stateful service would duplicate logic that is common to many long-running business processes (e.g., order fulfillment, report generation). A generic workflow-service (as planned in P1) is designed to solve this problem centrally.

Decision​

We will implement the onboarding-service as a stateless adapter on top of the generic workflow-service.

The onboarding-service will not have its own state machine or persistence layer for tracking process state. Its sole responsibilities are:

  1. To provide a clean, domain-specific API for "onboarding" (e.g., POST /onboarding/start).
  2. To translate these domain-specific requests into generic calls to the workflow-service (e.g., POST /workflows/{workflow_name}/start).
  3. To act as a simple proxy for status queries, translating GET /onboarding/{id}/status to GET /workflows/instances/{id}.

Consequences​

Positive​

  • Simplicity & Focus: The onboarding-service remains simple, stateless, and focused on its API contract. It is easy to develop, test, and scale.
  • Reusability: We avoid building a custom state machine and instead leverage the robust, reusable capabilities of the central workflow-service.
  • Consistency: All long-running business processes across the platform will be managed and monitored in the same way, using the workflow-service.
  • Flexibility: The mapping of onboarding "pipelines" to actual workflows can be configured within the adapter, allowing for changes without redeploying the core workflow engine.

Negative​

  • Direct Dependency: The onboarding-service has a hard, synchronous dependency on the workflow-service to function. This is an acceptable trade-off as they are part of the same core process.
  • Distributed Logic: The complete logic for an onboarding process is distributed between the adapter's API and the workflow definition itself, which can be slightly more complex to trace end-to-end.