# sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion architecture

> Architecture diagram of the GitHub repository sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion
- Repository: https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion

## Overview

##### Project Type and Purpose
- Type: A Node.js/TypeScript “connector” library (an ISC plugin) that runs as part of the SailPoint CLI/Identity Security Cloud (ISC) ecosystem.
- Purpose: Aggregate account data from multiple sources, generate unique IDs, detect and merge duplicates, and synchronize proxy accounts back to ISC via its REST APIs.

##### File Structure
Top level:
- .github/ → CI/CD workflows, issue templates
- connector-spec.json → Connector metadata (name, version, commands)
- delete_forms.ps1 → Maintenance script
- assets/images → Documentation screenshots
- src/ → Production code
- test/ → CSV fixtures, HTTP scenarios, Python script
- config files: tsconfig.json, jest.config.js, eslint.config.mjs, package.json, package-lock.json

Inside src/:
- index.ts → Entry point & orchestrator
- axios.ts & sdk-client.ts → HTTP client wrapper for ISC APIs
- contextHelper.ts → Logging, error handling, CLI context
- data/ → Definitions of available actions and statuses
- model/ → TypeScript interfaces for Account, Config, Form, EmailWorkflow, etc.
- utils/ → Utility functions: unique-ID generation, similarity (LIG3), template helpers

##### README
The README describes the connector’s runtime behavior rather than the code structure:
- Unique ID Generation (Velocity templates, normalization, scope)
- Deduplication workflow (similarity scoring, form generation, reviewer email)
- Mapping & Merging (attribute–identity mapping, multi-valued merges)
- Connector modes (Authoritative vs. Regular)
- ISC integration steps (add connector, configure, run entitlement/account aggregation, reports)

##### Main Components and Their Interactions

1) “Connector Host”
- SailPoint CLI / ISC runtime environment that invokes the connector

2) Connector Core (index.ts)
- Parses commands (aggregate-accounts, aggregate-entitlements, generate-report, etc.)
- Loads connector-spec.json and user configuration from CLI context

3) Configuration Loader
- Reads and validates “Base”, “Unique ID”, “Merging/Mapping” sections

4) Service Layer
- UniqueIDService: applies Velocity template, normalization, counter logic
- DeduplicationService: computes LIG3 similarity scores, decides if a form is needed
- MergeService: merges multi-valued attributes (first-found, concatenation, multi-valued entitlements)
- ReportService: generates deduplication report, triggers form creation

5) SDK Client (sdk-client.ts + axios.ts)
- Abstraction over ISC REST APIs: GET existing identities/accounts; POST account updates, forms, entitlements

