core/docs/QUICK_START.md

🚀 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

git clone https://git.gobha.me/xcaliber/chat-switchboard.git
cd chat-switchboard

2. Start Services (Docker)

docker-compose up -d

This starts:

• PostgreSQL on localhost:5432
• Redis on localhost:6379

3. Backend Setup

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

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 and pick one labeled:

• 🟡 LOW priority
• good-first-issue

Step 2: Create Branch

git checkout develop
git pull origin develop
git checkout -b issue-XX-description

Step 3: Make Changes

Edit files, test locally:

# Backend tests
cd server
go test ./...

# Frontend lint (if ESLint configured)
cd src
npm run lint

Step 4: Commit and Push

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

# 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

# Serve for development
python3 -m http.server 3000

# Build standalone
./build.sh

# Lint (if configured)
npm run lint

Docker

# 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

cp -r extensions/_template-python extensions/my-extension
cd extensions/my-extension

2. Edit Manifest

{
  "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

# 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

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

cd server
go test ./handlers -v
go test ./extensions -v
go test ./workflows -v

Integration Tests

# Start services
docker-compose up -d

# Run tests
go test ./tests/integration -v

E2E Tests

# Install Playwright (one-time)
npm install -D @playwright/test
npx playwright install

# Run E2E tests
npx playwright test

---

🔍 Debugging

Backend Debugging

# 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

# 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 - System design
2. PLUGIN_SPEC.md - Extension development
3. ISSUES.md - Contribution workflow
4. ROADMAP.md - Project direction

---

💬 Getting Help

• Issues: GitHub 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
2. Read the ROADMAP
3. Make your first PR!