Guardline

    Implementation Plan

    Plan to implement onboarding flows — create sessions, complete onboarding, and interact with Platform. Includes visual diagrams.

    Overview

    This document abstracts the developer from the core Guardline layer. You only interact with:

    1. Platform (aml_web_frontend) — Compliance dashboard: People, Legal, Manual Onboarding, Onboarding Flow editor
    2. Onboarding Web (kyx_onboarding_web) — Hosted flow where end users complete KYC/KYB
    3. Frontend Composer (optional) — BFF that proxies session creation to the Workflow Engine

    The Workflow Engine (BFF) and templates are managed internally. You create sessions and redirect users to the onboarding URL.

    1. Creating a Flow Session

    Flow Diagram

    Direct Integration (Platform → Workflow Engine)

    When Platform calls the Workflow Engine directly (bypassing Composer):

    Request / Response

    Request:

    POST /flow-sessions
Content-Type: application/json

{
  "tenantId": "398b985e-019c-4f1f-98b6-4a080543cb9d",
  "templateType": "KYC"
}

    Response:

    {
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "url": "https://onboarding.guardline.io/v2/{tenantId}/onboarding?sessionId={token}"
}

    Platform usage: Use kyxTemplateService.createFlowSession(flowType, tenantId) which calls POST /api/kyx-sessions. The Platform BFF proxies to the Workflow Engine.

    2. Flow Completion Lifecycle

    Step-by-Step Flow Diagram

    Module Completion Flow

    Session Statuses

    StatusDescription
    NOT_STARTEDSession created, user has not begun
    IN_PROGRESSUser has completed at least one module
    COMPLETEDAll modules finished
    ABANDONEDSession abandoned / expired

    3. Interacting with the Frontends

    Platform (aml_web_frontend)

    PagePurpose
    PeopleKYC list — applicants who completed KYC flow
    LegalKYB list — organizations that completed KYB flow
    Manual OnboardingChoose KYC or KYB → embeds iframe with onboarding URL
    Onboarding FlowConfigure flow templates (modules, fields)
    DashboardMetrics for KYC/KYB/Transactions

    Creating a session from Platform: Manual Onboarding uses useFlowSession(flowType, tenantId) which calls createFlowSession → renders an iframe with the onboarding URL.

    Onboarding Web (kyx_onboarding_web)

    ScreenPurpose
    CreateSessionWelcome + Start button → creates session, redirects to onboarding URL
    Onboarding FlowSteps: Terms → Document → Form → Liveness → Success
    Route/{tenantId}/onboarding?sessionId={token}

    Entry point: User lands on /{tenantId}/create-session or receives a link. Clicking "Start" triggers session creation and redirects to the flow.

    Frontend Composer (optional)

    Acts as a BFF. Platform can call:

    • POST /api/kyx-sessions with { flowType, tenantId }
    • Composer calls Workflow Engine POST /flow-sessions
    • Returns { token, url } to Platform

    4. Summary: What the Developer Must Know

    1. Create session: Call POST /flow-sessions (or Platform’s /api/kyx-sessions) with tenantId and templateType.
    2. Redirect user: Use the returned url (contains JWT in sessionId query param).
    3. User completes flow: Onboarding web fetches config from Workflow Engine, shows steps, and calls PUT .../modules/{moduleId}/complete for each step.
    4. Post-completion: Applicant appears in People (KYC) or Legal (KYB) in the Platform.

    No need to understand Workflow Engine internals, templates, or MongoDB—only the public flow creation and completion APIs.