core/docs/ARCHITECTURE.md

🏗️ Chat Switchboard Architecture

Overview

Chat Switchboard is a plugin-first, multi-model AI platform with dual-mode operation:

┌─────────────────────────────────────────────────────┐
│  FRONTEND (Vanilla JS)                              │
│  ├─ Managed Mode: Full backend features + auth     │
│  └─ Unmanaged Mode: LocalStorage only, offline     │
└─────────────────────┬───────────────────────────────┘
                      │
         ┌────────────┴────────────┐
         │                         │
    [HTTP/WS]              [LocalStorage Only]
         │
┌────────▼─────────────────────────────────────────────┐
│  BACKEND (Go + PostgreSQL)                           │
│  ├─ Core API (minimal, orchestration only)          │
│  ├─ Extension Manager                               │
│  └─ WebSocket Server (real-time features)           │
└────────┬─────────────────────────────────────────────┘
         │
         ├─ PostgreSQL (state, users, data)
         │
         └─ Extensions (modular features)
            ├─ Chat Engine (Python)
            ├─ Channels (Go)
            ├─ RAG Engine (Python)
            ├─ Workflow Builder (Go/Python)
            └─ Custom Extensions...

Operating Modes

🏠 Unmanaged Mode (LocalStorage)

Use Case: Personal use, offline, privacy-focused

• ✅ No backend required
• ✅ No account/auth needed
• ✅ Works offline
• ✅ All data in browser LocalStorage
• ✅ Export/import for backup
• ❌ No multi-device sync
• ❌ No collaboration features
• ❌ No server-side extensions

Detection:

// src/js/state.js
State.mode = State.settings.backendUrl ? 'managed' : 'unmanaged';

🌐 Managed Mode (Full Backend)

Use Case: Teams, collaboration, advanced features

• ✅ Multi-user with authentication
• ✅ Real-time collaboration (WebSockets)
• ✅ Server-side extensions (Python, Go)
• ✅ Shared knowledge bases
• ✅ Workflow orchestration
• ✅ Usage analytics
• ❌ Requires backend deployment

Switching:

// User configures backend URL in settings
State.settings.backendUrl = 'https://api.chatswitch.example.com';
State.settings.backendToken = 'jwt_token_here';

Core Features (All Modes)

1. Chat (User → LLM)

• Per-conversation model selection
• Streaming responses
• Message history
• Export (Markdown, JSON, Plain Text)

Managed Mode Additions:

• Multi-model auto-routing
• Cost tracking
• Shared chats
• Server-side tool calling

2. Channels (User → User + AI)

Managed Mode Only

• Public/private channels
• @mentions for users and AI models
• Threaded conversations
• Reactions
• Real-time updates (WebSocket)

Example:

@alice What do you think about this design?
@claude-3.5 Can you review this code?

3. Notes & Knowledge Bases

Both Modes:

• Personal notes
• Markdown editing
• Tagging and folders

Managed Mode Additions:

• Shared notes
• Knowledge base collections
• RAG (Retrieval Augmented Generation)
• Vector embeddings (pgvector)
• Semantic search

4. Workflows (🌟 UNIQUE FEATURE)

Managed Mode Only

Visual workflow builder for multi-step AI operations:

[User Input] → [Model A: Research] → [Model B: Summarize] → [Tool: Save to KB] → [Output]

Use Cases:

• Research pipelines (search → summarize → extract → store)
• Multi-model consensus (run prompt through 3 models, compare)
• Data processing (extract → transform → analyze → report)
• Content creation (outline → draft → edit → format)

Why It's Unique:

• Competitors have single-shot chat
• This enables AI composition - chain multiple models and tools
• Shareable templates (marketplace potential)
• Visual no-code builder

Extension Architecture

Extension Types

1. Frontend Extensions (UI Only)

Both Modes - Pure JavaScript, no backend needed

// extensions/token-counter/main.js
window.ChatSwitchboard.registerExtension({
  name: 'token-counter',
  hooks: {
    onMessageSend: (message) => {
      const tokens = estimateTokens(message);
      showToast(`~${tokens} tokens`);
    }
  }
});

