core/docs/GETTING_STARTED.md

🚀 Getting Started with Chat Switchboard

What is Chat Switchboard?

Chat Switchboard is a plugin-first, multi-model AI platform that works in two modes:

• 🏠 Unmanaged Mode: Runs entirely in your browser (like the current version)
• 🌐 Managed Mode: Full backend with collaboration, workflows, and advanced features

Quick Start (Unmanaged Mode)

1. Download & Run

# Clone the repo
git clone https://git.gobha.me/xcaliber/chat-switchboard.git
cd chat-switchboard

# Build standalone version
./build.sh

# Open in browser
xdg-open standalone/index.html
# or serve it
python3 -m http.server 8080 --directory standalone

2. Configure Your API

1. Click ⚙️ Settings
2. Enter your API details:
   • API Endpoint: https://api.openai.com/v1 (or OpenRouter, Venice.ai, etc.)
   • API Key: Your API key
   • Model: Select or type model name
3. Click "Save Settings"

3. Start Chatting

• Type a message and press Enter
• Switch models per-chat using the dropdown
• Export conversations as Markdown/JSON

That's it! No backend needed, all data stays in your browser.

---

Full Installation (Managed Mode)

For teams, collaboration, and advanced features like Workflows and Channels.

Prerequisites

• Docker & Docker Compose
• PostgreSQL 15+
• Go 1.21+ (for development)
• Python 3.9+ (for AI extensions)

1. Clone & Configure

git clone https://git.gobha.me/xcaliber/chat-switchboard.git
cd chat-switchboard

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env

# .env
DATABASE_URL=postgres://user:pass@localhost:5432/chatswitch
JWT_SECRET=your-secret-key-here
PORT=8080
FRONTEND_URL=http://localhost:3000
REDIS_URL=redis://localhost:6379

2. Start Services

# Start everything with Docker Compose
docker-compose up -d

# Services:
# - PostgreSQL (5432)
# - Backend API (8080)
# - Redis (6379)
# - Frontend (3000)

3. Run Migrations

# Apply database schema
docker-compose exec backend ./migrate up

4. Create Admin User

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "email": "admin@example.com",
    "password": "secure-password",
    "role": "admin"
  }'

5. Access Frontend

Open http://localhost:3000

1. Click "Connect to Backend"
2. Enter backend URL: http://localhost:8080
3. Login with your credentials

---

Architecture Overview

┌─────────────────────────────────────┐
│  Frontend (Vanilla JS)              │
│  - Manages UI state                 │
│  - Switches modes (managed/local)   │
└─────────────┬───────────────────────┘
              │
    ┌─────────┴─────────┐
    │                   │
[LocalStorage]    [Backend API]
    │                   │
    │         ┌─────────▼──────────┐
    │         │  Go Core           │
    │         │  - Auth            │
    │         │  - WebSocket       │
    │         │  - Extension Mgr   │
    │         └─────────┬──────────┘
    │                   │
    │         ┌─────────┴──────────┐
    │         │  PostgreSQL        │
    │         │  - Users, chats    │
    │         │  - Channels, notes │
    │         │  - Vector search   │
    │         └────────────────────┘
    │
    └─── Extensions (Python/Go) ───┐
         ├─ Chat Engine             │
         ├─ RAG Engine              │
         ├─ Workflows               │
         └─ Custom Tools            │

Core Features

1. Chat (User → AI)

Available in: Both modes

• Multi-model support (OpenAI, Anthropic, Ollama, etc.)
• Per-conversation model switching
• Streaming responses
• Message history
• Export (Markdown, JSON, Plain Text)

Managed mode additions:

• Auto-routing (smart model selection)
• Cost tracking
• Shared conversations
• Server-side tool calling

2. Channels (User → User + AI)

Available in: Managed mode only

Multi-user chat rooms with AI participants:

#general
  @alice: What do you think about this design?
  @claude: I'd suggest using a darker color scheme...
  @bob: Agreed! Also, @gpt4 can you review the code?
  @gpt4: I see a potential issue in line 42...

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

3. Notes & Knowledge Bases

Available in: Both modes (limited in unmanaged)

• Markdown notes with folders
• Tagging and search
• Linked notes (wiki-style)

Managed mode additions:

• Shared notes
• Knowledge base collections
• RAG (vector search)
• Semantic search with embeddings

4. Workflows 🌟 (UNIQUE FEATURE)

Available in: Managed mode only

Chain multiple AI models and tools into automated pipelines:

[User Query] → [Web Search] → [GPT-4 Summarize] 
                    ↓              ↓
            [Save to KB]    [Claude Verify]
                                   ↓
                          [Generate Report]

Use cases:

• Research assistants
• Code review pipelines
• Content creation factories
• Data processing
• Multi-model consensus

See docs/WORKFLOWS.md for details.

