Repository Docs & Knowledge Base

Consolidated Spensara documentation repository (722 Markdown & architecture documents in ../repository)

Built Word Documents (.docx): Spensara Overview (.docx) Capability Assessment (.docx) Brink POS Ingestion Analysis (.docx) The Borg Ingestion Architecture (.docx)

Implementation Specs (157)

Detailed engineering and feature implementation specifications.

implementation-specs/specs/CustomerCredentialTriggeredProvisioning/TASK.md 7,611 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

Customer Credential Triggered Provisioning - Implementation Tasks

Overview

Implementation of the Customer Credential Triggered Provisioning delivery slice.

This task plan is derived from analysis of the current implementation in:

backend/Kds.Ai.ApiService/Services/CustomerManagementService.cs
backend/Kds.Ai.ApiService/Services/CustomerEtlProvisioningService.cs
backend/Kds.Ai.ApiService/Endpoints/AdminCustomerEndpoints.cs
backend/Kds.Ai.Data/Entities/CustomerCredentialEntry.cs
backend/Kds.Ai.Warehouse/Services/TenantWarehouseBootstrapper.cs
backend/Kds.Ai.Warehouse/Models/TenantWarehouseBootstrapRequest.cs
backend/Kds.Ai.Warehouse/Sql/Bootstrap/**
backend/tests/Kds.Ai.ApiService.Tests/Kds.Ai.ApiService.Tests/Services/CustomerEtlProvisioningServiceTests.cs
backend/tests/Kds.Ai.ApiService.Tests/Kds.Ai.ApiService.Tests/Endpoints/AdminCustomerOnboardingFlowTests.cs

The current branch blocks customer create and update for about 30 seconds because Redshift registration and bootstrap happen synchronously inside customer CRUD.

The target slice moves provisioning responsibility to credential create and update, executes provisioning asynchronously through the existing TickerQ job infrastructure, exposes explicit provisioning state for the UI, and makes tenant bootstrap source-aware so it creates staging only for enabled source systems while still creating curated artifacts for all tenants.

Source Documents

repository analysis performed during this planning session
current admin customer and credential API implementation
current warehouse bootstrap implementation and embedded SQL layout

Spec Name

This implementation spec should be referred to as Customer Credential Triggered Provisioning.

Fixed Decisions

Customer create and update must no longer block on Redshift bootstrap.
Frontend migration to split customer basics and credentials happens immediately.
Customer create and update become customer-data-only operations.
Credential create and update trigger provisioning asynchronously through a background job.
Credential delete must not enqueue bootstrap or any warehouse cleanup job.
Credential delete must not modify warehouse schema or remove historical warehouse data.
Provisioning state must expose explicit async execution status for the admin UI.
Source-aware bootstrap selection must use CustomerCredentialEntry.Service as the source selector.
The bootstrapper may inspect the protected payload only for service-specific runtime flags such as Enabled.
Tenant bootstrap must always apply foundation and curated artifacts.
Tenant bootstrap must apply staging artifacts only for enabled source services.
The current implementation starts with CustomerCredentialService.BrinkPos, but the design must remain extensible for future services.

Scope

This task includes:

redefining admin customer and credential flow boundaries,
persisting and exposing async provisioning execution state,
introducing a background provisioning job using TickerQ,
removing synchronous provisioning from customer CRUD,
removing inline customer credential handling from the main customer create and update flow,
extending warehouse bootstrap requests with enabled source services,
refactoring tenant bootstrap SQL loading so staging is source-selective and curated remains global,
adding regression coverage for async provisioning and selective bootstrap.

In short, this slice ends when customer CRUD is fast, credential writes drive provisioning asynchronously, the UI can observe provisioning progress, and tenant bootstrap creates only the staging artifacts required by enabled credential services.

Out of Scope

The following items are explicitly excluded from this task:

warehouse teardown or schema removal when credentials are deleted,
warehouse data deletion when credentials are deleted,
introducing non-TickerQ background processing infrastructure,
redesigning the credential payload model for services beyond the current source set,
changing ETL runtime semantics beyond provisioning trigger and readiness status,
changing curated SQL semantics unless required by selective staging dependencies.

Task Checklist

Phase 1: Flow And Status Contract

[ ] TASK 1.1 - Define split admin flow and credential-trigger boundaries
[ ] TASK 1.2 - Persist and expose async provisioning state for the admin UI

Phase 2: Background Provisioning Orchestration

[ ] TASK 2.1 - Add background provisioning job and enqueue it from credential create and update
[ ] TASK 2.2 - Remove synchronous customer provisioning and inline credential handling from customer CRUD

Phase 3: Source-Aware Bootstrap

[ ] TASK 3.1 - Resolve enabled source services and extend bootstrap requests
[ ] TASK 3.2 - Refactor tenant bootstrap SQL loading to selected staging plus global curated

Phase 4: Verification

[ ] TASK 4.1 - Add regression coverage for async provisioning and selective bootstrap

Dependency Graph

text

Phase 1 (Flow And Status Contract)
    |-- 1.1 Split admin flow and trigger boundaries
    +-- 1.2 Async provisioning state contract <-- depends on 1.1

Phase 2 (Background Provisioning Orchestration)
    |-- 2.1 Background provisioning job and enqueue path <-- depends on 1.1, 1.2
    +-- 2.2 Customer CRUD cleanup and inline credential removal <-- depends on 1.1, 2.1

Phase 3 (Source-Aware Bootstrap)
    |-- 3.1 Enabled service resolution and bootstrap request model <-- depends on 1.1, 2.1
    +-- 3.2 Selective staging bootstrap and global curated bootstrap <-- depends on 3.1

Phase 4 (Verification)
    +-- 4.1 Regression coverage <-- depends on 2.1, 2.2, 3.1, 3.2

Recommended Session Order

Session	Tasks	Description
1	1.1, 1.2	Lock the backend and frontend flow boundary plus the provisioning state contract
2	2.1	Add the TickerQ provisioning job and enqueue path
3	2.2	Remove synchronous provisioning and inline credential handling from customer CRUD
4	3.1, 3.2	Make provisioning service and bootstrapper source-aware
5	4.1	Add regression coverage and validate end-to-end behavior

Key Design Decisions

Credential Lifecycle Owns Provisioning

The source connection becomes real only when credentials are created or updated. That is the correct place to enqueue provisioning.

Delete Never Cleans Up Warehouse

Credential delete is intentionally not a teardown signal. It may change ETL readiness, but it must not remove schema or warehouse data.

TickerQ Is The Existing Background Pattern

The repository already uses TickerQ for asynchronous work. This slice should reuse that infrastructure instead of introducing a second background execution model.

Service Enum Is The Bootstrap Selector

Bootstrap routing should use CustomerCredentialEntry.Service, not the protected Credentials blob. The protected payload should only be read for service-specific runtime flags such as Enabled.

Curated Always Exists, Staging Is Selective

Foundation and curated artifacts remain part of every tenant bootstrap. Only staging becomes source-aware.

Immediate Frontend Split

This slice assumes the frontend is migrated immediately to separate customer basics from credential operations. The main customer create and update flow should no longer handle inline credentials.