From 746e647fff9a65604d168aa5b160f7ec6f7fc873 Mon Sep 17 00:00:00 2001 From: xcaliber Date: Tue, 3 Feb 2026 23:27:04 +0000 Subject: [PATCH] Add quick start guide for developers --- docs/QUICK_START.md | 360 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 360 insertions(+) create mode 100644 docs/QUICK_START.md diff --git a/docs/QUICK_START.md b/docs/QUICK_START.md new file mode 100644 index 0000000..3143548 --- /dev/null +++ b/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!