Implementation Plan: Unified AI Architecture

Branch: 301-unified-ai-arch | Date: 2026-05-14 | Spec: spec.md Input: Feature specification from specs/300-others/301-unified-ai-arch/spec.md

Summary

Implement a Master AI Architecture enforcing strict physical isolation of AI workloads on a dedicated Admin Desktop (Desk-5439). The system supports secure legacy document migration via a staging queue, context-aware conversational RAG queries, and detailed AI audit logging, all orchestrated through robust backend queues (BullMQ) and multi-tenant security filters.

Technical Context

Language/Version: TypeScript (Node.js v24.15.0) for Backend/Frontend Primary Dependencies: NestJS 11, Next.js 16, BullMQ, Qdrant Node Client, n8n Storage: MariaDB 11.8 (Relational), Qdrant (Vector), Redis (Queue/Cache) Testing: Jest (Backend), Vitest (Frontend), E2E with Playwright Target Platform: QNAP Container Station (Production), Desk-5439 (AI Host) Project Type: Monorepo Web Application (Backend + Frontend) Performance Goals: RAG Response < 10s (p95), Migration throughput 1000 pages/hour Constraints: AI host has limited VRAM (8GB), necessitating concurrency limit of 1 for LLM generation. Scale/Scope: 20,000+ legacy documents, project-wide deployment.

Constitution Check

GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.

ADR-019 UUID: publicId used exclusively. No INT primary keys exposed.
ADR-009 Database: Schema changes via raw SQL deltas.
ADR-016 Security: CASL RBAC strictly enforced (@UseGuards(CaslAbilityGuard)). Idempotency-Key headers required.
ADR-008 BullMQ: Heavy AI orchestration and RAG queuing managed via BullMQ.
ADR-018/023 AI Boundary: AI host connects via DMS API. No direct database access.
TypeScript Strict: Explicit types, no any, proper error handling via BusinessException.

Project Structure

Documentation (this feature)

specs/300-others/301-unified-ai-arch/
├── spec.md
├── plan.md              # This file
├── research.md          
├── data-model.md        
├── quickstart.md        
├── contracts/           
└── tasks.md             # (To be created)

Source Code (repository root)

backend/
├── src/
│   ├── ai/
│   │   ├── ai.module.ts
│   │   ├── ai.controller.ts
│   │   ├── ai.service.ts
│   │   ├── qdrant.service.ts
│   │   ├── rag.processor.ts
│   │   └── dto/
│   └── database/
│       └── sql/

frontend/
├── src/
│   ├── app/(dashboard)/ai-staging/
│   ├── components/ai/
│   │   ├── AiStatusBanner.tsx
│   │   └── RagChatWidget.tsx
│   └── lib/api/ai.ts

Structure Decision: Integrated into the existing Next.js / NestJS monorepo architecture, utilizing a dedicated AiModule in the backend to centralize all external AI API calls and queue management.

3.0 KiB Raw Blame History