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

Branches (328)

Branch-specific documentation across extract-raw-xml, feature-fleet-import, kds_cdc_improvments, life-cycle, and tenat-admin.
branches/tenat-admin/architecture/docs/features/tenant-admin-control-plane/implementation-notes.md 7,858 bytes · Updated Oct 23, 2026 10:44 AM EDT
Raw File

Tenant Admin Control Plane Implementation Notes

Purpose

This document turns the feature proposal into a concrete implementation checklist for the backend team.

Use it as a working task list for the PoC. Each task is intentionally short, concrete, and mapped to a main repository area.

Task List

1. Add client business entity

  • [ ] Add Client entity with ClientId, Name, Code, IsActive, CreatedAt, UpdatedAt.
  • [ ] Enforce immutable generated Code and unique constraint.

Reference:

  • entities: backend/Kds.Ai.Data/Entities/
  • EF context: backend/Kds.Ai.Data/

2. Add tenant business entity

  • [ ] Add Tenant entity with TenantId, ClientId, Name, Code, DatabaseName, Status, IsActive, CreatedAt, UpdatedAt.
  • [ ] Enforce unique (ClientId, Name), globally unique Code, and globally unique DatabaseName.
  • [ ] Keep Code and DatabaseName immutable after creation.

Reference:

  • entities: backend/Kds.Ai.Data/Entities/
  • EF context: backend/Kds.Ai.Data/

3. Add tenant systems storage

  • [ ] Add TenantSystem entity or equivalent relational child record for tenant system names.
  • [ ] Store both display value and normalized comparison value.
  • [ ] Enforce case-insensitive deduplication per tenant.

Reference:

  • entities: backend/Kds.Ai.Data/Entities/
  • EF context: backend/Kds.Ai.Data/

4. Generate codes and database names

  • [ ] Add application logic that generates Client.Code from client name.
  • [ ] Add application logic that generates Tenant.Code from tenant name.
  • [ ] Derive Tenant.DatabaseName from Tenant.Code and validate against Redshift naming rules.

Reference:

  • application/services: backend/
  • warehouse-related validation: backend/Kds.Ai.Warehouse/

5. Add EF mappings and migration

  • [ ] Register new entities in the EF Core model.
  • [ ] Add migration for Clients, Tenants, and TenantSystems.
  • [ ] Add indexes and constraints described in the feature docs.

Reference:

  • EF context and model: backend/Kds.Ai.Data/
  • migrations: backend/Kds.Ai.Data/Migrations/

6. Align tenant warehouse mapping with the new tenant model

  • [ ] Update TenantWarehouseMappings to reference the new business tenant record.
  • [ ] Change warehouse mapping TenantId to Guid if still string-based in the current flow.
  • [ ] Keep warehouse mapping as a technical table, not the primary business source.

Reference:

  • entities and repositories: backend/Kds.Ai.Data/
  • warehouse services: backend/Kds.Ai.Warehouse/

7. Add client repository operations

  • [ ] Add create and list operations for clients.
  • [ ] Keep repository behavior focused on persistence and uniqueness checks.

Reference:

  • repositories: backend/Kds.Ai.Data/Repositories/

8. Add tenant repository operations

  • [ ] Add create operation for tenant under the current client.
  • [ ] Add list operations for tenants by current client.
  • [ ] Persist tenant systems together with tenant creation.

Reference:

  • repositories: backend/Kds.Ai.Data/Repositories/

9. Add admin client endpoints

  • [ ] Add POST /admin/clients.
  • [ ] Add GET /admin/clients.
  • [ ] Return contracts consistent with api-contract.md.

Reference:

  • endpoints: backend/Kds.Ai.ApiService/Endpoints/
  • app endpoint registration: backend/Kds.Ai.ApiService/Program.cs

10. Add admin tenant endpoints

  • [ ] Keep admin surface limited to client endpoints in the PoC.
  • [ ] Do not add admin tenant create/list/bootstrap endpoints in the PoC.

Reference:

  • endpoints: backend/Kds.Ai.ApiService/Endpoints/
  • app endpoint registration: backend/Kds.Ai.ApiService/Program.cs

