# 🏗️ 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:**
```javascript
// 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:**
```javascript
// 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

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

```json
// 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)

```javascript
// 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
```go
// 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
```bash
# Build standalone
./build.sh

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

### Managed Mode
```bash
# 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:**
```bash
# 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.