# Backend Database Consolidation - Implementation Tasks ## Overview Implementation of the **backend database consolidation** delivery slice. This task plan is derived from analysis of the current repository state across: - `backend/Kds.Ai.Data` - `backend/Kds.Ai.ApiService` - `backend/Kds.Ai.WarehouseDataModel` - `Front/app` - `Front/config` - `Front/routes` - `Front/database/migrations` This slice consolidates all application-owned persistence into the backend and converts the Laravel app into a stateless BFF with no database connection. The slice outcome is: - backend becomes the system of record for application data, - Keycloak becomes the system of record for user identity and login, - Laravel no longer owns users, customers, API keys, uploaded file metadata, or activity logs, - Laravel no longer uses database-backed auth, sessions, cache, or queue configuration, - backend document storage absorbs the current Laravel `uploaded_files` responsibilities, - tenant resolution and authorization no longer depend on a front-end database lookup or a spoofable tenant header. ## Source Documents - repository analysis of `backend/` and `Front/` performed during this planning session - `backend/Kds.Ai.Data/KdsAiDbContext.cs` - `backend/Kds.Ai.Data/Entities/Document.cs` - `backend/Kds.Ai.ApiService/Program.cs` - `backend/Kds.Ai.ApiService/Tenancy/TenantMiddleware.cs` - `backend/Kds.Ai.ApiService/Endpoints/DocumentEndpoints.cs` - `Front/app/Models/User.php` - `Front/app/Models/Customer.php` - `Front/app/Models/CustomerApiKey.php` - `Front/app/Models/UploadedFile.php` - `Front/app/Models/ActivityLog.php` - `Front/app/Http/Controllers/LoginController.php` - `Front/app/Http/Controllers/Admin/AdminAuthController.php` - `Front/app/Http/Controllers/Admin/AdminApiController.php` - `Front/app/Http/Controllers/Admin/UsersController.php` - `Front/app/Http/Controllers/FilesController.php` - `Front/app/Http/Controllers/DashboardController.php` - `Front/app/Services/AiApiService.php` - `Front/config/auth.php` - `Front/config/session.php` - `Front/config/cache.php` - `Front/config/queue.php` ## Spec Name The canonical implementation spec should be referred to as **Backend Database Consolidation**. ## Fixed Decisions - Laravel must become a stateless BFF with no database connection. - Laravel must not use database-backed sessions. - Authentication and user identity move to Keycloak. - Backend becomes the system of record for application-owned data. - Existing local Laravel data does not need to be preserved because the system is not yet deployed to production. - Laravel `uploaded_files` responsibilities should be merged into backend `Document` ownership instead of creating a separate long-term file metadata system. - The warehouse database used through `Kds.Ai.WarehouseDataModel` remains separate and out of scope. - The current backend pattern of trusting `X-Tenant-Id` without authentication is not acceptable after this migration. ## Scope This task includes: - adding Keycloak-based authentication and authorization integration, - replacing backend tenant resolution based on raw request headers with identity-backed tenant resolution, - introducing backend entities and APIs for customer/tenant management, - introducing backend entities and APIs for customer API key management, - extending backend `Document` ownership to cover current file metadata and dashboard use cases, - introducing backend audit logging if the current admin activity history remains required, - refactoring Laravel controllers, middleware, views, and services to use backend APIs and Keycloak-backed identity only, - removing Laravel reliance on local Eloquent models and local persistence, - switching Laravel session, cache, and queue configuration away from database-backed providers, - deleting obsolete Laravel persistence code after cutover. In short, this slice ends when Laravel can run as a DB-free BFF in front of Keycloak and backend APIs, while backend owns all application persistence. ## Out of Scope The following items are explicitly excluded from this task: - migrating or redesigning the warehouse read model in `backend/Kds.Ai.WarehouseDataModel`, - preserving pre-production Laravel data, - production infrastructure rollout for Keycloak, - multi-region identity architecture, - end-user self-service registration flows unless separately requested, - redesign of anomaly detection, monitor runtime, or warehouse ETL behavior unrelated to tenant/auth consolidation. --- ## Task Checklist ### Phase 1: Identity and Tenant Resolution - [x] [TASK 1.1](./TASK1.1.md) - Define Keycloak integration and identity contract - [x] [TASK 1.2](./TASK1.2.md) - Add backend authentication, authorization, and tenant resolution - [x] [TASK 1.3](./TASK1.3.md) - Wire Aspire host for Keycloak-backed local app configuration ### Phase 2: Backend Application Data Ownership - [ ] [TASK 2.1](./TASK2.1.md) - Add backend customer and tenant membership persistence - [ ] [TASK 2.2](./TASK2.2.md) - Add backend customer API key and audit log persistence - [ ] [TASK 2.3](./TASK2.3.md) - Merge Laravel uploaded file ownership into backend `Document` ### Phase 3: Backend API Surface - [ ] [TASK 3.1](./TASK3.1.md) - Add backend customer, API key, and document management endpoints - [ ] [TASK 3.2](./TASK3.2.md) - Add backend authenticated user context and admin user-management integration ### Phase 4: Laravel BFF Refactor - [ ] [TASK 4.1](./TASK4.1.md) - Replace Laravel auth with Keycloak-backed BFF auth flow - [ ] [TASK 4.2](./TASK4.2.md) - Refactor Laravel pages, admin flows, and file flows to backend APIs only - [ ] [TASK 4.3](./TASK4.3.md) - Remove Laravel database-backed infrastructure and local persistence code ### Phase 5: Validation and Cleanup - [ ] [TASK 5.1](./TASK5.1.md) - Validate end-to-end BFF, auth, and tenant enforcement behavior - [ ] [TASK 5.2](./TASK5.2.md) - Remove obsolete code paths and document final architecture --- ## Dependency Graph ``` Phase 1 (Identity and Tenant Resolution) |-- 1.1 Keycloak integration and identity contract |-- 1.2 Backend authentication, authorization, and tenant resolution <-- (depends on 1.1) +-- 1.3 Aspire host wiring for Keycloak-backed local configuration <-- (depends on 1.1) Phase 2 (Backend Application Data Ownership) <-- depends on 1.2 |-- 2.1 Customer and tenant membership persistence |-- 2.2 Customer API key and audit log persistence <-- (depends on 2.1) +-- 2.3 Merge uploaded file ownership into backend Document <-- (depends on 2.1) Phase 3 (Backend API Surface) <-- depends on Phase 2 |-- 3.1 Customer, API key, and document management endpoints +-- 3.2 Authenticated user context and admin user-management integration <-- (depends on 1.1, 1.2, 2.1) Phase 4 (Laravel BFF Refactor) <-- depends on Phase 3 |-- 4.1 Replace Laravel auth with Keycloak-backed BFF auth flow |-- 4.2 Refactor pages, admin flows, and file flows to backend APIs only <-- (depends on 4.1, 3.1, 3.2) +-- 4.3 Remove Laravel DB-backed infrastructure and local persistence code <-- (depends on 4.2) Phase 5 (Validation and Cleanup) <-- depends on all |-- 5.1 End-to-end validation +-- 5.2 Cleanup and architecture documentation ``` --- ## Recommended Session Order | Session | Tasks | Description | |---------|-------|-------------| | 1 | 1.1, 1.2, 1.3 | Define Keycloak contract, secure backend identity/tenant enforcement, and wire local Aspire resources | | 2 | 2.1, 2.2 | Add backend ownership for customers, membership, API keys, and audit logs | | 3 | 2.3, 3.1 | Merge file metadata into `Document` and expose management APIs | | 4 | 3.2, 4.1 | Add user context/admin integration and switch Laravel auth to Keycloak | | 5 | 4.2, 4.3 | Refactor Laravel UI/BFF flows and remove all DB dependencies | | 6 | 5.1, 5.2 | Validate full flow and remove obsolete code | --- ## Key Design Decisions ### Keycloak Owns Identity The old Laravel `users` table should not be recreated as the long-term source of truth in backend. Identity concerns belong in Keycloak: - login, - logout, - credentials, - user lifecycle, - roles/claims. Backend may still need app-owned user linkage data keyed by Keycloak subject when tenant membership or app-specific authorization cannot live entirely in token claims. ### Backend Owns Application Data The backend must own all application-level data previously stored in Laravel: - customers, - customer API keys, - file/document metadata, - activity/audit logs if retained, - tenant membership or user-to-customer mapping if needed for authorization. ### Tenant Resolution Must Be Identity-Backed The current backend middleware trusts `X-Tenant-Id` from the caller. That is acceptable only for pre-auth local development and must not remain the production authorization mechanism. After this migration, tenant scope must come from verified identity, either: - directly from trusted Keycloak claims, or - from backend-owned membership lookup keyed by the authenticated Keycloak subject. ### Laravel Must Be DB-Free Laravel should not keep a hidden residual database dependency through: - `auth` provider, - session storage, - cache storage, - queue storage, - local admin CRUD, - local file metadata. This slice is complete only when Laravel can run without a configured database connection. ### Merge UploadedFile Into Document Backend `Document` already covers part of the current file metadata model. Extend it to serve the dashboard and document management UX instead of creating a parallel long-term file entity surface. ### No Legacy Data Migration Required Because the system is not yet deployed to production, the implementation can prefer clean replacement over compatibility layers, historical data migration, or temporary synchronization between Laravel and backend data stores.