Chat System
Multi-interface chat architecture — public widget, admin chat, Argonaut agent, and user workbench with streaming, model selection, and conversation persistence
Chat System
Arcturus-Prime has four chat interfaces sharing common streaming and persistence patterns, each targeting different users and capabilities.
Chat Interfaces
ChatWidget (Public)
| Property | Value |
|---|---|
| File | src/components/chat/ChatWidget.astro |
| Endpoint | POST /api/public/chat |
| Model | google/gemini-2.0-flash-001 (free via OpenRouter) |
| Persistence | sessionStorage — last 20 messages, cleared on tab close |
| Rate limit | 15 requests/hour per IP |
Floating panel in the bottom-right corner on all public pages. Features a welcome state with starter chips, RAG-powered answers using the top 5 matching chunks (min score 0.3), and live infrastructure data injection. Max 8 messages of history sent per request, max 1024 tokens per response.
Admin Chat
| Property | Value |
|---|---|
| File | src/pages/admin/chat.astro |
| Endpoint | GET/POST /api/admin/chat |
| Models | Full catalog — Ollama, Anthropic, OpenAI, Google, Groq, NVIDIA NIM, OpenRouter |
| Persistence | localStorage — up to 50 conversations |
Full-featured interface with sidebar conversation list, model selector with categories (pricing tier, route type, context window), custom system prompt editor, and conversation search. Auto-titles conversations from the first message.
Sensitivity routing: Messages containing private topics (health, PII, legal, relationships, credentials) are automatically routed to groq/llama-3.3-70b-versatile for privacy-safe processing.
Argonaut Chat
| Property | Value |
|---|---|
| File | src/pages/admin/argonaut/chat.astro |
| Endpoint | POST /api/argonaut/chat |
| Backends | Argonaut (default) + OpenClaw (toggle) |
| Persistence | localStorage — up to 50 conversations |
Advanced admin interface with two switchable backends:
- Argonaut: Full agent with RAG, tool calling, and user profiles. Three-tier fallback: daemon proxy → local agent → cloud-only.
- OpenClaw: Orchestration agent for automation tasks.
Extras: RAG mode toggle (Full: 85K chunks unsanitized vs Safe: 46K chunks blog-only), voice conversation mode with Whisper STT + ElevenLabs TTS, agentic tool indicators, and sources panel.
Registered tools (when daemon is available): Brave/DuckDuckGo search, Perplexity, file read/write/list, allowlisted shell commands, Resend email, Twilio voice/SMS, Google Calendar.
User Workbench Chat
| Property | Value |
|---|---|
| File | src/pages/api/user/chat.ts |
| Endpoint | POST /api/user/chat |
| Models | Free models only |
| Persistence | None (API-only) |
Portal user access with role-based permissions (portal:workbench). Restricted to the free model list. Supports custom system prompts.
Provider Routing
The admin chat endpoint resolves providers by model prefix:
| Prefix | Provider | Requirement |
|---|---|---|
ollama/ | Ollama (local) | Ollama running on network |
anthropic/ | Anthropic Direct | ANTHROPIC_API_KEY set |
openai/ | OpenAI Direct | OPENAI_API_KEY set |
google/ | Google Gemini Direct | GOOGLE_API_KEY set |
groq/ | Groq | GROQ_API_KEY set |
nvidia-nim/ | NVIDIA NIM | NVIDIA_NIM_API_KEY set |
| Everything else | OpenRouter | OPENROUTER_API_KEY set |
Unified Chat Router
POST /api/admin/unified-chat classifies user intent with a two-tier system (regex patterns first, Groq LLM fallback) and routes to the appropriate backend:
| Intent | Backend | Use Case |
|---|---|---|
brain | RAG + knowledge lookup | Questions about the site or infrastructure |
forge | Tmux session dispatch | Coding tasks |
terminal | forge-shell session | Shell commands |
openclaw | Orchestration agent | Agentic tool use |
content | Content-specific prompts | Blog/journal writing |
private | Groq (privacy-safe) | Sensitive topics |
The mode parameter can override intent detection: code→forge, terminal→terminal, agent→openclaw.
Streaming Format
All endpoints use Server-Sent Events (SSE):
data: {"content": "text chunk"}
data: {"content": "more text"}
data: {"sources": [...]}
data: {"suggestions": [...]}
data: [DONE]Client-side pattern:
- Fetch with
AbortControllerfor cancellation response.body.getReader()+TextDecoderfor streaming- Buffer lines, parse JSON from
data:prefix - Handle special events:
[DONE], error, content, sources - Update DOM incrementally with
markedfor markdown rendering - Sanitize HTML output (strip scripts, iframes, event handlers)
Conversation Persistence
| Interface | Storage | Key | Limit |
|---|---|---|---|
| ChatWidget | sessionStorage | Arcturus-Prime-chat-history | 20 messages |
| Admin Chat | localStorage | Arcturus-Prime-chat-conversations | 50 conversations |
| Argonaut | localStorage | argonaut-conversations | 50 conversations |
Each stored conversation includes: ID, title (auto-generated from first message), messages array, selected model, optional system prompt, and timestamps.
Key Files
| File | Purpose |
|---|---|
src/components/chat/ChatWidget.astro | Public floating widget |
src/pages/admin/chat.astro | Admin chat interface |
src/pages/admin/argonaut/chat.astro | Argonaut advanced interface |
src/pages/api/public/chat.ts | Public endpoint (free model + RAG) |
src/pages/api/admin/chat.ts | Admin endpoint (multi-provider) |
src/pages/api/admin/personal-chat.ts | Private vault endpoint (Groq-only) |
src/pages/api/admin/unified-chat.ts | Intent-routing endpoint |
src/pages/api/argonaut/chat.ts | Argonaut daemon proxy |
src/pages/api/user/chat.ts | Portal user endpoint |