• About the Project
• Features
• Built With
• Architecture
• Getting Started
• Usage
• Roadmap
• Contributing
• License
• Contact

AI Chatbot Tree stores every message in a Conversation Tree (SSOT) and keeps the SDK view in sync by projecting the Projection Recipe (projection root + ordered sequence) into Projected Messages (UIMessage[]) before sending it to useChat. When the stream resolves, the hook commits the final user/assistant nodes back into the tree so you can branch, regenerate, or inspect historic context through Tree Navigator (D3) or Canvas (React Flow).

The Conversation Tree (nodes + parent/child links) is the single source of truth, while the chat UI only renders the Projection Recipe. Tree persistence uses lz-string compression with a checksum so the history survives reloads without storing UI-only state like zoom or locks.

• Conversation Tree SSOT + _pathCache for fast ancestor traversal.
• Projection Recipe (root + sequence) that explicitly defines SDK context, with reorder/remove controls and cross-branch composition.
• useTreeChat projector/orchestration that unlocks the tree when streaming finishes, creates placeholders for user/assistant nodes, and exposes sendIsolated, regenerate, and addManualMessage.
• Context engineering panel for export/import/reset, projection preview, and statistics (recipe count, ratio, preview snippet).
• D3-based Tree Navigator and XYFlow Canvas visuals to explore the whole tree and highlight the Projection Recipe with virtual edges for non-parent adjacency.
• Manual message dialog with isolated root toggle, branch selector inside chat messages, and retry/copy helpers.
• Local API route /api/chat that forwards Projected Messages (UIMessage[]) through streamText while honoring a configured responseId.

• Next.js 16 (App Router)
• AI SDK v6 (ai, @ai-sdk/react)
• Zustand
• D3
• React Flow
• Shadcn UI (Radix)
• AI Elements
• Tailwind CSS v4

• Conversation Tree (src/stores/tree-store.ts): nodes map, projection recipe state, canvas state, parts, lock flag, persistence adapter, _pathCache, and helper actions (addMessage, updateMessage, renameNode, deleteNode).
• Hook (src/hooks/use-tree-chat.ts): projector between the Conversation Tree (Projection Recipe) and useChat, placeholder management, signature diffing, onFinish commit, branching helpers, and manual message flow.
• Projection (src/lib/tree-projection.ts): builds TopicTree nodes/edges for the Tree Navigator, including virtual edges for recipe adjacency.
• Visuals: ChatHeader, ChatMessages, TreeNavigator, CanvasView, and WorkflowNode.
• API: /api/chat converts Projected Messages (UIMessage[]) ⇒ model messages ⇒ streamText.
• Docs: docs/message-tree.md explains the current data flow and expansion ideas.

• Node.js 20+
• npm (bundled with Node.js)
• AI_GATEWAY_API_KEY (copy env.example to .env.local). To get a Vercel AI gateway API key, sign up at https://vercel.com/ai-gateway and create a new key in the dashboard. Or you can use other compatible providers.

1. Clone the repo:

   git clone https://github.com/TongDucThanhNam/ai-chatbot-tree
   cd ai-chatbot-tree

2. Install dependencies:

   npm install

3. Create .env.local and add your API key:

   cp env.example .env.local

4. Start the dev server:

   npm run dev

• Open the UI in your browser (default port 3000).
• Type a prompt in the chat input; toggle the isolated switch to spawn a new root, or hit “Add Message” to place manual content anywhere.
• Use the Canvas to right-click a node and set the projection root, then drag connections to append or insert nodes into the Projection Recipe.
• Use the Canvas Projection Recipe panel to reorder or remove steps, and the Context Panel to preview or export/import/reset the tree.
• Regenerate the last assistant node to branch from the previous user message, and use the branch selector in the chat to switch between siblings.

Refer to docs/message-tree.md for a deeper dive into the projection logic, hook workflows, unlock strategy, and persistence invariants.

• Tree-driven chat with placeholder nodes
• Context panel with import/export/reset
• Branch selector + regenerate support
• Canvas view with XYFlow
• Partial-streaming assistant node (draft status)
• Database persistence
• Rich multimodal rendering inside ChatMessages

1. Fork the repo.
2. Create a feature branch.
3. Run the formatter/linter (Biome).
4. Submit a PR describing your changes.

Please open issues for bugs or feature requests, especially if they touch the tree synchronization logic.

MIT © AI Chatbot Tree

• Maintainer: Terasumi · LinkedIn · Tong Duc Thanh Nam
• Documentation reference: docs/message-tree.md