Add quick start guide for developers
This commit is contained in:
360
docs/QUICK_START.md
Normal file
360
docs/QUICK_START.md
Normal file
@@ -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!
|
||||
Reference in New Issue
Block a user