npx clawhub@latest install ai-chat-application

┌─────────────────────────────────────────────────────────────┐
│                    Client (React)                            │
├─────────────────────────────────────────────────────────────┤
│  useChat Hook                    │  Data Stream Handler     │
│  - messages, input, submit       │  - Custom data events    │
│  - isLoading, error              │  - Message annotations   │
│  See: vercel-ai-chat-integration │  See: vercel-ai-data-streaming
├─────────────────────────────────────────────────────────────┤
│                    API Route (Next.js)                       │
│  - createDataStreamResponse, streamText, message persistence│
│  See: ai-streaming-routes                                    │
├─────────────────────────────────────────────────────────────┤
│                    Tool System                               │
│  - Toolkit composition, singleton factories, error handling │
│  See: ai-tool-composition, vercel-ai-tool-architecture      │
├─────────────────────────────────────────────────────────────┤
│                    Message Handling                          │
│  - DB ↔ UI conversion, sanitization, annotations           │
│  See: ai-message-handling                                    │
└─────────────────────────────────────────────────────────────┘

// app/api/chat/route.ts
export async function POST(request: Request) {
  const { id, messages, modelId } = await request.json();
  
  // Auth, validation, save user message...
  
  return createDataStreamResponse({
    execute: (dataStream) => {
      const result = streamText({
        model: customModel(model),
        system: systemPrompt,
        messages: convertToCoreMessages(messages),
        tools: makeToolkitByName(model.toolkit, params),
        onFinish: async ({ response }) => {
          // Save assistant messages
        },
      });
      result.mergeIntoDataStream(dataStream);
    },
  });
}

// components/chat.tsx
export function Chat({ id, initialMessages }: ChatProps) {
  const { messages, input, handleSubmit, isLoading } = useChat({
    id,
    initialMessages,
    experimental_throttle: 100,
    onError: (error) => toast.error(parseError(error)),
  });

  return (
    <div>
      <Messages messages={messages} isLoading={isLoading} />
      <ChatInput value={input} onSubmit={handleSubmit} />
    </div>
  );
}

const [containerRef, endRef] = useScrollToBottom();

{isLoading && lastMessage?.role === 'user' && <ThinkingMessage />}

// lib/tools/allTools.ts
export function allToolsToolkit(params: ToolkitParams) {
  return {
    ...makeWeb3Tools(params),
    ...makeSearchTools(params),
    getTime: tool({ /* inline tool */ }),
  };
}

// Convert DB → UI on page load
const uiMessages = convertToUIMessages(dbMessages);

// Sanitize before save
const cleanMessages = sanitizeResponseMessages(response.messages);