Add quick start guide for developers

docs/QUICK_START.md

@@ -0,0 +1,360 @@
+# 🚀 Quick Start for Developers
+
+Get up and running with Chat Switchboard development in under 10 minutes.
+
+## Prerequisites
+
+- **Go 1.21+** - Backend
+- **Python 3.11+** - Extensions
+- **PostgreSQL 15+** - Database
+- **Redis 7+** - WebSocket scaling
+- **Node.js 18+** (optional) - For frontend tooling
+- **Docker** (optional) - For containerized development
+
+## 🏃 Quick Setup
+
+### 1. Clone and Enter
+```bash
+git clone https://git.gobha.me/xcaliber/chat-switchboard.git
+cd chat-switchboard
+```
+
+### 2. Start Services (Docker)
+```bash
+docker-compose up -d
+```
+
+This starts:
+- PostgreSQL on `localhost:5432`
+- Redis on `localhost:6379`
+
+### 3. Backend Setup
+```bash
+cd server
+go mod download
+cp .env.example .env
+# Edit .env with database credentials
+
+# Run migrations
+go run cmd/migrate/main.go up
+
+# Start server
+go run main.go
+```
+
+Backend runs on `http://localhost:8080`
+
+### 4. Frontend Setup
+```bash
+cd src
+python3 -m http.server 3000
+```
+
+Frontend runs on `http://localhost:3000`
+
+### 5. Open Browser
+```
+http://localhost:3000
+```
+
+Configure API settings to point to `http://localhost:8080`
+
+---
+
+## 🎯 Your First Contribution
+
+### Step 1: Pick an Issue
+Browse [issues](https://git.gobha.me/xcaliber/chat-switchboard/issues) and pick one labeled:
+- 🟡 **LOW** priority
+- `good-first-issue`
+
+### Step 2: Create Branch
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b issue-XX-description
+```
+
+### Step 3: Make Changes
+Edit files, test locally:
+```bash
+# Backend tests
+cd server
+go test ./...
+
+# Frontend lint (if ESLint configured)
+cd src
+npm run lint
+```
+
+### Step 4: Commit and Push
+```bash
+git add .
+git commit -m "[Category] Description (refs #XX)"
+git push origin issue-XX-description
+```
+
+### Step 5: Open PR
+Go to GitHub/Gitea and open PR:
+- **Base:** `develop`
+- **Title:** `[Category] Description (closes #XX)`
+- Fill in PR template
+
+### Step 6: Wait for Review
+Maintainers will review and provide feedback.
+
+---
+
+## 🔧 Development Commands
+
+### Backend
+```bash
+# Run server
+go run main.go
+
+# Run tests
+go test ./...
+
+# Run tests with coverage
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
+
+# Lint
+golangci-lint run
+
+# Build
+go build -o bin/server main.go
+
+# Run migrations
+go run cmd/migrate/main.go up
+go run cmd/migrate/main.go down
+```
+
+### Frontend
+```bash
+# Serve for development
+python3 -m http.server 3000
+
+# Build standalone
+./build.sh
+
+# Lint (if configured)
+npm run lint
+```
+
+### Docker
+```bash
+# Start all services
+docker-compose up -d
+
+# View logs
+docker-compose logs -f
+
+# Restart a service
+docker-compose restart backend
+
+# Stop all
+docker-compose down
+```
+
+---
+
+## 📁 Project Structure Quick Reference
+
+```
+chat-switchboard/
+├── server/               # Go backend
+│   ├── main.go          # Entry point
+│   ├── handlers/        # API handlers
+│   ├── middleware/      # Auth, CORS, etc.
+│   ├── models/          # Database models
+│   ├── extensions/      # Extension manager
+│   ├── websocket/       # WebSocket hub
+│   └── workflows/       # Workflow engine
+├── src/                 # Frontend
+│   ├── index.html
+│   ├── js/
+│   │   ├── app.js       # Main app logic
+│   │   ├── state.js     # State management
+│   │   ├── api.js       # API calls
+│   │   └── ui.js        # UI rendering
+│   └── css/
+├── extensions/          # Backend extensions
+│   ├── _template-python/
+│   ├── chat-engine/
+│   ├── web-search/
+│   └── calculator/
+├── migrations/          # Database migrations
+├── docs/                # Documentation
+│   ├── ARCHITECTURE.md
+│   ├── WORKFLOWS.md
+│   ├── PLUGIN_SPEC.md
+│   └── GETTING_STARTED.md
+├── ROADMAP.md           # Development roadmap
+└── ISSUES.md            # Issue workflow
+```
+
+---
+
+## 🐍 Creating Your First Extension
+
+### 1. Copy Template
+```bash
+cp -r extensions/_template-python extensions/my-extension
+cd extensions/my-extension
+```
+
+### 2. Edit Manifest
+```json
+{
+  "name": "my-extension",
+  "version": "1.0.0",
+  "runtime": "python",
+  "entry": "main.py",
+  "port": 9001,
+  "tools": [
+    {
+      "name": "my_tool",
+      "description": "Does something cool",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "input": {
+            "type": "string",
+            "description": "Input text"
+          }
+        }
+      }
+    }
+  ]
+}
+```
+
+### 3. Implement Tool
+```python
+# main.py
+from fastapi import FastAPI
+import uvicorn
+
+app = FastAPI()
+
+@app.post("/tools/my_tool")
+async def my_tool(input: str):
+    # Your logic here
+    result = input.upper()  # Example
+    return {"result": result}
+
+if __name__ == "__main__":
+    uvicorn.run(app, host="127.0.0.1", port=9001)
+```
+
+### 4. Test
+```bash
+python main.py
+# In another terminal:
+curl -X POST http://localhost:9001/tools/my_tool \
+  -H "Content-Type: application/json" \
+  -d '{"input": "hello"}'
+```
+
+### 5. Register with Backend
+Backend auto-discovers extensions in `/extensions` folder on startup.
+
+---
+
+## 🧪 Running Tests
+
+### Backend Unit Tests
+```bash
+cd server
+go test ./handlers -v
+go test ./extensions -v
+go test ./workflows -v
+```
+
+### Integration Tests
+```bash
+# Start services
+docker-compose up -d
+
+# Run tests
+go test ./tests/integration -v
+```
+
+### E2E Tests
+```bash
+# Install Playwright (one-time)
+npm install -D @playwright/test
+npx playwright install
+
+# Run E2E tests
+npx playwright test
+```
+
+---
+
+## 🔍 Debugging
+
+### Backend Debugging
+```bash
+# Run with delve debugger
+dlv debug main.go
+
+# Or use VS Code launch.json
+# F5 to start debugging
+```
+
+### Frontend Debugging
+- Open browser DevTools (F12)
+- Check Console for errors
+- Use Network tab for API calls
+
+### Extension Debugging
+```bash
+# Run extension standalone
+cd extensions/my-extension
+python main.py
+
+# Check logs
+tail -f logs/extension.log
+```
+
+---
+
+## 📚 Essential Reading
+
+Before you start coding:
+
+1. **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design
+2. **[PLUGIN_SPEC.md](PLUGIN_SPEC.md)** - Extension development
+3. **[ISSUES.md](../ISSUES.md)** - Contribution workflow
+4. **[ROADMAP.md](../ROADMAP.md)** - Project direction
+
+---
+
+## 💬 Getting Help
+
+- **Issues:** [GitHub Issues](https://git.gobha.me/xcaliber/chat-switchboard/issues)
+- **Discussions:** (Coming soon)
+- **Discord:** (Coming soon)
+
+---
+
+## ✨ Pro Tips
+
+1. **Use `develop` branch** - Never commit directly to `main`
+2. **Small PRs** - Easier to review, faster to merge
+3. **Test locally** - Don't rely on CI to catch errors
+4. **Ask questions** - Better to ask than assume
+5. **Read existing code** - Learn patterns from implemented features
+
+---
+
+## 🎉 You're Ready!
+
+Pick an issue and start coding. Welcome to the team! 🚀
+
+**Next Steps:**
+1. Browse [open issues](https://git.gobha.me/xcaliber/chat-switchboard/issues)
+2. Read the [ROADMAP](../ROADMAP.md)
+3. Make your first PR!