## 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.