# bytefolk/digital-employee architecture

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

- Interactive diagram: https://gitdiagram.com/bytefolk/digital-employee
- Repository: https://github.com/bytefolk/digital-employee

## Overview

Digital Employee is a local-first workspace for addressing work to positions in a digital organization, with context and permission boundaries. The main workflow is: a user selects a position and sends a turn through the Workbench; the turn engine assembles context, applies policy, invokes a model/host, and returns an answer with evidence. Separate capabilities cover employee packages, organization setup and delegation, CLI run/evaluation/deploy, and optional channels and memory. The README documents several links whose implementation was not sampled; those are represented only where the workflow is explicit.

Main entry points: [`packages/engine/src/turn-executor.ts`](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/turn-executor.ts) (Turn executor), [`apps/cli/turn/turn-run.ts`](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/turn/turn-run.ts) (Turn runner), [`apps/cli/bin.ts`](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/bin.ts) (CLI entry), [`apps/cli/deploy/index.ts`](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/deploy/index.ts) (Deploy command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Workspace and CLI"]
  node_cli["CLI entry<br/>[bin.ts]"]
  node_workbench["Workbench server<br/>[server.ts]"]
  node_turnrun["Turn runner<br/>[turn-run.ts]"]
  node_deploy["Deploy command<br/>[index.ts]"]
end

subgraph group_org["Organization and packages"]
  node_package["Employee package"]
  node_hire["Hiring flow<br/>[hire.ts]"]
  node_orgmodel["Organization model<br/>[model.ts]"]
  node_permissions["Org permissions<br/>[permissions.ts]"]
end

subgraph group_engine["Turn engine"]
  node_engine["Turn executor<br/>[turn-executor.ts]"]
  node_context["Context assembly"]
  node_approval["Approval policy<br/>[approval.ts]"]
  node_evidence["Turn evidence<br/>[turn-evidence.ts]"]
  node_modelport["Model port<br/>[model-port.ts]"]
end

subgraph group_connectors["Hosts and channels"]
  node_hostruntime["Host runtime<br/>[host-runtime.ts]"]
  node_agenthosts["Agent host adapters<br/>[agent-hosts.ts]"]
  node_dingtalk["DingTalk channel<br/>[index.ts]"]
end

subgraph group_data["Context and sources"]
  node_memory["Memory adapter"]
  node_retriever["Lexical retriever"]
  node_git["Git source<br/>[index.ts]"]
end

node_user(("Business user"))
node_modelservice(("Model service"))
node_agenthost(("External agent host"))

node_user -->|"sends turn"| node_workbench
node_workbench -->|"runs turn"| node_turnrun
node_turnrun -->|"executes turn"| node_engine
node_engine -->|"assembles context"| node_context
node_engine -->|"checks permissions"| node_permissions
node_engine -->|"applies policy"| node_approval
node_engine -->|"requests completion"| node_modelport
node_modelport -.->|"selects host"| node_agenthosts
node_agenthosts -.->|"invokes host"| node_agenthost
node_modelport -.->|"calls model"| node_modelservice
node_engine -->|"records evidence"| node_evidence
node_turnrun -->|"returns output"| node_workbench
node_cli -->|"dispatches turn"| node_turnrun
node_cli -->|"dispatches deploy"| node_deploy
node_deploy -->|"probes hosts"| node_agenthosts
node_deploy -.->|"configures channel"| node_dingtalk
node_cli -->|"dispatches hiring"| node_hire
node_hire -->|"creates package"| node_package
node_hire -->|"sets position"| node_orgmodel
node_context -.->|"recalls context"| node_memory
node_context -.->|"retrieves evidence"| node_retriever
node_retriever -.->|"reads documents"| node_git

click node_cli "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/bin.ts"
click node_workbench "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/workbench/server.ts"
click node_turnrun "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/turn/turn-run.ts"
click node_deploy "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/deploy/index.ts"
click node_package "https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/employee-package.ts"
click node_hire "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/hire.ts"
click node_orgmodel "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/org/model.ts"
click node_permissions "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/org/permissions.ts"
click node_engine "https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/turn-executor.ts"
click node_context "https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/context-assembler.ts"
click node_approval "https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/approval.ts"
click node_evidence "https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/turn-evidence.ts"
click node_modelport "https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/model-port.ts"
click node_hostruntime "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/host-runtime.ts"
click node_agenthosts "https://github.com/bytefolk/digital-employee/blob/main/apps/cli/agent-hosts.ts"
click node_dingtalk "https://github.com/bytefolk/digital-employee/blob/main/connectors/channels/dingtalk/index.ts"
click node_memory "https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/mem-http-memory-adapter.ts"
click node_retriever "https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/lexical-retriever.ts"
click node_git "https://github.com/bytefolk/digital-employee/blob/main/connectors/sources/git/index.ts"

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_cli,node_workbench,node_turnrun,node_deploy,node_user toneBlue
class node_package,node_hire,node_orgmodel,node_permissions toneAmber
class node_engine,node_context,node_approval,node_evidence,node_modelport toneMint
class node_hostruntime,node_agenthosts,node_dingtalk toneRose
class node_memory,node_retriever,node_git,node_modelservice,node_agenthost toneIndigo
```

## Components

### Workspace and CLI

- [CLI entry](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/bin.ts): `apps/cli/bin.ts`
- [Workbench server](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/workbench/server.ts): `apps/cli/workbench/server.ts`
- [Turn runner](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/turn/turn-run.ts): `apps/cli/turn/turn-run.ts`
- [Deploy command](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/deploy/index.ts): `apps/cli/deploy/index.ts`

### Organization and packages

- [Employee package](https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/employee-package.ts): `packages/core/src/employee-package.ts`
- [Hiring flow](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/hire.ts): `apps/cli/hire.ts`
- [Organization model](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/org/model.ts): `apps/cli/org/model.ts`
- [Org permissions](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/org/permissions.ts): `apps/cli/org/permissions.ts`

### Turn engine

- [Turn executor](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/turn-executor.ts): `packages/engine/src/turn-executor.ts`
- [Context assembly](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/context-assembler.ts): `packages/engine/src/context-assembler.ts`
- [Approval policy](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/approval.ts): `packages/engine/src/approval.ts`
- [Turn evidence](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/turn-evidence.ts): `packages/engine/src/turn-evidence.ts`
- [Model port](https://github.com/bytefolk/digital-employee/blob/main/packages/engine/src/model-port.ts): `packages/engine/src/model-port.ts`

### Hosts and channels

- [Host runtime](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/host-runtime.ts): `apps/cli/host-runtime.ts`
- [Agent host adapters](https://github.com/bytefolk/digital-employee/blob/main/apps/cli/agent-hosts.ts): `apps/cli/agent-hosts.ts`
- [DingTalk channel](https://github.com/bytefolk/digital-employee/blob/main/connectors/channels/dingtalk/index.ts): `connectors/channels/dingtalk/index.ts`

### Context and sources

- [Memory adapter](https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/mem-http-memory-adapter.ts): `packages/core/src/mem-http-memory-adapter.ts`
- [Lexical retriever](https://github.com/bytefolk/digital-employee/blob/main/packages/core/src/lexical-retriever.ts): `packages/core/src/lexical-retriever.ts`
- [Git source](https://github.com/bytefolk/digital-employee/blob/main/connectors/sources/git/index.ts): `connectors/sources/git/index.ts`

### Other components

- **Business user**
- **Model service**
- **External agent host**

## Connections

- Business user → Workbench server: sends turn
- Workbench server → Turn runner: runs turn
- Turn runner → Turn executor: executes turn
- Turn executor → Context assembly: assembles context
- Turn executor → Org permissions: checks permissions
- Turn executor → Approval policy: applies policy
- Turn executor → Model port: requests completion
- Model port → Agent host adapters: selects host
- Agent host adapters → External agent host: invokes host
- Model port → Model service: calls model
- Turn executor → Turn evidence: records evidence
- Turn runner → Workbench server: returns output
- CLI entry → Turn runner: dispatches turn
- CLI entry → Deploy command: dispatches deploy
- Deploy command → Agent host adapters: probes hosts
- Deploy command → DingTalk channel: configures channel
- CLI entry → Hiring flow: dispatches hiring
- Hiring flow → Employee package: creates package
- Hiring flow → Organization model: sets position
- Context assembly → Memory adapter: recalls context
- Context assembly → Lexical retriever: retrieves evidence
- Lexical retriever → Git source: reads documents