Skip to content

Home

Jump to bottom
Maruf Bepary edited this page Jun 17, 2026 · 4 revisions

Project Overview

Next.js 16 AI chat client using Better Auth. UI features branching message trees, Mermaid diagrams, and KaTeX. Real AI responses stream via any OpenAI-compatible AI provider/Vercel AI SDK, with support for reasoning tokens, files, and MCP servers.

Features

  • Chat UI with branching (editing creates siblings).
  • Streaming responses with collapsible <Thinking> tokens.
  • Functional file support (Images, PDFs, Text, XLSX) via MinIO/Presigned URLs. XLSX uses MCP file bridge (local staging, path injection, auto-re-upload).
  • MCP tool support (stdio/HTTP); selectable per-message via dialog.
  • Slash-commands (/shortcut); prepends content to AI calls (hidden in UI).
  • PostgreSQL persistence (Server Actions).
  • Projects (shared system prompts) and Assistants (personas).
  • Knowledge bases (UI-only).
  • Mermaid/KaTeX rendering plus Artifact side panel.
  • Auth: Email/Pass, GitHub/Discord OAuth, Passkeys, TOTP 2FA.
  • Session tracking (fingerprinting/revocation).
  • Transactional emails via Postmark.
  • Artifacts/Canvas: Multi-view (Markdown, XLSX, HTML, Mermaid). AI triggers manage_artifact tool; supports streaming, edits, and export.
  • Advanced Editing: Edit messages using full ChatInput controls (model picker, tools, attachments); settings are persisted in message metadata and recovered when navigating branches.
  • Persistent Context: User artifact edits save to DB and re-inject into AI context as tool-result history.

Tech Stack

  • Framework: Next.js 16.2.4 (App Router, Turbopack)
  • Language: TypeScript 5, React 19.2.5
  • DB: PostgreSQL (Drizzle ORM v0.45.2)
  • Auth: Better Auth v1.6.8 (Passkey/2FA)
  • Styling: Tailwind v4.2.4, Shadcn (Radix), @base-ui/react v1.4.1
  • State: Zustand v5.0.12
  • Forms: React Hook Form v7.73.1 + Zod v4.3.6
  • Containers: Podman
  • Storage: MinIO (AWS SDK v3.1036.0)
  • AI SDK: Vercel AI SDK v6.0.168, @ai-sdk/openai v3.0.53, @ai-sdk/mcp v1.0.36
  • MCP: @modelcontextprotocol/sdk v1.29.0
  • Libraries: react-markdown v10.1.0, Mermaid v11.14.0, KaTeX v0.16.45, resizable-panels v4.10.0, Sonner v2.0.7, date-fns v4.1.0, unpdf v1.6.0, vaul v1.1.2, uuid v14.0.0, cmdk v1.1.1, @blocknote/react v0.49.0, xlsx v0.18.5, postmark v4.0.7, pg v8.20.0
  • MCP Languages (Optional): Python, Java, Kotlin, Go, Rust, C++ (for local servers)

Database Schema

PostgreSQL/Drizzle. Schemas in drizzle/schemas/. Types derived via InferSelectModel.

user

  • Summary: Core profiles.
  • Columns: id (PK); name/email (UNIQUE); email_verified (bool); image; two_factor_enabled; created_at/updated_at.
  • Links: 1:N session, account, passkey, chat, attachment, mcp_server, assistant, project; 1:1 two_factor.

session

  • Summary: Active sessions with fingerprints.
  • Columns: id (PK); expires_at; token (UNIQUE); ip_address/user_agent; user_id (FK); created_at/updated_at.
  • Links: N:1 user.

account

  • Summary: OAuth/Credential hashes.
  • Columns: id (PK); account_id; provider_id; password; tokens/expiry; scope; user_id (FK).
  • Links: N:1 user. Unique (user_id, provider_id).

verification

  • Summary: TTL tokens for email/reset.
  • Columns: id (PK); identifier (email); value; expires_at.

two_factor

  • Summary: TOTP secrets and backup codes.
  • Columns: id (PK); secret; backup_codes (JSON); user_id (FK).
  • Links: 1:1 user.

