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/BackendDatabaseConsolidation/TASK.md 9,887 bytes · Updated Oct 23, 2026 10:44 AM EDT

Raw File

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 - Define Keycloak integration and identity contract
[x] TASK 1.2 - Add backend authentication, authorization, and tenant resolution
[x] TASK 1.3 - Wire Aspire host for Keycloak-backed local app configuration

Phase 2: Backend Application Data Ownership

[ ] TASK 2.1 - Add backend customer and tenant membership persistence
[ ] TASK 2.2 - Add backend customer API key and audit log persistence
[ ] TASK 2.3 - Merge Laravel uploaded file ownership into backend Document

Phase 3: Backend API Surface

[ ] TASK 3.1 - Add backend customer, API key, and document management endpoints
[ ] TASK 3.2 - Add backend authenticated user context and admin user-management integration

Phase 4: Laravel BFF Refactor

[ ] TASK 4.1 - Replace Laravel auth with Keycloak-backed BFF auth flow
[ ] TASK 4.2 - Refactor Laravel pages, admin flows, and file flows to backend APIs only
[ ] TASK 4.3 - Remove Laravel database-backed infrastructure and local persistence code

Phase 5: Validation and Cleanup

[ ] TASK 5.1 - Validate end-to-end BFF, auth, and tenant enforcement behavior
[ ] TASK 5.2 - 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.