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 apps/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"}'

Create a Task with Agent

# Create a task that will be executed by an AI agent
curl -X POST http://localhost:8080/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Analyze codebase",
    "description": "Provide an overview of the project structure",
    "board_id": "{board_id}",
    "column_id": "{column_id}",
    "agent_type": "augment-agent",
    "repository_url": "/path/to/your/project"
  }'

Start Task via Orchestrator

# Start the task - this launches the agent container
curl -X POST http://localhost:8080/api/v1/orchestrator/tasks/{task_id}/start \
  -H "Content-Type: application/json"

Check Agent Status

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

# List all agents
curl http://localhost:8080/api/v1/agents

---

Running the End-to-End Test

The project includes a comprehensive E2E test script:

# Build the agent Docker image first
cd apps/backend/dockerfiles/augment-agent
docker build -t kandev/augment-agent:latest .

# Run the E2E test
cd /path/to/kandev
./scripts/e2e-test.sh

The E2E test:

1. Starts the server with a fresh database
2. Creates a board, column, and task
3. Starts the task via the orchestrator
4. Verifies the agent container starts
5. Checks that ACP session is created
6. Verifies permission requests are handled
7. Waits for agent to complete

---

Configuration

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

---

Development Workflow

Build

cd apps/backend
make build

Run Tests

cd apps/backend
make test

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

Code Formatting

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

View Database

# SQLite CLI
sqlite3 apps/backend/kandev.db

# List tables
.tables

# View boards
SELECT * FROM boards;

# View tasks
SELECT * FROM tasks;

---

Project Structure

kandev/
├── apps/
│   ├── backend/              # Go backend services
│   │   ├── cmd/kandev/       # Main entry point
│   │   │   └── main.go
│   │   ├── internal/
│   │   │   ├── agent/        # Agent management
│   │   │   │   ├── acp/      # ACP session management
│   │   │   │   ├── api/      # Agent HTTP handlers
│   │   │   │   ├── credentials/  # Credential providers
│   │   │   │   ├── 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
│   │   ├── pkg/acp/          # ACP protocol types
│   │   │   └── jsonrpc/      # JSON-RPC 2.0 client
│   │   ├── dockerfiles/      # Agent Dockerfiles
│   │   │   └── augment-agent/
│   │   ├── bin/              # Built binaries (gitignored)
│   │   └── Makefile
│   └── web/                  # Frontend application
├── scripts/
│   └── e2e-test.sh           # End-to-end test script
└── docs/                     # Documentation

---

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 apps/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.