Workflows

Target Architecture — Final-State Design

This page describes the final-state orchestration of the Marketplace Platform. The publishing and installation workflows are MassTransit state-machine sagas hosted by MarketplacePublishingWorker and InstallationWorker (see Workers), coordinating the catalog, versioning, compatibility, dependency, license, and review services through the canonical event envelope.

Two long-running workflows define the Marketplace's behavior: asset publishing (how an asset becomes available) and asset installation (how an asset is applied into a target). Both are sagas with explicit states, idempotent steps, and compensating actions on failure.

Asset publishing flow

A publisher submits an asset; it is quality-scanned, signed, versioned, indexed, and made available.

sequenceDiagram
    participant Pub as Publisher
    participant APS as AssetPublishingService
    participant QSW as AssetQualityScanWorker
    participant Gov as Governance Policy Gate
    participant AVS as AssetVersionService
    participant IDX as AssetIndexingWorker
    participant Cat as MarketplaceCatalogService

    Pub->>APS: PublishAsset / ReleaseAssetVersion (+ package)
    APS->>APS: Stage package to Blob (content hash)
    APS->>QSW: ScanAssetQuality
    QSW-->>APS: AssetQualityScanned (verdict, findings)
    alt quality passed
        APS->>Gov: Evaluate publishing policy
        Gov-->>APS: Policy approved
        APS->>AVS: Release version (sign package)
        AVS-->>APS: AssetVersionReleased (signed)
        APS-->>Cat: AssetPublished
        Cat->>IDX: index document
        IDX-->>Cat: AssetIndexed (asset available)
    else quality failed
        APS-->>Pub: Publication rejected (findings)
    end

Hold "Alt" / "Option" to enable pan & zoom

Steps

1. Submit & stage — the package is uploaded to the Blob staging container and addressed by content hash.
2. Quality scan — AssetQualityScanWorker runs static, structural, security, and policy checks, producing an AssetQualityScanned verdict.
3. Policy gate — the Governance policy gate evaluates publisher trust tier and asset policy; low-trust publishers require manual approval.
4. Sign & release — on approval, AssetVersionService signs the package (publisher signing key in Key Vault), promotes it to the immutable released store, and emits AssetVersionReleased.
5. Catalog & index — MarketplaceCatalogService records the catalogue entry and AssetIndexingWorker builds the search document; the asset becomes available.

Asset installation flow

An agent or user requests installation; the asset is compatibility-checked, its dependencies resolved, the license verified, then applied.

sequenceDiagram
    participant Req as Agent Mesh / Studio
    participant AIS as AssetInstallationService
    participant ACS as AssetCompatibilityService
    participant DRS as DependencyResolutionService
    participant LS as LicenseService
    participant Tgt as Target Project

    Req->>AIS: InstallAsset (assetId, version, target)
    AIS->>ACS: EvaluateCompatibility
    ACS-->>AIS: CompatibilityEvaluated (verdict)
    alt compatible
        AIS->>DRS: ResolveDependencies
        DRS-->>AIS: DependenciesResolved (graph)
        AIS->>LS: GrantLicense (check entitlement)
        LS-->>AIS: LicenseGranted
        AIS->>Tgt: Apply asset + dependencies
        Tgt-->>AIS: Applied
        AIS-->>Req: AssetInstalled
    else incompatible or conflict
        AIS-->>Req: AssetInstallationFailed (rollback)
    end

Hold "Alt" / "Option" to enable pan & zoom

Steps

1. Compatibility — AssetCompatibilityService evaluates the version against the target runtime, project, and installed assets, emitting CompatibilityEvaluated.
2. Dependency resolution — DependencyResolutionService computes the transitive graph and detects conflicts (DependenciesResolved or DependencyConflictDetected).
3. License check — LicenseService verifies/grants the tenant entitlement via ConnectSoft.Extensions.Saas.Billing (LicenseGranted).
4. Apply — the asset and its resolved dependencies are applied to the target, recording InstalledArtifactRef provenance and a RollbackToken.
5. Complete — AssetInstalled is emitted; the Knowledge and Observability platforms ingest it.

Installation state machine

stateDiagram-v2
    [*] --> Requested
    Requested --> Evaluating : compatibility check
    Evaluating --> Failed : incompatible
    Evaluating --> Resolving : compatible
    Resolving --> Failed : dependency conflict
    Resolving --> LicenseCheck : graph resolved
    LicenseCheck --> Failed : license denied
    LicenseCheck --> Applying : license granted
    Applying --> Installed : applied successfully
    Applying --> RolledBack : apply error
    Failed --> [*]
    RolledBack --> [*]
    Installed --> [*]

Hold "Alt" / "Option" to enable pan & zoom

State	Meaning	Exit
Requested	Installation accepted, saga started	→ Evaluating
Evaluating	Compatibility being checked	→ Resolving / Failed
Resolving	Dependency graph being computed	→ LicenseCheck / Failed
LicenseCheck	Entitlement being verified/granted	→ Applying / Failed
Applying	Asset and dependencies being applied	→ Installed / RolledBack
Installed	Terminal success; provenance recorded	terminal
Failed	Terminal failure before apply; nothing changed	terminal
RolledBack	Apply failed; compensations restored clean state	terminal

Failure handling and escalation

• Idempotent retries — each step deduplicates on eventId and a step-specific idempotency key; transient failures retry with exponential backoff (see Workers).
• Compensation — if Applying fails, the saga uses the RollbackToken to reverse applied artifacts, emits AssetInstallationFailed, and leaves the target in its prior clean state.
• Dependency conflicts — DependencyConflictDetected fails the saga before any change, returning actionable findings (which ranges conflict) to the requester.
• License denial — a denied or expired license fails the saga at LicenseCheck; the requester is directed to acquire/renew an entitlement.
• Dead-lettering — unprocessable messages move to a dead-letter subqueue with the full envelope preserved; the Observability tooling alerts on dead-letter growth.
• Escalation — repeated publishing-quality failures or installation rollbacks for an asset raise a governance signal that can suspend the asset or publisher trust tier, surfaced in the Publisher Portal and to Governance.

Continue to Workers, Events, and UI.