11. Add client-scoped tenant endpoints

  • [ ] Add POST /client/tenants.
  • [ ] Add GET /client/tenants.
  • [ ] Add GET /client/tenants/{tenantId}.
  • [ ] Resolve current client from authentication context instead of request body or route clientId.
  • [ ] Keep client tenant create/list scoped to the authenticated client only.
  • [ ] Keep client tenant detail scoped to the authenticated client only.

Reference:

  • endpoints: backend/Kds.Ai.ApiService/Endpoints/
  • app endpoint registration: backend/Kds.Ai.ApiService/Program.cs

12. Add bootstrap trigger endpoints

  • [ ] Add POST /client/tenants/{tenantId}/bootstrap.
  • [ ] Load tenant metadata and tenant systems before triggering bootstrap.
  • [ ] Reject bootstrap when tenant has no configured systems.
  • [ ] Keep the endpoint idempotent.
  • [ ] Ensure client bootstrap verifies tenant ownership before execution.

Reference:

  • endpoints: backend/Kds.Ai.ApiService/Endpoints/
  • warehouse bootstrap flow: backend/Kds.Ai.Warehouse/

13. Keep tenant creation and bootstrap separated

  • [ ] Ensure tenant create endpoint only registers the tenant and technical warehouse mapping.
  • [ ] Do not run warehouse bootstrap inside tenant creation.

Reference:

  • API service: backend/Kds.Ai.ApiService/
  • warehouse bootstrap flow: backend/Kds.Ai.Warehouse/

14. Add client scoping abstraction

  • [ ] Add the minimum abstraction needed to resolve the current client for the client endpoint surface.
  • [ ] Keep client scoping separate from tenant scoping already used elsewhere in the application.

Reference:

  • API service: backend/Kds.Ai.ApiService/
  • data and tenancy infrastructure: backend/Kds.Ai.Data/

15. Normalize and validate systems input

  • [ ] Trim and normalize systems values before deduplication.
  • [ ] Reject duplicate system names after normalization.
  • [ ] Preserve one canonical stored/display value per system entry.

Reference:

  • API validation and application logic: backend/Kds.Ai.ApiService/, backend/Kds.Ai.Data/

16. Add status transition rules

  • [ ] New tenant starts as PendingBootstrap and inactive.
  • [ ] Successful bootstrap sets tenant to Active and active.
  • [ ] Failed bootstrap sets tenant to BootstrapFailed and inactive.

Reference:

  • business persistence: backend/Kds.Ai.Data/
  • bootstrap integration: backend/Kds.Ai.Warehouse/

17. Add API validation behavior

  • [ ] Validate missing client name and tenant name.
  • [ ] Validate duplicate tenant names inside one client.
  • [ ] Validate generated database name against Redshift rules.
  • [ ] Return clear problem details for invalid requests.

Reference:

  • API endpoints and validation: backend/Kds.Ai.ApiService/
  • data persistence rules: backend/Kds.Ai.Data/

18. Add integration tests for admin and client flows

  • [ ] Test client creation.
  • [ ] Test client-scoped tenant creation.
  • [ ] Test client-scoped tenant listing.
  • [ ] Test client-scoped tenant get by id.
  • [ ] Test tenant worker cannot read another client's tenant by id.
  • [ ] Test bootstrap rejection when tenant has no systems.
  • [ ] Test client bootstrap success/failure status transitions.
  • [ ] Test client bootstrap ownership checks.

Reference:

  • API tests: backend/tests/Kds.Ai.ApiService.Tests/

19. Update CLI and warehouse assumptions only where needed

  • [ ] Review existing warehouse CLI and bootstrap assumptions for tenant identity type and mapping lookup.
  • [ ] Adjust only the minimum needed for compatibility with the new tenant model.

Reference:

  • CLI: backend/Kds.Ai.Cli/
  • warehouse services: backend/Kds.Ai.Warehouse/

20. Update documentation references if implementation naming changes

  • [ ] Keep endpoint naming aligned with api-contract.md.
  • [ ] Keep persistence naming aligned with data-model.md.
  • [ ] Update this feature folder if implementation decisions change materially.

Reference:

  • feature docs: docs/features/tenant-admin-control-plane/

Suggested Delivery Order

  • [ ] Data model and migration first.
  • [ ] Repository layer second.
  • [ ] Admin and client read/write endpoints third.
  • [ ] Bootstrap trigger endpoints fourth.
  • [ ] Integration tests and cleanup last.