Changeset 0.5.0 (#35)
This commit is contained in:
@@ -1,482 +0,0 @@
|
||||
# 🏗️ 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.
|
||||
Reference in New Issue
Block a user