Imported from joelvinaykumar/raga-fe (AGENTS.md). Install upstream with npx skills add joelvinaykumar/raga-fe. Copyright stays with the author.

AGENTS.md

RAGA — a Vite + React 18 + TypeScript RAG chat UI ("Rag As A Service"). Authenticated via Supabase, talks to a FastAPI backend, streams LLM answers over SSE.

Commands

• Dev server: bun dev
• Build (typecheck + bundle): bun run build — runs tsc && vite build; type errors block build
• Lint: bun run lint (Biome). No test runner / test script exists.
• Quick typecheck: bun x tsc --noEmit
• Package manager is bun (bun.lock). The husky pre-commit hook runs bun x lint-staged using bun.

Architecture

• Entry: src/main.tsx → RouterProvider; AuthProvider wraps the app. Router instance + types registered there.
• File-based routing (TanStack Router): routes live in src/routes/**. _layout.tsx is a pathless authenticated layout — its beforeLoad checks the Supabase session and throw redirect to /login; the _layout segment never appears in URLs.
• Colocated components: route-local components go in a -components/ sibling dir (e.g. src/routes/_layout/chat/-components/). Types get re-exported from the route file and imported by siblings via .. (e.g. FileAttachment from chat/index.tsx).
• Generated code: src/routeTree.gen.ts is auto-generated by the @tanstack/router-vite-plugin during dev/build. Never hand-edit; after adding/renaming route files restart dev or build to regenerate. Biome ignores it.
• Env: src/lib/env.ts zod-parses import.meta.env at module load and throws if VITE_BASE_URL, VITE_SUPABASE_URL, or VITE_SUPABASE_ANON_KEY are missing — the app won't boot without a .env (gitignored; mirror .env).
• Backend: FastAPI at VITE_BASE_URL. Axios (src/lib/axios.ts) injects Authorization: Bearer <supabase access_token> in a request interceptor and toasts API errors in a response interceptor. Endpoints used: list-sessions, chat-history/{session_id}, list-docs/{session_id}, upload-doc/{session_id}, delete-doc, delete-session/{session_id}, POST /chat.
• SSE streaming: src/lib/stream.ts uses raw fetch (not axios, so no auth header/interceptor applies), POSTs to /chat, parses data: {content, done} lines. A new stream() call aborts the previous in-flight stream via a shared AbortController.
• State: TanStack Query for server state, Zustand (src/store/index.ts) for persisted auth flags, Supabase for auth.
• Deploy: Vercel. vercel.json rewrites all paths to index.html (SPA fallback required for router history URLs — direct loads/refreshes on /chat/... 404 without it).

Coding standards

• Strict TS: tsconfig.json has strict, noUnusedLocals, noUnusedParameters — unused imports/vars fail bun run build.
• Formatting: Prettier (.prettierrc, 2 spaces) runs on commit via lint-staged. biome.json's formatter settings (tabs/4) are not applied to the codebase — match the existing 2-space style; run prettier --write before committing.
• Lint: Biome (bun run lint). noUnusedVariables is an error; noExplicitAny is off (loose any is accepted). Auto-fix with bun run lint --write.
• Buttons: the shadcn Button does not set type; native default is type="submit". Non-form buttons need explicit type="button", and pass no args to handlers (onClick={() => fn()}) — route onSubmit(message?) treats its first arg as the chat message.
• UI: shadcn/ui primitives in src/components/ui/*, cn() from @/lib/utils, Tailwind, sonner toasts, framer-motion, lucide icons, @/ alias → src.
• Empty states: every component that renders a collection must handle the empty case explicitly — never render a bare/interactive-but-useless control. e.g. a select/dropdown with no options must be disabled and show a placeholder like "No options available"; lists, tables, and menus show an empty-state message instead of a blank area. Also handle loading and error states so the component never renders nothing.
• Markdown: @/components/custom/markdown is a thin React.lazy wrapper (Suspense) around markdown-impl.tsx, which holds the heavy react-markdown + remark/rehype stack — keep it code-split so it stays out of the initial bundle. The renderer is intentionally lean: GFM only (remark-gfm, rehype-raw, rehype-slug). No KaTeX/math, syntax-highlighter, or emoji deps — don't re-add them without cause. Only framer-motion is used for animation (the motion package was removed).

Known issues

• Initial chat jitter (new chat): the first message is typed on /chat and passed to /chat/{sessionId} via location.state.query, which src/routes/_layout/chat/$sessionId/index.tsx replays in a mount effect. Because main.tsx wraps in <StrictMode>, that effect double-fires in dev. The file guards this with an initialQuerySubmittedRef ref plus a cancelled flag in the effect cleanup, and onSubmit early-returns if (isStreaming). Do not remove these guards: without them onSubmit runs twice, producing duplicate prompt/reply pairs and one reply stuck loading: true forever (the second stream() aborts the first via the shared AbortController). The Enter key in the input still fires onSubmit even though the send button is disabled while loading.
• Chat streaming animation bug: message-bubble.tsx re-mounts the markdown node on every chunk via key={msg.loading ? \s-${msg.content.length}` : "static"}, re-triggering the .markdown-streaming fade-inanimation (defined insrc/index.css). Combined with the per-chunk flushSyncin$sessionId/index.tsx`, every token causes a full synchronous re-render plus a CSS animation restart → visible flicker/jitter while streaming. Fix direction: animate without remounting (CSS transition on opacity instead of a keyed remount) and/or batch chunk updates.
• Account page renders nothing: /account (src/routes/_layout/account/index.tsx) mounts but shows an empty page. Investigate the data source it reads (user/profile query) — the layout renders but its content columns come up blank, likely an unresolved/empty query or a guard that returns null before the details render.
• MCP connection — authentication still needs work: the MCP connection flow is buggy and not yet production-ready. Authentication for MCP clients (API-key provisioning/validation and scoped access) is incomplete and needs further work before it can be relied on. Fix direction: harden the MCP auth path — robust API-key issuance/rotation, consistent header validation on the server, and clear error handling on the client.

Resolved issues

• top_k limit inconsistency (fixed): previously three different caps were enforced for the same value (create form .max(10), config slider max="20", backend _resolve_top_k clamp to min(x, 30)). Now aligned to a single source of truth across the create form (src/routes/_layout/knowledge-base/new.tsx), the workspace config slider (src/routes/_layout/knowledge-base/$kbId/-components/config-sidebar.tsx), and the backend _resolve_top_k (raga-be/main.py).