passkey

  • Summary: WebAuthn credentials.
  • Columns: id (PK); name; public_key; credential_id; counter; device_type; backed_up; transports; user_id (FK).
  • Links: N:1 user.

project

  • Summary: Chat groups with shared prompts.
  • Columns: id (PK); user_id (FK); name; description; global_prompt; is_pinned; timestamps.
  • Links: N:1 user. Soft ref from chat.

assistant

  • Summary: AI personas.
  • Columns: id (PK); user_id (FK); name; description; prompt; avatar; timestamps.
  • Links: N:1 user. Soft ref from chat.

chat

  • Summary: Persisted sessions.
  • Columns: id (PK); title; user_id (FK); project_id; assistant_id; current_leaf_id; timestamps.
  • Links: N:1 user, 1:N message.

message

  • Summary: Tree-structured entries.
  • Columns: id (PK); chat_id (FK); role (user/assistant/system); content; parent_id; metadata (JSON: tools/reasoning); created_at.
  • Links: N:1 chat, 1:N attachment.

attachment

  • Summary: S3 files.
  • Columns: id (PK); message_id (FK); user_id (FK); name; mime_type; size; key (UNIQUE S3); created_at.
  • Links: N:1 message, user.

mcp_server

  • Summary: stdio/HTTP tool configs.
  • Columns: id (PK); user_id (FK); name; type; command/args/url/headers/env; enabled; timestamps.
  • Links: N:1 user.

prompt

  • Summary: Reusable slash-shortcuts.
  • Columns: id (PK); user_id (FK); title; shortcut; content; timestamps.
  • Links: N:1 user.