2. Backend Extensions (Full Power)

Managed Mode Only - Python, Go, Node.js

extensions/
├── web-search/
│   ├── extension.json      # Manifest
│   ├── main.py            # Python service
│   └── requirements.txt

Communication: HTTP/gRPC between Go core and extension processes

Extension Protocol

// extension.json
{
  "name": "web-search",
  "version": "1.0.0",
  "runtime": "python",
  "entry": "main.py",
  "port": 9001,
  "capabilities": ["tool"],
  "tools": [
    {
      "name": "search_web",
      "description": "Search the web for information",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        },
        "required": ["query"]
      }
    }
  ]
}

Technology Stack

Frontend

• Vanilla JavaScript - No framework bloat
• CSS3 - Custom dark theme
• LocalStorage - Offline-first
• WebSocket - Real-time (managed mode)

Backend (Managed Mode)

• Go - Core API, routing, orchestration
• PostgreSQL - Primary data store
• pgvector - Vector embeddings for RAG
• Redis - Session cache, WebSocket pub/sub (optional)
• Python - AI/ML extensions (LangChain, embeddings)

Infrastructure

• Docker - Easy deployment
• nginx - Reverse proxy
• Let's Encrypt - TLS certificates

Data Flow

Unmanaged Mode

User Input → Frontend State → LocalStorage
                   ↓
              API Provider (OpenAI, etc)
                   ↓
              Frontend State → LocalStorage

Managed Mode

User Input → Frontend → WebSocket → Backend
                                       ↓
                                  PostgreSQL
                                       ↓
                               Extension Manager
                                 ↓         ↓
                         [Chat Engine] [RAG Engine]
                                 ↓         ↓
                            Model Router → API Provider
                                       ↓
                              WebSocket → Frontend

WebSocket Protocol

Events (Managed Mode)

// Client → Server
{
  type: 'chat.send',
  chatId: 'uuid',
  message: 'Hello',
  model: 'gpt-4'
}

// Server → Client (streaming)
{
  type: 'chat.stream',
  chatId: 'uuid',
  delta: 'Hello! ',
  done: false
}

// Channel messages
{
  type: 'channel.message',
  channelId: 'uuid',
  content: '@claude What do you think?',
  mentions: {users: [], models: ['claude-3.5']}
}

// AI response in channel
{
  type: 'channel.ai_response',
  channelId: 'uuid',
  model: 'claude-3.5',
  content: 'I think...',
  inReplyTo: 'message_uuid'
}

Connection Management

// server/websocket/hub.go
type Hub struct {
    clients    map[*Client]bool
    broadcast  chan Message
    register   chan *Client
    unregister chan *Client
}

Security

Unmanaged Mode

• All sensitive data (API keys) in browser localStorage
• User responsible for backups
• No server-side attack surface

Managed Mode

• Authentication: JWT tokens
• Authorization: RBAC (roles: user, admin, moderator)
• API Keys: Encrypted at rest (pgcrypto)
• Rate Limiting: Per-user, per-endpoint
• CORS: Strict origin checking
• Webhooks: HMAC signature verification
• Extensions: Sandboxed execution

Deployment

Unmanaged Mode

# Build standalone
./build.sh

# Serve
python3 -m http.server 8080 --directory standalone
# or upload index.html to any static host

Managed Mode

# Docker Compose
docker-compose up -d

# Services:
# - postgres:5432
# - backend:8080
# - redis:6379 (optional)
# - nginx:443

Scaling

Horizontal Scaling (Managed)

         ┌─ Load Balancer (nginx)
         ├─ Backend Instance 1 ─┐
         ├─ Backend Instance 2 ─┼─ PostgreSQL (primary)
         └─ Backend Instance 3 ─┘
                  │
                Redis (WebSocket sync)

Extension Scaling

• Extensions are separate processes
• Can run on different machines
• Service discovery via extension registry

Plugin Ecosystem (🌟 DIFFERENTIATOR)

Core Principle

