Spensara Spensara Knowledge Base & Documentation Repository
System Overview Brink & Borg Master Index (722 Docs) Spensara Platform Project Tracker

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)

Categories

Implementation Specs (157)

Detailed engineering and feature implementation specifications.
implementation-specs/specs/EtlSourceAdapterFramework/TASK5.md 5,008 bytes · Updated Oct 23, 2026 10:44 AM EDT
Raw File

TASK 5: Migrate The Current Brink POS Pipeline To The Framework Contracts

Summary

Migrate the current active Brink POS ETL path so it uses the extracted framework contracts instead of remaining a one-off orchestration chain.

Implementation Status

Status: implemented.

Verified in code:

  • Brink adapter exists in backend/Kds.Ai.Integrations/BrinkPos/BrinkPosSourceAdapter.cs,
  • the four active stage wrappers exist in BrinkPosExtractStage.cs, BrinkPosNormalizeLoadStage.cs, BrinkPosLoadToStagingStage.cs, and BrinkPosStagingToCuratedStage.cs,
  • BrinkPosEtlJobs no longer uses a hardcoded four-call sequence and instead invokes IEtlPipelineRunner,
  • DI wiring registers the runner, helper services, Brink stages, and IEtlSourceAdapter in backend/Kds.Ai.Integrations/DependencyInjectionExtensions.cs,
  • Brink adapter stage ordering is covered in backend/tests/Kds.Ai.Integrations.Tests/BrinkPos/BrinkPosEtlCatalogTests.cs.

This task is the proof that the new framework boundary is practical.

The goal is not to broaden Brink scope. The goal is to make the current active Brink pipeline the first real source adapter implementation.

Dependencies

Files to Modify

1. Brink orchestration and stage registration

  • backend/Kds.Ai.ApiService/Jobs/BrinkPosEtlJobs.cs
  • relevant DI registration files

2. Brink stage implementations

  • backend/Kds.Ai.Integrations/BrinkPos/BrinkPosExtractJobs.cs
  • backend/Kds.Ai.Integrations/BrinkPos/BrinkPosNormalizeLoadJobs.cs
  • backend/Kds.Ai.Integrations/BrinkPos/BrinkPosLoadToStagingJobs.cs
  • backend/Kds.Ai.Integrations/BrinkPos/BrinkPosStagingToCuratedJobs.cs

3. Brink adapter metadata and registration

  • backend/Kds.Ai.Integrations/BrinkPos/**

4. Tests

  • add or extend tests under:
  • backend/tests/Kds.Ai.Integrations.Tests/BrinkPos/
  • backend/tests/Kds.Ai.ApiService.Tests/

Required Behavior

Brink becomes a source adapter

The active Brink pipeline should be represented through the new source adapter contracts.

Orchestration uses framework contracts

The current RunPipelineAsync(...) hardcoded sequence should be replaced or wrapped by framework-based orchestration.

Existing runtime semantics stay stable

The migration must preserve the current active Brink runtime behavior for:

  • stage order,
  • tenant and business-date scope,
  • batch lifecycle semantics,
  • upstream batch chaining,
  • failure behavior.

No runtime scope expansion

The migration must not use the framework task as an excuse to turn on dormant Brink paths.

Proposed Contracts

Suggested Brink migration shape:

csharp
public sealed class BrinkPosSourceAdapter : IEtlSourceAdapter
{
    public EtlSourceDescriptor Descriptor { get; }
    public IReadOnlyList<IEtlStage> GetStages();
}

Suggested stage wrappers for the active path:

csharp
public sealed class BrinkExtractStage : IEtlStage { ... }
public sealed class BrinkNormalizeLoadStage : IEtlStage { ... }
public sealed class BrinkLoadToStagingStage : IEtlStage { ... }
public sealed class BrinkStagingToCuratedStage : IEtlStage { ... }

These may internally delegate to existing services or adapted job classes. This task does not require full internal rewriting if the runtime seam becomes real.

Proposed Execution Shape

Expected migrated flow:

  1. scheduler or manual endpoint resolves the Brink adapter,
  2. orchestration calls shared IEtlPipelineRunner,
  3. the Brink adapter returns the four active stages in order,
  4. each stage executes under the shared framework contracts,
  5. existing Brink-specific extract, normalization, staging, and curated logic remains inside the adapter boundary.

Adapter Composition Guidance

The Brink adapter should own:

  • the Brink Descriptor,
  • the active stage list,
  • Brink catalogs,
  • Brink transport and parser services,
  • stage-specific validation rules.

The framework should own:

  • calling the stages in order,
  • carrying pipeline input between stages,
  • shared lifecycle helpers.

Migration Safety Guidance

The migration should preserve the following externally visible behavior:

  • manual Brink ETL trigger still runs the same active pipeline,
  • scheduled Brink ETL still iterates the same active tenants,
  • stage names remain stable,
  • batch lineage remains stable enough for existing diagnostics and reruns.

Acceptance Criteria

  • Brink is wired through the new framework contracts,
  • hardcoded pipeline sequencing is removed or reduced to framework-based composition,
  • active runtime semantics remain stable,
  • regression tests cover the migrated orchestration path.

Notes

  • Keep the migration limited to the current active Brink path.
  • If some stage internals stay source-specific, that is acceptable as long as the framework seam is real and reusable.
  • Prefer wrapping existing stage services over rewriting all stage internals in one step.