6) Data Models (model/*)
- Strongly-typed payloads for requests/responses: Account, FormInstance, Workflow, Config, Status

7) Utilities (utils/*)
- unique.ts: ID helper, UUID assignment
- lig.ts: similarity function
- index.ts: miscellaneous helpers

8) Tests
- __tests__ use CSV fixtures and HTTP mocks to validate all actions

9) CI/CD
- GitHub workflows in .github/workflows handle build, test, security scans, and deployment via CLI

10) External Systems
- ISC REST API (accounts, entitlements, forms, workflows)
- Reviewers via email (configured in EmailWorkflow model)

##### Architectural Patterns & Design Principles
- Separation of Concerns – orchestration, configuration, services, HTTP client, utilities
- Command/Action Pattern – each connector command is a discrete action in data/action.ts
- Adapter/Facade – SDK Client wraps raw HTTP calls into typed methods
- Test-Driven Approach – clear boundaries validated by Jest tests and CSV fixtures

##### Essential Elements
– Component labels, boundaries, and groupings
– CI/CD flow linking GitHub workflows to test & publish steps
– External dependencies: ISC API, email service

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Connector Host
    subgraph "Connector Host"
        CLI["SailPoint CLI / ISC Runtime Env"]:::host
    end

    %% Connector Core & Actions
    subgraph "Connector Core"
        Core["Connector Core\n(src/index.ts & connector-spec.json)"]:::core
    end

    subgraph "Configuration Loader"
        ContextHelper["ContextHelper\n(src/contextHelper.ts)"]:::core
        ConfigModel["Config Model\n(src/model/config.ts)"]:::core
    end

    subgraph "Command Definitions"
        ActionDef["Action Definitions\n(src/data/action.ts)"]:::core
        StatusDef["Status Definitions\n(src/data/status.ts)"]:::core
    end

    %% Service Layer
    subgraph "Service Layer"
        UniqueID["UniqueIDService"]:::service
        Dedup["DeduplicationService"]:::service
        Merge["MergeService"]:::service
        Report["ReportService"]:::service
    end

    %% SDK Client
    subgraph "SDK Client (ISC API Adapter)"
        SDKClient["SDK Client\n(src/sdk-client.ts)"]:::sdk
        Axios["HTTP Wrapper\n(src/axios.ts)"]:::sdk
    end

    %% Data Models
    DataModels["Data Models\n(src/model/)"]:::util

    %% Utilities
    Utils["Utility Helpers\n(src/utils/index.ts)"]:::util

    %% Tests & Fixtures
    Tests["Test Harness\n(src/__tests__/ & test/)"]:::test

    %% CI/CD
    CI["GitHub Workflows\n(.github/workflows/)"]:::ci

    %% External Systems
    subgraph "External Systems"
        ISCAPI["ISC REST API"]:::external
        Email["Reviewer Email Service"]:::external
    end

    %% Connections
    CLI -->|"invoke"| Core
    Core -->|"load CLI context"| ContextHelper
    Core -->|"load CLI context"| ConfigModel
    Core -->|"register commands"| ActionDef
    Core -->|"register commands"| StatusDef

    ContextHelper -->|"provides config"| UniqueID
    ConfigModel -->|"provides config"| UniqueID
    ContextHelper -->|"provides config"| Dedup
    ConfigModel -->|"provides config"| Dedup
    ContextHelper -->|"provides config"| Merge
    ConfigModel -->|"provides config"| Merge
    ContextHelper -->|"provides config"| Report
    ConfigModel -->|"provides config"| Report

    ActionDef --> UniqueID
    StatusDef --> Dedup
    ActionDef --> Merge
    ActionDef --> Report

    UniqueID -->|"calls SDK methods"| SDKClient
    Dedup -->|"calls SDK methods"| SDKClient
    Merge -->|"calls SDK methods"| SDKClient
    Report -->|"calls SDK methods"| SDKClient

    SDKClient -->|"uses HTTP wrapper"| Axios
    Axios -->|"requests"| ISCAPI

    Report -->|"send email via"| Email

    Core -->|"executes tests"| Tests
    CI -->|"runs build & tests"| Core
    CI -->|"deploys connector"| Core
    CI -->|"triggers test harness"| Tests

    %% Click Events
    click Core "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/index.ts"
    click Core "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/connector-spec.json"
    click ContextHelper "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/contextHelper.ts"
    click ConfigModel "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/model/config.ts"
    click ActionDef "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/data/action.ts"
    click StatusDef "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/data/status.ts"
    click UniqueID "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/utils/unique.ts"
    click Dedup "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/utils/lig.ts"
    click SDKClient "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/sdk-client.ts"
    click Axios "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/axios.ts"
    click DataModels "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/tree/main/src/model/"
    click Utils "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/blob/main/src/utils/index.ts"
    click Tests "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/tree/main/src/__tests__"
    click Tests "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/tree/main/test/"
    click CI "https://github.com/sailpoint-oss/colab-saas-conn-sailpoint-identity-fusion/tree/main/.github/workflows/"

    %% Styles
    classDef host fill:#e0ffe0,stroke:#2a5934,color:#000
    classDef core fill:#e0f0ff,stroke:#1f4e79,color:#000
    classDef service fill:#d0e0ff,stroke:#162f59,color:#000
    classDef sdk fill:#ffe0b3,stroke:#99661a,color:#000
    classDef util fill:#f0e0f0,stroke:#5a5a5a,color:#000
    classDef test fill:#f9e0ff,stroke:#7a397a,color:#000
    classDef ci fill:#ffebe0,stroke:#7a3f1b,color:#000
    classDef external fill:#e0e0e0,stroke:#3a3a3a,color:#000
```
