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

```bash
# 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

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

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env
```

```bash
# .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

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

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

### 3. Run Migrations

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

### 4. Create Admin User

```bash
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:

```javascript
// 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:

```python
# 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

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

# Build standalone
./build.sh
```

### Backend Development

```bash
# Install Go dependencies
go mod download

# Run backend
go run server/main.go

# Or with air (hot reload)
air
```

### Extension Development

```bash
# 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

```yaml
# 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! 🚀**