# kdlbs/kandev architecture

> Architecture diagram of the GitHub repository kdlbs/kandev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kdlbs/kandev
- Repository: https://github.com/kdlbs/kandev

## Overview

Kandev is a self-hostable control plane for managing parallel tasks, orchestrating AI agents through configurable workflows, and reviewing their changes in an integrated workspace. The principal flow is task creation and workflow execution in an isolated runtime, followed by human review. The graph also preserves documented integrations, statistics, and the developing Office-mode capabilities. Several backend subsystems are represented at their existing directory paths because their implementations were not sampled; edges use README documentation where it establishes the relationship.

Main entry points: [`apps/backend/internal/agent/runtime/lifecycle`](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/runtime/lifecycle) (Runtime lifecycle), [`apps/web/app/tasks/tasks-page-client.tsx`](https://github.com/kdlbs/kandev/blob/main/apps/web/app/tasks/tasks-page-client.tsx) (Task management), [`apps/backend/internal/task`](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/task) (Task services), [`apps/backend/internal/workflow/engine/engine.go`](https://github.com/kdlbs/kandev/blob/main/apps/backend/internal/workflow/engine/engine.go) (Workflow engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_taskflow["Task orchestration"]
  node_tasks_ui["Task management"]
  node_task_service["Task services"]
  node_workflow["Workflow engine<br/>[engine.go]"]
  node_orchestrator["Agent orchestrator"]
end

subgraph group_execution["Agent execution"]
  node_worktree["Worktree isolation"]
  node_lifecycle["Runtime lifecycle"]
  node_agent_providers["Agent providers"]
  node_workspace["Integrated workspace"]
  node_agentctl["Agent runtime client"]
end

subgraph group_review["Review and insights"]
  node_stats["Statistics dashboard"]
  node_review_service["Change review<br/>[review_service.go]"]
end

subgraph group_integrations["External integrations"]
  node_gitlab_ui["GitLab workspace"]
  node_gitlab_state["GitLab page state"]
  node_integrations_backend["Issue integrations"]
end

subgraph group_office["Office mode"]
  node_office_dashboard["Office dashboard<br/>[page-client.tsx]"]
  node_office_capabilities["Office capabilities"]
end

node_developer(("Developer"))
node_external_services{{"Connected services"}}

node_developer -->|"manages tasks"| node_tasks_ui
node_tasks_ui -.->|"creates tasks"| node_task_service
node_task_service -.->|"runs workflow"| node_workflow
node_workflow -.->|"orchestrates agents"| node_orchestrator
node_orchestrator -.->|"starts runtime"| node_lifecycle
node_lifecycle -.->|"isolates workspace"| node_worktree
node_lifecycle -.->|"runs provider"| node_agent_providers
node_agentctl -.->|"serves workspace tools"| node_workspace
node_developer -->|"views issues"| node_gitlab_ui
node_gitlab_ui -->|"uses page state"| node_gitlab_state
node_external_services -->|"provides issues"| node_integrations_backend
node_developer -->|"views activity"| node_stats
node_developer -->|"reviews changes"| node_review_service
node_developer -->|"manages teams"| node_office_dashboard
node_office_dashboard -.->|"uses office features"| node_office_capabilities

click node_tasks_ui "https://github.com/kdlbs/kandev/blob/main/apps/web/app/tasks/tasks-page-client.tsx"
click node_task_service "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/task"
click node_workflow "https://github.com/kdlbs/kandev/blob/main/apps/backend/internal/workflow/engine/engine.go"
click node_orchestrator "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/orchestrator"
click node_worktree "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/worktree"
click node_lifecycle "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/runtime/lifecycle"
click node_agent_providers "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/agents"
click node_workspace "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/handlers"
click node_agentctl "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/runtime/agentctl"
click node_gitlab_ui "https://github.com/kdlbs/kandev/blob/main/apps/web/app/gitlab/gitlab-page-client.tsx"
click node_gitlab_state "https://github.com/kdlbs/kandev/blob/main/apps/web/app/gitlab/use-gitlab-page-state.ts"
click node_integrations_backend "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal"
click node_stats "https://github.com/kdlbs/kandev/tree/main/apps/web/app/stats"
click node_review_service "https://github.com/kdlbs/kandev/blob/main/apps/backend/internal/task/service/review_service.go"
click node_office_dashboard "https://github.com/kdlbs/kandev/blob/main/apps/web/app/office/page-client.tsx"
click node_office_capabilities "https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/office"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tasks_ui,node_task_service,node_workflow,node_orchestrator toneBlue
class node_worktree,node_lifecycle,node_agent_providers,node_workspace,node_agentctl toneAmber
class node_stats,node_review_service toneMint
class node_gitlab_ui,node_gitlab_state,node_integrations_backend toneRose
class node_office_dashboard,node_office_capabilities,node_developer,node_external_services toneIndigo
```

## Components

### Task orchestration

- [Task management](https://github.com/kdlbs/kandev/blob/main/apps/web/app/tasks/tasks-page-client.tsx): `apps/web/app/tasks/tasks-page-client.tsx`
- [Task services](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/task): `apps/backend/internal/task`
- [Workflow engine](https://github.com/kdlbs/kandev/blob/main/apps/backend/internal/workflow/engine/engine.go): `apps/backend/internal/workflow/engine/engine.go`
- [Agent orchestrator](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/orchestrator): `apps/backend/internal/orchestrator`

### Agent execution

- [Worktree isolation](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/worktree): `apps/backend/internal/worktree`
- [Runtime lifecycle](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/runtime/lifecycle): `apps/backend/internal/agent/runtime/lifecycle`
- [Agent providers](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/agents): `apps/backend/internal/agent/agents`
- [Integrated workspace](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/handlers): `apps/backend/internal/agent/handlers`
- [Agent runtime client](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/agent/runtime/agentctl): `apps/backend/internal/agent/runtime/agentctl`

### Review and insights

- [Statistics dashboard](https://github.com/kdlbs/kandev/tree/main/apps/web/app/stats): `apps/web/app/stats`
- [Change review](https://github.com/kdlbs/kandev/blob/main/apps/backend/internal/task/service/review_service.go): `apps/backend/internal/task/service/review_service.go`

### External integrations

- [GitLab workspace](https://github.com/kdlbs/kandev/blob/main/apps/web/app/gitlab/gitlab-page-client.tsx): `apps/web/app/gitlab/gitlab-page-client.tsx`
- [GitLab page state](https://github.com/kdlbs/kandev/blob/main/apps/web/app/gitlab/use-gitlab-page-state.ts): `apps/web/app/gitlab/use-gitlab-page-state.ts`
- [Issue integrations](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal): `apps/backend/internal`

### Office mode

- [Office dashboard](https://github.com/kdlbs/kandev/blob/main/apps/web/app/office/page-client.tsx): `apps/web/app/office/page-client.tsx`
- [Office capabilities](https://github.com/kdlbs/kandev/tree/main/apps/backend/internal/office): `apps/backend/internal/office`

### Other components

- **Developer**
- **Connected services**

## Connections

- Developer → Task management: manages tasks (evidence: `README.md`)
- Task management → Task services: creates tasks
- Task services → Workflow engine: runs workflow
- Workflow engine → Agent orchestrator: orchestrates agents
- Agent orchestrator → Runtime lifecycle: starts runtime
- Runtime lifecycle → Worktree isolation: isolates workspace
- Runtime lifecycle → Agent providers: runs provider
- Agent runtime client → Integrated workspace: serves workspace tools
- Developer → GitLab workspace: views issues (evidence: `README.md`)
- GitLab workspace → GitLab page state: uses page state (evidence: `apps/web/app/gitlab/gitlab-page-client.tsx`)
- Connected services → Issue integrations: provides issues (evidence: `README.md`)
- Developer → Statistics dashboard: views activity (evidence: `README.md`)
- Developer → Change review: reviews changes (evidence: `README.md`)
- Developer → Office dashboard: manages teams (evidence: `README.md`)
- Office dashboard → Office capabilities: uses office features
