Add comprehensive architecture documentation
This commit is contained in:
482
docs/ARCHITECTURE.md
Normal file
482
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,482 @@
|
|||||||
|
# 🏗️ 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