Extension System

Frontend Extensions (Both Modes)

Simple JavaScript plugins that run in the browser:

// extensions/frontend/my-plugin/main.js
window.ChatSwitchboard.registerExtension({
  name: 'my-plugin',
  hooks: {
    onMessageSend: (msg) => {
      console.log('Sending:', msg);
      return msg; // Can modify
    }
  }
});

Backend Extensions (Managed Only)

Full-featured plugins in any language:

# extensions/backend/my-tool/main.py
from fastapi import FastAPI

app = FastAPI()

@app.post("/tools/my_tool")
async def my_tool(input: str):
    result = process(input)
    return {"result": result}

See docs/PLUGIN_SPEC.md for complete guide.

Development

Frontend Development

# Serve source files
python3 -m http.server 8080 --directory src

# Build standalone
./build.sh

Backend Development

# Install Go dependencies
go mod download

# Run backend
go run server/main.go

# Or with air (hot reload)
air

Extension Development

# Create from template
cp -r extensions/_template-python extensions/my-extension

# Edit files
cd extensions/my-extension
nano extension.json
nano main.py

# Test locally
python main.py

Configuration

Frontend Settings

Stored in localStorage (unmanaged) or user profile (managed):

• API endpoints and keys
• Default model
• Stream responses
• System prompt
• Temperature, max tokens, etc.

Backend Configuration

# config.yaml
server:
  port: 8080
  host: 0.0.0.0

database:
  url: ${DATABASE_URL}
  max_connections: 20

redis:
  url: ${REDIS_URL}
  enabled: true

extensions:
  directory: ./extensions/backend
  auto_load: true

security:
  jwt_secret: ${JWT_SECRET}
  jwt_expiry: 24h
  rate_limit: 100/minute

Switching Modes

From Unmanaged → Managed

1. Deploy backend (see Full Installation above)
2. In Settings, enter Backend URL
3. Login/register
4. Your local data will be uploaded on first sync

From Managed → Unmanaged

1. Export your data (Settings → Export)
2. Remove backend URL from settings
3. Continue using locally

Note: Managed-only features (Channels, Workflows) won't work in unmanaged mode.

Common Workflows

Personal Use (Unmanaged)

Open standalone/index.html → Configure API → Chat

Team Collaboration (Managed)

Deploy backend → Create team channels → @mention AI models

Development (Contributing)

Fork repo → Create extension → Test locally → Submit PR

Self-Hosted (Privacy)

Deploy on your server → Configure domains → Invite team

Troubleshooting

Frontend Issues

"No settings found"

• Click Settings ⚙️ and configure API endpoint + key

"API request failed"

• Check API endpoint URL (trailing slash?)
• Verify API key is correct
• Check browser console for errors

"LocalStorage full"

• Export old chats
• Delete unused chats
• Clear browser data

Backend Issues

"Connection refused"

• Is backend running? docker-compose ps
• Check firewall rules
• Verify port 8080 is open

"Database migration failed"

• Check PostgreSQL is running
• Verify DATABASE_URL is correct
• Run migrations manually: ./migrate up

"Extension not loading"

• Check extension.json is valid
• Verify runtime is installed (python3, go, node)
• Check logs: docker-compose logs backend

WebSocket Issues

"Real-time updates not working"

• Check WebSocket connection in browser console
• Verify Redis is running (for multi-instance setups)
• Check nginx WebSocket proxy config

Next Steps

1. Explore Features: Try Chat, Notes, and (if managed) Channels
2. Read Docs:
   • docs/ARCHITECTURE.md - System design
   • docs/WORKFLOWS.md - Workflow system
   • docs/PLUGIN_SPEC.md - Extension development
3. Build Extensions: Use templates in extensions/
4. Join Community: Discord, GitHub Discussions
5. Contribute: Submit PRs, report bugs, suggest features

Resources

• GitHub: https://git.gobha.me/xcaliber/chat-switchboard
• Documentation: /docs directory
• Examples: /examples directory
• Extensions: /extensions directory

---

FAQ

Q: Is my data private?
A: In unmanaged mode, everything stays in your browser. In managed mode, you control the backend.

Q: Can I use my own models?
A: Yes! Configure any OpenAI-compatible API (Ollama, LM Studio, etc.)

Q: How do I migrate from ChatGPT/Claude?
A: Export your conversations, then import via our import tool (coming soon).

Q: Can I run this offline?
A: Unmanaged mode works offline if you pre-load the page. For LLM calls, you need internet or local models (Ollama).

Q: How much does it cost?
A: Chat Switchboard is free and open-source. You pay for API usage (OpenAI, etc.) or use free models (Ollama).

Q: Can I sell extensions?
A: Yes! The marketplace (coming soon) will support paid extensions.

---

Ready to switch? Start building! 🚀