Reusable Code & Directory Structure

  • Chat Components (components/chat/)

    • ChatInput: Textarea with model/prompt logic. Full file validation/upload (limits: 3 img, 5 total; sizes 2/20/50MB). Functional ToolPickerDialog. Supports initial values and optional cancel/save modes (icon-only buttons) for message editing.
    • ChatUI: Streaming handler via useStreamResponse. Handles persistence, attachments, artifacts, and regeneration (request chain simplified; selectedResources removed).
    • ChatPageClient: Hydrates Zustand from SSR; renders ChatUI.
    • MarkdownRenderer: Renders MD, KaTeX, and Mermaid.
    • Message Sub-components: ToolCallDisplay, ThinkingDisplay, StreamingPlaceholder, MessageActions (Edit/Delete/Regenerate/Branching).
    • MessageBubble: Decomposed with extracted metadata parsing (lib/chat/parse-message-metadata.ts) and message-focused sub-components (components/chat/message/*).
    • ArtifactPanel: Tabbed right-panel (Markdown, XLSX, HTML, Mermaid). Persistent side-by-side on md+.

  • Chat Utils (lib/chat/)

    • reconstruct-thread.ts: Linearizes message tree from leaf to root for rendering.
    • get-deepest-leaf.ts: Finds terminal nodes by following the last child at each level.

  • Shared Components (components/shared/)

    • ResourceListPage: Searchable grid for lists.
    • DeleteConfirmDialog / RenameDialog: Common entity actions.
    • ErrorPage / NotFoundPage: Reusable route-level wrappers for error and not-found states.
    • AuthenticatedLayout: Guards routes; provides sidebar and breadcrumbs.
    • ResponsiveMenu: Desktop Dropdown / Mobile Drawer.
    • SidebarTabs: Specialized layout wrapper for Shadcn UI tabs providing a vertical, right-aligned sidebar design for detail pages (Projects, Assistants, MCP Servers).

  • MCP/Assistant/Project/Prompt Components: CRUD UIs, server detail pages, shared MCP server form fields (components/mcp/server-form-fields.tsx), and slash-command palettes (cmdk).

  • Store (lib/store/index.ts)

    • Zustand monolithic store with domain slices. Large slices (e.g., EntitySlice) are decomposed into dedicated files per function within domain-specific subdirectories (e.g., lib/store/slices/entity/projects/). Actions manage optimistic state synced via DB-backed functions (createProjectDb, etc.). Mappers handle DB-to-store conversion.

  • Auth / Schemas / Actions: Better Auth config, Zod validation for all entities (centralized in schemas/), and ownership-guarded Server Actions for persistence.

  • MCP Library (lib/mcp/)

    • Decomposed into dedicated files per function. Includes tool discovery (discover-tools-and-resources.ts), transport building (build-transport.ts), server actions (list-mcp-servers.ts, create-mcp-server.ts, etc.), and File Bridge (download-attachments-to-temp.ts, persist-modified-files.ts, and cleanup-temp-dir.ts). Connects LLM to local staged spreadsheets with SSRF protection and timeout safety.

  • Storage / Attachments: AWS SDK S3/MinIO helpers. Client-side file processing, MIME resolution, and PDF/Text extraction.

  • Hooks: useStreamResponse (AI loop), useAutoExpandingTextarea (shared textarea behavior), usePromptCommands (slash-commands), useEntityOptions (shared CRUD logic).

  • Types (types/)

    • artifact.ts: ArtifactData interface for multi-view artifacts.
    • tool-call.ts: ToolCallState interface for streaming tool execution.
    • message.ts: Core Message and tree structure types.
    • discovered-tool.ts, discovered-resource.ts, mcp-connection.ts: Centralized MCP types.
    • bridged-file.ts, file-bridge-result.ts, modified-attachment.ts: File bridge metadata and result types.
    • Domain types for Chat, Assistant, Project, Attachment, etc.

Design & Architecture

Pattern

App Router: (main)/ (Auth-guarded/Sidebar), auth/ (Public), api/auth/ (Better Auth).

Data Flow

Browser -> App Router -> Server Actions/API -> DB (Drizzle) / S3 (MinIO) / AI (User's Selected Provider).

Key Decisions

  • Zustand + PG: Optimistic UI with reliable persistence.
  • Message Tree: parentId links allow branching; currentLeafId tracks active path.
  • Upload Order: Messages persist before S3 uploads to ensure ownership.
  • ID Stability: Client-generated UUIDs persist to DB for stable file bridging.
  • Prompt Injection: Project/Assistant prompts prepended server-side in API.
  • GPT OSS Default: Natively supports tool calling for MCP.
  • Excel MCP: Uses Python excel-mcp. Staging via /tmp/[uuid] with EXCEL_MCP_ALLOWED_DIRS overrides.
  • SSE Protocol: Events for text, reasoning, tool-call, tool-result, and file-modified.
  • Artifacts: Internal manage_artifact tool. User edits re-validate paths and update DB metadata for AI context re-injection.
  • SDK v6: Strict compliance using { type: "json", value: ... } for tool outputs.
  • Import Strategy: Avoid barrel files (index.ts) for modules containing Server Actions or server-only logic to prevent bundling issues in Client Components. Use direct file imports instead.
  • Schema Centralization: API request schemas (e.g., chatRequestSchema) and internal tool schemas (e.g., manageArtifactSchema) are centralized in schemas/chat.ts to maintain consistency across the pipeline.
  • Request Payload Simplification: selectedResources was removed from the chat request schema and client call chain.
  • MCP Connection Cleanup: MCP connection setup now performs client cleanup on connection failures (lib/mcp/connect-server.ts).
  • Vertical Tabs: Right-aligned vertical tab pattern for detail/settings pages (Projects, Assistants, MCP Servers) to improve focus and navigation. Projects use decomposed tabs (e.g., separating "Prompt" from "Settings").
  • Editing Metadata Persistence: Model and tool selections are persisted in the user message's metadata JSON, allowing for exact context recovery and configuration consistency when editing or branching from an older message.

Component Patterns

  • BetterAuthActionButton: Normalises Better Auth mutation responses with toasts.
  • ActionButton: General useTransition wrapper for async tasks.

Developer Workflows

  • DB: db:migrate, auth:generate, db:generate, db:push, db:studio.
  • App: podman compose up -d (Infra), npm run dev (Turbopack), npm run build.

References

Clone this wiki locally