diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md new file mode 100644 index 0000000..0e8f8c2 --- /dev/null +++ b/docs/ARCHITECTURE.md @@ -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.