Documentation AI Search & Assistant Sidebar Improvements (QA)
Executive summary
A QA batch promotion bundling improvements to the documentation portal's AI search and chat assistant. It makes the AI search backend connection more robust, adds a smoother slide-in/out animation for the assistant sidebar (now usable on narrower screens), and removes a large set of unused dependencies to slim down the project.
Why this was needed
The documentation AI search/chat feature previously fell back to a hard-coded http://localhost:1337 backend address. In hosted environments where the Strapi documentation backend URL is not configured, this caused confusing failures with no clear explanation. The assistant sidebar was also hidden on smaller viewports and appeared abruptly, hurting usability. Separately, several large unused AI-toolkit packages (CopilotKit) lingered in the dependency tree.
Client / user impact
- Documentation AI search/chat now surfaces a clear, actionable message ("the documentation search backend is not configured") instead of silently misbehaving when the backend URL is missing.
- The docs assistant sidebar slides in and out smoothly and is now accessible on narrower screens, improving the help experience for more users.
- A leaner dependency footprint improves project maintainability and build hygiene. No change to the core mail/document workflows.
Technical scope
- AI search backend config (
src/app/api/docs-chat/route.ts,src/routes/documentation.routes.ts): removed thehttp://localhost:1337default;NEXT_PUBLIC_STRAPI_URLis now required. The chat API returns HTTP 500 with an admin-facing error (and logs) when it is unset, and request-body parsing was hardened to defensively readquery/history. - Assistant sidebar UX (
src/components/documentation/DocsLayoutShell.tsx): wrapped the sidebar in Framer MotionAnimatePresencewith a spring slide-in/out from the right edge; removed thehidden xl:blockgate so it renders on smaller breakpoints. - Dependency cleanup (
pnpm-lock.yaml): removed unused CopilotKit packages (@copilotkit/react-core,react-ui,runtime, etc.), accounting for ~5,000 lockfile deletions. - Docker (
Dockerfile): addedNEXT_PUBLIC_STRAPI_URLandNEXT_PUBLIC_STRAPI_API_TOKENbuild args/env so the docs backend is configurable per deployment. - Bundles feature branch
feat-ai-search(PR #729).
Risk & mitigation
Low-to-moderate, scoped to the documentation portal. The main behavioral risk is that removing the localhost fallback means any environment missing NEXT_PUBLIC_STRAPI_URL will now return errors for AI search instead of attempting localhost; mitigated by the new explicit error message, logging, and the Docker env wiring. The removed CopilotKit packages must be genuinely unused. Mitigation: confirm the Strapi URL/token are set in QA, and verify no code path still imports CopilotKit.
QA validation focus
- With
NEXT_PUBLIC_STRAPI_URLset in QA, confirm documentation AI search/chat returns results normally. - Temporarily unset the Strapi URL and confirm the chat API returns the clear "backend is not configured" message (HTTP 500) rather than crashing or hitting localhost.
- Open/close the docs assistant sidebar and verify the slide-in/out animation is smooth; confirm it now appears and is usable on narrower/smaller screen widths.
- Smoke-test the docs portal build/start to confirm the dependency removal did not break any page.
- Send a chat request with a missing/empty
queryand confirm the validation error response is returned.