Everything is a plugin (except minimal routing core)

Feature	Implementation
Chat	extensions/chat-engine/
Channels	extensions/channels/
Notes	extensions/notes/
Knowledge Bases	extensions/rag-engine/
Workflows	extensions/workflows/

Why This Matters

1. Proof of Extensibility - If core features work as plugins, any feature can
2. Community Innovation - Users build missing features
3. Customization - Disable unwanted features
4. Marketplace Potential - Monetize premium plugins

Plugin Types

Official Plugins (Bundled)

• Chat Engine
• Channels
• RAG/Knowledge
• Web Search
• Code Execution

Community Plugins (Marketplace)

• Specialized tools
• Industry-specific workflows
• Integration plugins (Slack, Discord, etc)
• Custom AI models

Enterprise Plugins (Premium)

• SSO/SAML
• Advanced analytics
• Compliance logging
• Custom model hosting

Unique Features Summary

1. Workflow Builder (⭐⭐⭐)

What: Visual DAG builder for multi-step AI operations Why Unique: No competitor has AI orchestration at this level Use Case: Research assistant = [Search] → [GPT-4 summarize] → [Claude verify] → [Save to KB]

2. Dual-Mode Operation (⭐⭐)

What: Works offline (LocalStorage) or managed (full backend) Why Unique: Privacy-first with optional collaboration Use Case: Personal use → upgrade to team without migration

3. Plugin-First Architecture (⭐⭐⭐)

What: Core features ARE plugins (dogfooding) Why Unique: Proves extensibility, enables marketplace Use Case: Build custom enterprise workflows as plugins

4. Multi-Model Auto-Routing (⭐⭐)

What: Automatically route to best/cheapest model Why Unique: Most tools lock you to one provider Use Case: Simple questions → GPT-3.5 (), complex → GPT-4 ($$)

5. Channels with AI Participants (⭐)

What: Slack-like channels where you @mention AI models Why Unique: Collaborative AI + human conversations Use Case: Team discusses design, @claude gives input, @gpt4 suggests alternatives

Comparison Matrix

Feature	Chat Switchboard	Open WebUI	ChatGPT	Claude Desktop
Multi-Model	✅	✅	❌	❌
Plugin System	✅⭐	Limited	❌	❌
Offline Mode	✅	❌	❌	Limited
Workflows	✅⭐	❌	❌	❌
Channels	✅	✅	❌	❌
RAG/Knowledge	✅	✅	❌	Limited
Self-Hosted	✅	✅	❌	❌
Open Source	✅	✅	❌	❌

Competitive Advantage: Workflows + Plugin Architecture + Dual-Mode

Roadmap

Phase 1: Foundation (Weeks 1-4)

• ✅ Frontend core
• ⬜ Backend API skeleton
• ⬜ PostgreSQL integration
• ⬜ WebSocket server
• ⬜ Extension manager

Phase 2: Core Features (Weeks 5-8)

• ⬜ Chat engine (as plugin)
• ⬜ Channels (as plugin)
• ⬜ Notes (as plugin)
• ⬜ Basic auth/users

Phase 3: Unique Features (Weeks 9-12)

• ⬜ RAG/Knowledge bases
• ⬜ Workflow builder (visual editor)
• ⬜ Model auto-routing
• ⬜ Extension marketplace basics

Phase 4: Polish (Weeks 13-16)

• ⬜ Desktop app (Tauri)
• ⬜ Mobile-responsive
• ⬜ Documentation
• ⬜ Example plugins (10+)
• ⬜ Launch 🚀

Contributing

Since core features are plugins, contributors can:

1. Build new extensions (any language)
2. Improve existing plugins (PRs welcome)
3. Share workflows (template marketplace)
4. Report bugs, suggest features

Plugin Development:

# Use template
cp -r extensions/_template-python extensions/my-plugin
cd extensions/my-plugin
# Edit extension.json, main.py
python main.py  # Runs on port from manifest

License

MIT - Build whatever you want, including commercial

---

Questions? See /docs for detailed guides or join discussions.