kandev/docs/GETTING_STARTED.md

Getting Started with Kandev Backend Development

Note: This guide reflects the current unified binary implementation. The original microservices architecture is documented in IMPLEMENTATION_PLAN.md for future reference.

Prerequisites

Required Software

1. Go 1.21 or higher

   # Check version
   go version
   
   # Install from https://go.dev/dl/
   

2. Docker

   # Check version
   docker --version
   
   # Install from https://docs.docker.com/get-docker/
   

3. Augment CLI Credentials

   # Verify Augment session exists
   cat ~/.augment/session.json
   

4. Git with SSH Keys Configured (for repository access)

   git --version
   
   # Verify SSH keys exist
   ls -la ~/.ssh/
   

---

Quick Start

Step 1: Build the Backend

cd backend

# Build the binary
make build

# This creates ./bin/kandev

Step 2: Run the Server

# Run with default settings (creates kandev.db in current directory)
./bin/kandev

# Or specify a custom database path
KANDEV_DB_PATH=/path/to/kandev.db ./bin/kandev

The server starts on port 8080 by default.

Step 3: Verify It's Running

# Health check
curl http://localhost:8080/health

# Should return: {"status":"ok"}

---

Basic Usage

Create a Board

curl -X POST http://localhost:8080/api/v1/boards \
  -H "Content-Type: application/json" \
  -d '{"name": "My Project", "description": "Project tasks"}'

Create a Column

curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns \
  -H "Content-Type: application/json" \
  -d '{"name": "To Do"}'

Create a Task

curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns/{column_id}/tasks \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix login bug", "description": "Users cannot login"}'

Launch an Agent

# Get your Augment session auth
SESSION_AUTH=$(cat ~/.augment/session.json)

# Launch an agent
curl -X POST http://localhost:8080/api/v1/agents/launch \
  -H "Content-Type: application/json" \
  -d '{
    "task_id": "{task_id}",
    "agent_type": "augment-agent",
    "workspace_path": "/path/to/your/project",
    "env": {
      "AUGMENT_SESSION_AUTH": "'$SESSION_AUTH'",
      "TASK_DESCRIPTION": "Analyze this codebase"
    }
  }'

Check Agent Status

curl http://localhost:8080/api/v1/agents/{agent_id}/status

---

Configuration

Environment Variable	Default	Description
KANDEV_DB_PATH	./kandev.db	SQLite database file path
PORT	8080	HTTP server port

---

Development Workflow

Build

cd backend
make build

Run Tests

cd backend
make test

# Or with verbose output
go test -v ./...

Code Formatting

go fmt ./...
go vet ./...

View Database

# SQLite CLI
sqlite3 backend/kandev.db

# List tables
.tables

# View boards
SELECT * FROM boards;

# View tasks
SELECT * FROM tasks;

---

Project Structure

backend/
├── cmd/kandev/           # Main entry point
│   └── main.go
├── internal/
│   ├── agent/            # Agent management
│   │   ├── api/          # Agent HTTP handlers
│   │   ├── docker/       # Docker client
│   │   ├── lifecycle/    # Container lifecycle
│   │   └── registry/     # Agent type registry
│   ├── task/             # Task management
│   │   ├── api/          # Task HTTP handlers
│   │   ├── models/       # Data models
│   │   ├── repository/   # SQLite/Memory storage
│   │   └── service/      # Business logic
│   ├── orchestrator/     # Orchestration logic
│   ├── events/           # In-memory event bus
│   └── common/           # Shared utilities
│       └── logger/       # Zap logger
├── dockerfiles/          # Agent Dockerfiles
│   └── augment-agent/
├── bin/                  # Built binaries (gitignored)
├── Makefile
└── NEXT_STEPS.md         # Development roadmap

---

Troubleshooting

Docker Permission Issues

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

Port Already in Use

# Find process using port 8080
lsof -i :8080

# Kill it
kill -9 <PID>

Database Issues

# Delete and recreate database
rm backend/kandev.db
./bin/kandev  # Will create fresh database

Agent Container Issues

# List running containers
docker ps -a --filter "label=kandev.managed=true"

# View container logs
docker logs <container_id>

# Clean up old containers
docker rm $(docker ps -a -q --filter "label=kandev.managed=true")

---

Next Steps

See NEXT_STEPS.md for the development roadmap and immediate next steps.