Initial commit: Kandev with SQLite persistence and agent integration
Features: - Unified Go binary running Task Service, Agent Manager, and Orchestrator - SQLite persistence for boards, columns, and tasks - Docker-based agent execution with ACP message streaming - Augment Agent integration with session resumption support - RESTful API for all operations (port 8080) - In-memory event bus for service communication Architecture: - cmd/kandev: Single entry point for all services - internal/task: Task, board, and column management - internal/agent: Docker container lifecycle and ACP streaming - internal/orchestrator: Agent coordination and monitoring - internal/events: In-memory pub/sub event bus Documentation: - README.md: Project overview and quick start - docs/ARCHITECTURE.md: System architecture (current + planned) - docs/GETTING_STARTED.md: Development setup guide - docs/IMPLEMENTATION_PLAN.md: Original microservices plan - backend/NEXT_STEPS.md: Development roadmap
This commit is contained in:
jcfs
@@ -0,0 +1,645 @@
|
||||
# Kandev System Architecture
|
||||
|
||||
> **Note:** This document describes both the current implementation and the planned architecture.
|
||||
> Sections marked with ✅ are implemented, while sections marked with 📋 are planned for future development.
|
||||
|
||||
## Current Implementation Status
|
||||
|
||||
The current implementation uses a **unified binary architecture** instead of separate microservices:
|
||||
|
||||
- ✅ **Single Go binary** (`cmd/kandev/main.go`) running all services
|
||||
- ✅ **SQLite database** for persistence (instead of PostgreSQL)
|
||||
- ✅ **In-memory event bus** (instead of NATS)
|
||||
- ✅ **Docker-based agent execution** with ACP streaming
|
||||
- ✅ **Session resumption** for multi-turn agent conversations
|
||||
- 📋 WebSocket support for real-time frontend streaming
|
||||
- 📋 JWT authentication
|
||||
- 📋 NATS event bus for distributed deployment
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Kandev uses an event-driven architecture with **Agent Communication Protocol (ACP)** for real-time streaming between AI agents and the backend. The system is designed for deployment on client machines (local workstations) with future cloud scalability.
|
||||
|
||||
## Current Architecture (Unified Binary)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Kandev Binary │
|
||||
│ (Port 8080) │
|
||||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
|
||||
│ │ Task │ │ Agent │ │ Orchestrator │ │
|
||||
│ │ Service │ │ Manager │ │ Service │ │
|
||||
│ └──────┬──────┘ └──────┬──────┘ └────────┬────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └───────────────┴──────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────┴──────────┐ │
|
||||
│ │ In-Memory Event Bus │ │
|
||||
│ └──────────┬──────────┘ │
|
||||
│ │ │
|
||||
│ ┌──────────┴──────────┐ │
|
||||
│ │ SQLite Database │ │
|
||||
│ │ (kandev.db) │ │
|
||||
│ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
│
|
||||
Docker Engine (Agent Containers)
|
||||
│
|
||||
┌───────────┴───────────┐
|
||||
│ Augment Agent │
|
||||
│ Container │
|
||||
│ (ACP via stdout) │
|
||||
└───────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Planned Architecture (Microservices) 📋
|
||||
|
||||
### 1. API Gateway
|
||||
**Port:** 8080
|
||||
**Purpose:** Single entry point for all client requests with WebSocket support
|
||||
|
||||
**Responsibilities:**
|
||||
- Route requests to appropriate services
|
||||
- JWT authentication and authorization
|
||||
- **WebSocket connection management for real-time ACP streaming**
|
||||
- **Proxy ACP streams from Orchestrator to frontend**
|
||||
- Rate limiting and request validation
|
||||
- CORS handling
|
||||
- API versioning
|
||||
|
||||
**Dependencies:**
|
||||
- Task Service (internal)
|
||||
- Agent Manager (internal)
|
||||
- Orchestrator (internal - WebSocket proxy)
|
||||
- PostgreSQL (for user auth)
|
||||
|
||||
---
|
||||
|
||||
### 2. Task Service
|
||||
**Port:** 8081
|
||||
**Purpose:** Manage kanban tasks and boards
|
||||
|
||||
**Responsibilities:**
|
||||
- CRUD operations for tasks and boards
|
||||
- Task state transitions
|
||||
- Task priority and scheduling metadata
|
||||
- Publish task events to NATS
|
||||
|
||||
**Dependencies:**
|
||||
- PostgreSQL (tasks, boards, task_events tables)
|
||||
- NATS (event publishing)
|
||||
|
||||
**Events Published:**
|
||||
- `task.created`
|
||||
- `task.updated`
|
||||
- `task.state_changed`
|
||||
- `task.deleted`
|
||||
|
||||
---
|
||||
|
||||
### 3. Orchestrator Service
|
||||
**Port:** 8082
|
||||
**Purpose:** Automated task orchestration, agent coordination, and real-time ACP streaming
|
||||
|
||||
**Responsibilities:**
|
||||
- Subscribe to task state change events
|
||||
- Determine when to launch AI agents
|
||||
- Manage task queue with priority
|
||||
- Coordinate with Agent Manager for container launches
|
||||
- **Aggregate ACP messages from NATS event bus**
|
||||
- **Provide WebSocket endpoints for real-time ACP streaming to frontend**
|
||||
- **Expose comprehensive REST API for task execution control**
|
||||
- Implement retry logic for failed tasks
|
||||
- Monitor agent execution
|
||||
|
||||
**Dependencies:**
|
||||
- NATS (event subscription + ACP message aggregation)
|
||||
- Agent Manager (gRPC calls)
|
||||
- PostgreSQL (read task details, store ACP messages)
|
||||
|
||||
**Events Subscribed:**
|
||||
- `task.state_changed`
|
||||
- `agent.completed`
|
||||
- `agent.failed`
|
||||
- **`acp.message.*` - All ACP messages from agents**
|
||||
|
||||
**Key Endpoints:**
|
||||
- `WS /api/v1/orchestrator/tasks/{taskId}/stream` - Real-time ACP streaming
|
||||
- `POST /api/v1/orchestrator/tasks/{taskId}/start` - Start agent execution
|
||||
- `POST /api/v1/orchestrator/tasks/{taskId}/stop` - Stop agent execution
|
||||
- `GET /api/v1/orchestrator/tasks/{taskId}/status` - Get execution status
|
||||
|
||||
**Orchestration Logic:**
|
||||
```
|
||||
When task.state_changed to "TODO" with agent_type set:
|
||||
1. Add task to priority queue
|
||||
2. Check available resources
|
||||
3. Request Agent Manager to launch container
|
||||
4. Update task state to "IN_PROGRESS"
|
||||
5. Subscribe to ACP messages for this task
|
||||
6. Stream ACP messages to connected WebSocket clients
|
||||
|
||||
When acp.message received:
|
||||
1. Store message in database
|
||||
2. Broadcast to WebSocket clients subscribed to this task
|
||||
3. Update task progress/status
|
||||
|
||||
When agent.completed:
|
||||
1. Update task state to "COMPLETED"
|
||||
2. Record completion time
|
||||
3. Send final ACP result message
|
||||
4. Clean up resources
|
||||
|
||||
When agent.failed:
|
||||
1. Check retry count
|
||||
2. If retries available: re-queue task
|
||||
3. Else: Update task state to "FAILED"
|
||||
4. Send ACP error message
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Agent Manager Service
|
||||
**Port:** 8083
|
||||
**Purpose:** Docker container lifecycle management with ACP streaming and credential mounting
|
||||
|
||||
**Responsibilities:**
|
||||
- Launch Docker containers for AI agents
|
||||
- **Mount host credentials (SSH keys, Git config) into containers**
|
||||
- **Capture and parse ACP messages from container stdout**
|
||||
- **Publish ACP messages to NATS event bus**
|
||||
- Monitor container health and status
|
||||
- Stream and store container logs
|
||||
- Manage agent type registry
|
||||
- Resource allocation and limits
|
||||
- Container cleanup
|
||||
|
||||
**Dependencies:**
|
||||
- Docker Engine (container operations)
|
||||
- PostgreSQL (agent_instances, agent_logs, agent_types tables)
|
||||
- NATS (event publishing + ACP message publishing)
|
||||
- **Host filesystem (for credential mounting)**
|
||||
|
||||
**Events Published:**
|
||||
- `agent.started`
|
||||
- `agent.running`
|
||||
- `agent.completed`
|
||||
- `agent.failed`
|
||||
- `agent.stopped`
|
||||
- **`acp.message.{task_id}` - Real-time ACP messages from agents**
|
||||
|
||||
**Container Launch Flow with ACP:**
|
||||
```
|
||||
1. Receive launch request (task_id, agent_type)
|
||||
2. Lookup agent_type configuration
|
||||
3. Create agent_instance record (status: PENDING)
|
||||
4. Pull Docker image if needed
|
||||
5. **Prepare host credential mounts (SSH, Git config)**
|
||||
6. **Checkout repository on host (if repository_url provided)**
|
||||
7. Prepare volume mounts (workspace, credentials)
|
||||
8. Create container with resource limits and mounts
|
||||
9. Start container
|
||||
10. Update agent_instance (status: RUNNING, container_id)
|
||||
11. **Attach to container stdout for ACP message capture**
|
||||
12. **Parse ACP messages from stdout**
|
||||
13. **Publish ACP messages to NATS (acp.message.{task_id})**
|
||||
14. Store ACP messages in database
|
||||
15. Publish agent.started event
|
||||
16. Monitor container until completion
|
||||
17. Collect exit code and final logs
|
||||
18. Update agent_instance (status: COMPLETED/FAILED)
|
||||
19. Publish completion event
|
||||
20. Cleanup container and workspace
|
||||
```
|
||||
|
||||
**Credential Mounting Strategy:**
|
||||
```
|
||||
Mounts (Read-Only):
|
||||
- ~/.ssh → /root/.ssh (SSH keys)
|
||||
- ~/.gitconfig → /root/.gitconfig (Git configuration)
|
||||
- ~/.git-credentials → /root/.git-credentials (HTTPS credentials)
|
||||
|
||||
Environment Variables:
|
||||
- GITHUB_TOKEN (from host environment)
|
||||
- GITLAB_TOKEN (from host environment)
|
||||
- GEMINI_API_KEY (from host environment)
|
||||
|
||||
Workspace Mount (Read-Write):
|
||||
- /tmp/kandev/workspaces/{task_id} → /workspace
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Flow Examples
|
||||
|
||||
### Example 1: User Creates a Task with AI Agent (with Real-time ACP Streaming)
|
||||
|
||||
```
|
||||
1. User → API Gateway: POST /api/v1/boards/{id}/tasks
|
||||
{
|
||||
"title": "Fix login bug",
|
||||
"description": "Users can't login with email",
|
||||
"agent_type": "auggie-cli",
|
||||
"repository_url": "https://github.com/user/repo",
|
||||
"branch": "main"
|
||||
}
|
||||
|
||||
2. API Gateway → Task Service: Forward request
|
||||
|
||||
3. Task Service:
|
||||
- Validate request
|
||||
- Create task in database (state: TODO)
|
||||
- Publish event to NATS: task.created
|
||||
|
||||
4. Orchestrator (subscribed to task.created):
|
||||
- Receive event
|
||||
- Check if agent_type is set
|
||||
- Add task to priority queue
|
||||
- Process queue
|
||||
|
||||
5. Orchestrator → Agent Manager (gRPC):
|
||||
LaunchAgent(task_id, agent_type="auggie-cli")
|
||||
|
||||
6. Agent Manager:
|
||||
- Create agent_instance record
|
||||
- Pull docker image "augmentcode/auggie-cli:latest"
|
||||
- **Mount host credentials (SSH keys, Git config)**
|
||||
- **Clone repository to /tmp/kandev/workspaces/{task_id}**
|
||||
- Create container with volume mounts:
|
||||
* /tmp/kandev/workspaces/{task_id} → /workspace
|
||||
* ~/.ssh → /root/.ssh (read-only)
|
||||
* ~/.gitconfig → /root/.gitconfig (read-only)
|
||||
- Start container
|
||||
- **Attach to container stdout for ACP capture**
|
||||
- Publish agent.started event
|
||||
|
||||
7. Orchestrator (subscribed to agent.started):
|
||||
- Update task state to IN_PROGRESS
|
||||
- **Subscribe to acp.message.{task_id}**
|
||||
|
||||
8. Frontend → API Gateway: WebSocket connection
|
||||
WS /api/v1/orchestrator/tasks/{task_id}/stream
|
||||
|
||||
9. API Gateway → Orchestrator: Proxy WebSocket connection
|
||||
|
||||
10. Agent Container → stdout:
|
||||
**Writes ACP messages in JSON format:**
|
||||
{"type":"progress","timestamp":"...","agent_id":"...","task_id":"...","data":{"progress":10,"message":"Analyzing codebase..."}}
|
||||
|
||||
11. Agent Manager:
|
||||
- **Captures ACP message from container stdout**
|
||||
- **Parses JSON ACP message**
|
||||
- **Publishes to NATS: acp.message.{task_id}**
|
||||
- Stores ACP message in database
|
||||
|
||||
12. Orchestrator (subscribed to acp.message.{task_id}):
|
||||
- **Receives ACP message from NATS**
|
||||
- **Broadcasts to all WebSocket clients for this task**
|
||||
|
||||
13. Frontend (via WebSocket):
|
||||
- **Receives real-time ACP message**
|
||||
- **Updates UI with progress: "Analyzing codebase... 10%"**
|
||||
|
||||
14. [Steps 10-13 repeat for each ACP message from agent]
|
||||
|
||||
15. Agent Container completes:
|
||||
- Writes final ACP result message
|
||||
- Exits with code 0
|
||||
|
||||
16. Agent Manager:
|
||||
- Captures final ACP message
|
||||
- Publishes to NATS
|
||||
- Collects exit code
|
||||
- Publishes agent.completed event
|
||||
|
||||
17. Orchestrator (subscribed to agent.completed):
|
||||
- Update task state to COMPLETED
|
||||
- Record completion time
|
||||
- **Send final ACP result to WebSocket clients**
|
||||
- Close ACP subscription
|
||||
|
||||
18. Frontend:
|
||||
- **Receives completion notification**
|
||||
- **Displays final results**
|
||||
- Closes WebSocket connection
|
||||
```
|
||||
|
||||
### Example 2: Manual Task State Change
|
||||
|
||||
```
|
||||
1. User → API Gateway: PATCH /api/v1/tasks/{id}/state
|
||||
{ "state": "IN_PROGRESS" }
|
||||
|
||||
2. API Gateway → Task Service: Forward request
|
||||
|
||||
3. Task Service:
|
||||
- Validate state transition
|
||||
- Update task state
|
||||
- Create task_event record
|
||||
- Publish task.state_changed event
|
||||
|
||||
4. Orchestrator (subscribed to task.state_changed):
|
||||
- Check if agent should be launched
|
||||
- If no agent_type set: ignore
|
||||
- If agent_type set: add to queue
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Communication Protocol (ACP)
|
||||
|
||||
### Protocol Overview
|
||||
|
||||
ACP is a JSON-based streaming protocol for real-time bidirectional communication between AI agents and the backend system.
|
||||
|
||||
**Key Characteristics:**
|
||||
- **Streaming**: Continuous message flow during agent execution
|
||||
- **Structured**: JSON format for consistency and parsing
|
||||
- **Real-time**: Low-latency delivery to frontend
|
||||
- **Bidirectional**: Agents send updates, backend can send control commands
|
||||
|
||||
### ACP Message Format
|
||||
|
||||
```json
|
||||
{
|
||||
"type": "progress|log|result|error|status|heartbeat",
|
||||
"timestamp": "2026-01-09T10:30:00Z",
|
||||
"agent_id": "uuid",
|
||||
"task_id": "uuid",
|
||||
"data": {
|
||||
// Type-specific data
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Message Types
|
||||
|
||||
**1. Progress Messages**
|
||||
```json
|
||||
{
|
||||
"type": "progress",
|
||||
"timestamp": "2026-01-09T10:30:15Z",
|
||||
"agent_id": "agent-123",
|
||||
"task_id": "task-456",
|
||||
"data": {
|
||||
"progress": 45,
|
||||
"message": "Analyzing file: src/main.go",
|
||||
"current_file": "src/main.go",
|
||||
"files_processed": 23,
|
||||
"total_files": 51
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**2. Log Messages**
|
||||
```json
|
||||
{
|
||||
"type": "log",
|
||||
"timestamp": "2026-01-09T10:30:16Z",
|
||||
"agent_id": "agent-123",
|
||||
"task_id": "task-456",
|
||||
"data": {
|
||||
"level": "info",
|
||||
"message": "Found 3 potential issues in authentication module",
|
||||
"metadata": {
|
||||
"module": "auth",
|
||||
"issues": 3
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**3. Result Messages**
|
||||
```json
|
||||
{
|
||||
"type": "result",
|
||||
"timestamp": "2026-01-09T10:35:00Z",
|
||||
"agent_id": "agent-123",
|
||||
"task_id": "task-456",
|
||||
"data": {
|
||||
"status": "completed",
|
||||
"summary": "Analysis complete. Found 12 issues, suggested 8 improvements.",
|
||||
"artifacts": [
|
||||
{
|
||||
"type": "report",
|
||||
"path": "/workspace/analysis_report.md"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**4. Error Messages**
|
||||
```json
|
||||
{
|
||||
"type": "error",
|
||||
"timestamp": "2026-01-09T10:32:00Z",
|
||||
"agent_id": "agent-123",
|
||||
"task_id": "task-456",
|
||||
"data": {
|
||||
"error": "Failed to parse file",
|
||||
"file": "src/broken.go",
|
||||
"details": "syntax error at line 45"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ACP Flow Through System
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ AI Agent │
|
||||
│ Container │
|
||||
│ │
|
||||
│ Writes to │
|
||||
│ stdout: │
|
||||
│ {"type":...} │
|
||||
└────────┬────────┘
|
||||
│ Docker logs API
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Agent Manager │
|
||||
│ │
|
||||
│ - Captures │
|
||||
│ - Parses JSON │
|
||||
│ - Validates │
|
||||
└────────┬────────┘
|
||||
│ NATS publish
|
||||
│ Subject: acp.message.{task_id}
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ NATS Event Bus │
|
||||
└────────┬────────┘
|
||||
│ NATS subscribe
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Orchestrator │
|
||||
│ │
|
||||
│ - Aggregates │
|
||||
│ - Stores in DB │
|
||||
│ - Broadcasts │
|
||||
└────────┬────────┘
|
||||
│ WebSocket
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ API Gateway │
|
||||
│ (WS Proxy) │
|
||||
└────────┬────────┘
|
||||
│ WebSocket
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Frontend UI │
|
||||
│ │
|
||||
│ - Displays │
|
||||
│ - Updates UI │
|
||||
└─────────────────┘
|
||||
```
|
||||
|
||||
### Initial Agent Types
|
||||
|
||||
**1. Auggie CLI Agent**
|
||||
- **Image**: `augmentcode/auggie-cli:latest`
|
||||
- **Capabilities**: Code analysis, generation, debugging, refactoring
|
||||
- **ACP Support**: Native
|
||||
- **Resources**: 2 CPU, 2GB RAM
|
||||
|
||||
**2. Gemini Agent**
|
||||
- **Image**: `kandev/gemini-agent:latest`
|
||||
- **Capabilities**: Code review, documentation, testing
|
||||
- **ACP Support**: Wrapper implementation
|
||||
- **Resources**: 1.5 CPU, 1.5GB RAM
|
||||
|
||||
---
|
||||
|
||||
## Database Schema Summary
|
||||
|
||||
**Tables:**
|
||||
- `users` - User accounts
|
||||
- `boards` - Kanban boards
|
||||
- `tasks` - Tasks on boards
|
||||
- `task_events` - Audit log of task changes
|
||||
- `agent_types` - Registry of available agent types
|
||||
- `agent_instances` - Running/completed agent containers
|
||||
- `agent_logs` - Logs from agent execution
|
||||
|
||||
**Key Relationships:**
|
||||
- Board → Tasks (1:N)
|
||||
- Task → Agent Instances (1:N)
|
||||
- Agent Instance → Agent Logs (1:N)
|
||||
- User → Boards (1:N)
|
||||
- User → Tasks (created_by)
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
**Backend Services:**
|
||||
- Language: Go 1.21+
|
||||
- Web Framework: Gin
|
||||
- Database: PostgreSQL 15+
|
||||
- Event Bus: NATS
|
||||
- Container Runtime: Docker
|
||||
|
||||
**Key Libraries:**
|
||||
- `github.com/docker/docker` - Docker SDK
|
||||
- `github.com/gin-gonic/gin` - HTTP framework
|
||||
- **`github.com/gorilla/websocket` - WebSocket support**
|
||||
- `github.com/jackc/pgx/v5` - PostgreSQL driver
|
||||
- `github.com/nats-io/nats.go` - NATS client
|
||||
- `github.com/golang-jwt/jwt/v5` - JWT auth
|
||||
- `go.uber.org/zap` - Structured logging
|
||||
- `google.golang.org/grpc` - gRPC communication
|
||||
|
||||
---
|
||||
|
||||
## Deployment Architecture
|
||||
|
||||
### Primary Target: Client Machines (Local Workstations)
|
||||
|
||||
The system is designed for deployment on **client machines** (developer workstations, local servers) with direct access to user credentials.
|
||||
|
||||
**Architecture:**
|
||||
```
|
||||
┌─────────────────────────────────────────────────────┐
|
||||
│ User's Local Machine │
|
||||
│ │
|
||||
│ ┌──────────────┐ ┌──────────────┐ │
|
||||
│ │ PostgreSQL │ │ NATS Server │ │
|
||||
│ │ (Docker) │ │ (Docker) │ │
|
||||
│ └──────────────┘ └──────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Kandev Backend Services │ │
|
||||
│ │ (Native binaries or Docker) │ │
|
||||
│ │ │ │
|
||||
│ │ API Gateway | Task Service | Orchestrator │ │
|
||||
│ │ Agent Manager │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Docker Engine (Agent Containers) │ │
|
||||
│ │ ┌──────────┐ ┌──────────┐ │ │
|
||||
│ │ │ Auggie │ │ Gemini │ ... │ │
|
||||
│ │ │ Agent │ │ Agent │ │ │
|
||||
│ │ └──────────┘ └──────────┘ │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────┐ │
|
||||
│ │ Host Credentials (Mounted Read-Only) │ │
|
||||
│ │ ~/.ssh/ ~/.gitconfig ~/.git-credentials │ │
|
||||
│ └──────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Deployment Methods:**
|
||||
|
||||
1. **Docker Compose** (Development)
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
2. **Native Binaries** (Production)
|
||||
```bash
|
||||
systemctl start kandev-gateway
|
||||
systemctl start kandev-task-service
|
||||
systemctl start kandev-orchestrator
|
||||
systemctl start kandev-agent-manager
|
||||
```
|
||||
|
||||
**System Requirements:**
|
||||
- OS: Linux (Ubuntu 20.04+) or macOS 12+
|
||||
- CPU: 4+ cores (8+ recommended)
|
||||
- RAM: 8GB minimum (16GB recommended)
|
||||
- Disk: 50GB free space
|
||||
- Docker: 20.10+
|
||||
|
||||
### Future Deployment Options (Roadmap)
|
||||
|
||||
**Cloud Deployment (Phase 7+):**
|
||||
```
|
||||
- Deploy to AWS/GCP/Azure
|
||||
- Managed PostgreSQL and NATS
|
||||
- Cloud secret managers for credentials
|
||||
- Horizontal scaling with load balancers
|
||||
```
|
||||
|
||||
**Kubernetes (Phase 8+):**
|
||||
```
|
||||
- Helm charts for deployment
|
||||
- StatefulSets for databases
|
||||
- Deployments for services
|
||||
- Horizontal Pod Autoscaling
|
||||
- Ingress for external access
|
||||
```
|
||||
|
||||
**Multi-User SaaS (Phase 9+):**
|
||||
```
|
||||
- Tenant isolation
|
||||
- Centralized credential management
|
||||
- Usage-based billing
|
||||
```
|
||||
|
||||
@@ -0,0 +1,260 @@
|
||||
# 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**
|
||||
```bash
|
||||
# Check version
|
||||
go version
|
||||
|
||||
# Install from https://go.dev/dl/
|
||||
```
|
||||
|
||||
2. **Docker**
|
||||
```bash
|
||||
# Check version
|
||||
docker --version
|
||||
|
||||
# Install from https://docs.docker.com/get-docker/
|
||||
```
|
||||
|
||||
3. **Augment CLI Credentials**
|
||||
```bash
|
||||
# Verify Augment session exists
|
||||
cat ~/.augment/session.json
|
||||
```
|
||||
|
||||
4. **Git with SSH Keys Configured** (for repository access)
|
||||
```bash
|
||||
git --version
|
||||
|
||||
# Verify SSH keys exist
|
||||
ls -la ~/.ssh/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Step 1: Build the Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
|
||||
# Build the binary
|
||||
make build
|
||||
|
||||
# This creates ./bin/kandev
|
||||
```
|
||||
|
||||
### Step 2: Run the Server
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Health check
|
||||
curl http://localhost:8080/health
|
||||
|
||||
# Should return: {"status":"ok"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Create a Board
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/boards \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "My Project", "description": "Project tasks"}'
|
||||
```
|
||||
|
||||
### Create a Column
|
||||
|
||||
```bash
|
||||
curl -X POST http://localhost:8080/api/v1/boards/{board_id}/columns \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name": "To Do"}'
|
||||
```
|
||||
|
||||
### Create a Task
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
make build
|
||||
```
|
||||
|
||||
### Run Tests
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
make test
|
||||
|
||||
# Or with verbose output
|
||||
go test -v ./...
|
||||
```
|
||||
|
||||
### Code Formatting
|
||||
|
||||
```bash
|
||||
go fmt ./...
|
||||
go vet ./...
|
||||
```
|
||||
|
||||
### View Database
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Add user to docker group (Linux)
|
||||
sudo usermod -aG docker $USER
|
||||
newgrp docker
|
||||
```
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
```bash
|
||||
# Find process using port 8080
|
||||
lsof -i :8080
|
||||
|
||||
# Kill it
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Database Issues
|
||||
|
||||
```bash
|
||||
# Delete and recreate database
|
||||
rm backend/kandev.db
|
||||
./bin/kandev # Will create fresh database
|
||||
```
|
||||
|
||||
### Agent Container Issues
|
||||
|
||||
```bash
|
||||
# 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](../backend/NEXT_STEPS.md) for the development roadmap and immediate next steps.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user