# 🚀 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!