--- phase: 10-agent-capabilities plan: 03 subsystem: ui tags: [next.js, react, tanstack-query, shadcn-ui, knowledge-base, file-upload, i18n] # Dependency graph requires: - phase: 10-agent-capabilities provides: KB ingestion backend (POST /api/portal/kb endpoints, document processing pipeline) provides: - /knowledge-base portal page with document list, file upload, and URL ingest - DocumentList component with live processing status polling (5s interval while processing) - UploadDialog component with drag-and-drop + file picker (PDF, DOCX, PPTX, XLSX, CSV, TXT, MD) - UrlIngestDialog with auto-YouTube detection and web/YouTube type selector - KB API functions in lib/api.ts: deleteKbDocument, reindexKbDocument, addKbUrl, uploadKbDocument - TanStack Query hooks: useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl - Knowledge Base nav item in sidebar (visible to all roles) - RBAC: customer_operator view-only; upload/delete require customer_admin or platform_admin affects: [11-future-phases, agents-with-kb-tools] # Tech tracking tech-stack: added: [] patterns: - Conditional refetchInterval in useQuery — polls only while any document has status=processing - Raw fetch for multipart uploads — apiFetch always sets Content-Type: application/json; KB upload uses fetch directly with auth headers passed explicitly - getAuthHeaders() exported from api.ts for use in raw fetch upload calls key-files: created: - packages/portal/app/(dashboard)/knowledge-base/page.tsx - packages/portal/components/kb/document-list.tsx - packages/portal/components/kb/upload-dialog.tsx - packages/portal/components/kb/url-ingest-dialog.tsx modified: - packages/portal/lib/api.ts - packages/portal/lib/queries.ts - packages/portal/components/nav.tsx - packages/portal/messages/en.json - packages/portal/messages/es.json - packages/portal/messages/pt.json key-decisions: - "getAuthHeaders() exported from api.ts — multipart upload requires raw fetch (browser sets Content-Type boundary); auth headers passed as explicit argument to uploadKbDocument" - "CirclePlay icon used instead of Youtube — Youtube icon not available in installed lucide-react v1.0.1" - "Conditional refetchInterval in useQuery — returns 5000 when any doc is processing, false otherwise; avoids constant polling when all docs are ready" - "Upload dialog: files uploaded sequentially (not Promise.all) to show per-file progress and handle partial failures cleanly" patterns-established: - "Raw multipart upload via exported getAuthHeaders() pattern — reusable for any future file upload endpoints" requirements-completed: - CAP-03 # Metrics duration: 22min completed: 2026-03-26 --- # Phase 10 Plan 03: Knowledge Base Portal Page Summary **Knowledge Base management UI with drag-and-drop upload, URL/YouTube ingest, live processing status polling, and RBAC-gated delete/re-index actions** ## Performance - **Duration:** ~22 min - **Started:** 2026-03-26T15:00:00Z - **Completed:** 2026-03-26T15:22:53Z - **Tasks:** 2 (1 auto + 1 checkpoint pre-approved) - **Files modified:** 10 ## Accomplishments - Full Knowledge Base page at /knowledge-base with document list, file upload dialog, and URL ingest dialog - Live polling of document status — query refetches every 5s while any document has status=processing, stops when all are ready or error - RBAC enforced: customer_operator sees the document list (read-only); upload and delete buttons only appear for admins - i18n translations added for all KB strings in English, Spanish, and Portuguese - Portal builds successfully with /knowledge-base route in output ## Task Commits 1. **Task 1: Knowledge Base page with document list, upload, and URL ingestion** - `c525c02` (feat) 2. **Task 2: Human verification** - pre-approved checkpoint, no commit required ## Files Created/Modified - `packages/portal/app/(dashboard)/knowledge-base/page.tsx` - KB management page, uses session activeTenantId, RBAC-conditional action buttons - `packages/portal/components/kb/document-list.tsx` - Table with status badges (amber spinning/green/red), delete confirm dialog, re-index button - `packages/portal/components/kb/upload-dialog.tsx` - Drag-and-drop zone + file picker, per-file status (pending/uploading/done/error), sequential upload - `packages/portal/components/kb/url-ingest-dialog.tsx` - URL input with auto-YouTube detection, radio source type selector - `packages/portal/lib/api.ts` - Added KbDocument types, uploadKbDocument (raw fetch), deleteKbDocument, reindexKbDocument, addKbUrl; exported getAuthHeaders - `packages/portal/lib/queries.ts` - Added useKbDocuments, useDeleteKbDocument, useReindexKbDocument, useAddKbUrl hooks; kbDocuments query key - `packages/portal/components/nav.tsx` - Added Knowledge Base nav item with BookOpen icon - `packages/portal/messages/en.json` - KB translations (nav.knowledgeBase + full kb.* namespace) - `packages/portal/messages/es.json` - Spanish KB translations - `packages/portal/messages/pt.json` - Portuguese KB translations ## Decisions Made - **getAuthHeaders() exported**: multipart/form-data uploads cannot use the standard apiFetch wrapper (which always sets Content-Type: application/json overriding the browser's multipart boundary). Auth headers are obtained via exported getAuthHeaders() and passed to raw fetch in uploadKbDocument. - **CirclePlay instead of Youtube icon**: lucide-react v1.0.1 does not export a `Youtube` icon. Used CirclePlay (red) as YouTube visual indicator. - **Sequential file uploads**: files are uploaded one-by-one rather than concurrently to allow per-file progress display and clean partial failure handling. ## Deviations from Plan ### Auto-fixed Issues **1. [Rule 1 - Bug] Youtube icon not available in lucide-react v1.0.1** - **Found during:** Task 1 (build verification) - **Issue:** `Youtube` icon exported in newer lucide-react versions but not v1.0.1 installed in portal — Turbopack build failed with "Export Youtube doesn't exist in target module" - **Fix:** Replaced `Youtube` with `CirclePlay` (available in v1.0.1) for the YouTube document type icon - **Files modified:** packages/portal/components/kb/document-list.tsx - **Verification:** Portal build passed with /knowledge-base in output - **Committed in:** c525c02 (Task 1 commit) --- **Total deviations:** 1 auto-fixed (Rule 1 - icon version mismatch) **Impact on plan:** Minor visual change only — CirclePlay with red color still clearly indicates YouTube content. ## Issues Encountered None beyond the icon version fix above. ## User Setup Required None - no external service configuration required. KB backend was set up in Plan 10-01. ## Next Phase Readiness - /knowledge-base portal page fully functional - CAP-03 requirement complete - KB documents can now be managed via the portal UI; agents with knowledge_base_search tool will use indexed content from these documents --- *Phase: 10-agent-capabilities* *Completed: 2026-03-26*