# gurukiran10/ai-workforce architecture

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

- Interactive diagram: https://gitdiagram.com/gurukiran10/ai-workforce
- Repository: https://github.com/gurukiran10/ai-workforce

## Overview

Acme Workforce is a role-configured AI employee system that carries out browser-based business tasks, escalates decisions to a human, and reports completion only after independent verification. The principal workflow runs from task assignment through role selection, planning and browser actions, safety checks, and verification; the console also supports reviewing runs and approving learned rules. The sandbox supplies sample mail, ERP, recruiting, and ATS applications. Some console-to-runtime wiring and unsampled subsystem details are documented but not shown in the excerpts, so those links are marked unverified or omitted.

Main entry points: [`worker/runtime.py`](https://github.com/gurukiran10/ai-workforce/blob/main/worker/runtime.py) (Task runtime), [`viewer/routes.py`](https://github.com/gurukiran10/ai-workforce/blob/main/viewer/routes.py) (Workforce console), [`worker/verifier.py`](https://github.com/gurukiran10/ai-workforce/blob/main/worker/verifier.py) (Independent verifier), [`worker/llm.py`](https://github.com/gurukiran10/ai-workforce/blob/main/worker/llm.py) (Model interface)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Worker runtime"]
  node_runtime["Task runtime<br/>[runtime.py]"]
  node_planning["Plans and prompts<br/>[prompts.py]"]
  node_llm["Model interface<br/>[llm.py]"]
  node_provider["Model providers<br/>[llm_converse.py]"]
  node_tools["Generic action tools<br/>[tools.py]"]
  node_browser["Browser interaction<br/>[browser.py]"]
  node_policy["Safety policy<br/>[policy.py]"]
  node_verifier["Independent verifier<br/>[verifier.py]"]
end

subgraph group_knowledge["Roles and learning"]
  node_role["Role definitions<br/>[role.py]"]
  node_rolefiles["Employee role files<br/>[diya.yaml]"]
  node_learning["Learning and trust<br/>[learning.py]"]
  node_memory["Company memory<br/>[memory.py]"]
end

subgraph group_oversight["Human oversight"]
  node_console["Workforce console<br/>[routes.py]"]
  node_human["Human decision channel<br/>[human.py]"]
end

subgraph group_company["Sandbox company apps"]
  node_sandbox["Sandbox web apps<br/>[app.py]"]
  node_seed["Company sample data<br/>[seed.py]"]
  node_invoice["Invoice PDFs<br/>[invoices.py]"]
end

subgraph group_evidence["Run evidence"]
  node_trace["Run trace and state<br/>[trace.py]"]
  node_report["Run report<br/>[report.py]"]
  node_runfiles["Saved run artifacts"]
end

node_operator(("Employee"))
node_llmservice{{"LLM service"}}

node_operator -->|"assigns work"| node_console
node_console -.->|"routes tasks"| node_runtime
node_runtime -->|"loads role"| node_role
node_role -.->|"reads definitions"| node_rolefiles
node_runtime -->|"builds prompts"| node_planning
node_runtime -->|"requests decisions"| node_llm
node_llm -->|"selects adapter"| node_provider
node_provider -.->|"sends requests"| node_llmservice
node_runtime -->|"dispatches tools"| node_tools
node_tools -->|"performs actions"| node_browser
node_runtime -->|"checks actions"| node_policy
node_runtime -->|"requests decisions"| node_human
node_human -->|"exchanges responses"| node_console
node_browser -.->|"uses web apps"| node_sandbox
node_runtime -->|"checks completion"| node_verifier
node_verifier -->|"requests review"| node_llm
node_verifier -.->|"rechecks systems"| node_browser
node_runtime -->|"records learning"| node_learning
node_learning -->|"adds approved rules"| node_memory
node_console -->|"reviews proposals"| node_learning
node_runtime -->|"records events"| node_trace
node_runtime -->|"creates report"| node_report
node_trace -.->|"persists evidence"| node_runfiles
node_report -.->|"saves result"| node_runfiles
node_console -->|"reads run evidence"| node_runfiles
node_sandbox -->|"uses sample data"| node_seed
node_seed -->|"renders invoices"| node_invoice

click node_console "https://github.com/gurukiran10/ai-workforce/blob/main/viewer/routes.py"
click node_runtime "https://github.com/gurukiran10/ai-workforce/blob/main/worker/runtime.py"
click node_role "https://github.com/gurukiran10/ai-workforce/blob/main/worker/role.py"
click node_rolefiles "https://github.com/gurukiran10/ai-workforce/blob/main/roles/diya.yaml"
click node_planning "https://github.com/gurukiran10/ai-workforce/blob/main/worker/prompts.py"
click node_llm "https://github.com/gurukiran10/ai-workforce/blob/main/worker/llm.py"
click node_provider "https://github.com/gurukiran10/ai-workforce/blob/main/worker/llm_converse.py"
click node_tools "https://github.com/gurukiran10/ai-workforce/blob/main/worker/tools.py"
click node_browser "https://github.com/gurukiran10/ai-workforce/blob/main/worker/browser.py"
click node_policy "https://github.com/gurukiran10/ai-workforce/blob/main/worker/policy.py"
click node_human "https://github.com/gurukiran10/ai-workforce/blob/main/worker/human.py"
click node_verifier "https://github.com/gurukiran10/ai-workforce/blob/main/worker/verifier.py"
click node_learning "https://github.com/gurukiran10/ai-workforce/blob/main/worker/learning.py"
click node_memory "https://github.com/gurukiran10/ai-workforce/blob/main/worker/memory.py"
click node_trace "https://github.com/gurukiran10/ai-workforce/blob/main/worker/trace.py"
click node_report "https://github.com/gurukiran10/ai-workforce/blob/main/worker/report.py"
click node_runfiles "https://github.com/gurukiran10/ai-workforce/tree/main/runs"
click node_sandbox "https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/app.py"
click node_seed "https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/seed.py"
click node_invoice "https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/invoices.py"

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_runtime,node_planning,node_llm,node_provider,node_tools,node_browser,node_policy,node_verifier toneBlue
class node_role,node_rolefiles,node_learning,node_memory toneAmber
class node_console,node_human toneMint
class node_sandbox,node_seed,node_invoice toneRose
class node_trace,node_report,node_runfiles,node_operator,node_llmservice toneIndigo
```

## Components

### Worker runtime

- [Task runtime](https://github.com/gurukiran10/ai-workforce/blob/main/worker/runtime.py): `worker/runtime.py`
- [Plans and prompts](https://github.com/gurukiran10/ai-workforce/blob/main/worker/prompts.py): `worker/prompts.py`
- [Model interface](https://github.com/gurukiran10/ai-workforce/blob/main/worker/llm.py): `worker/llm.py`
- [Model providers](https://github.com/gurukiran10/ai-workforce/blob/main/worker/llm_converse.py): `worker/llm_converse.py`
- [Generic action tools](https://github.com/gurukiran10/ai-workforce/blob/main/worker/tools.py): `worker/tools.py`
- [Browser interaction](https://github.com/gurukiran10/ai-workforce/blob/main/worker/browser.py): `worker/browser.py`
- [Safety policy](https://github.com/gurukiran10/ai-workforce/blob/main/worker/policy.py): `worker/policy.py`
- [Independent verifier](https://github.com/gurukiran10/ai-workforce/blob/main/worker/verifier.py): `worker/verifier.py`

### Roles and learning

- [Role definitions](https://github.com/gurukiran10/ai-workforce/blob/main/worker/role.py): `worker/role.py`
- [Employee role files](https://github.com/gurukiran10/ai-workforce/blob/main/roles/diya.yaml): `roles/diya.yaml`
- [Learning and trust](https://github.com/gurukiran10/ai-workforce/blob/main/worker/learning.py): `worker/learning.py`
- [Company memory](https://github.com/gurukiran10/ai-workforce/blob/main/worker/memory.py): `worker/memory.py`

### Human oversight

- [Workforce console](https://github.com/gurukiran10/ai-workforce/blob/main/viewer/routes.py): `viewer/routes.py`
- [Human decision channel](https://github.com/gurukiran10/ai-workforce/blob/main/worker/human.py): `worker/human.py`

### Sandbox company apps

- [Sandbox web apps](https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/app.py): `sandbox/app.py`
- [Company sample data](https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/seed.py): `sandbox/seed.py`
- [Invoice PDFs](https://github.com/gurukiran10/ai-workforce/blob/main/sandbox/invoices.py): `sandbox/invoices.py`

### Run evidence

- [Run trace and state](https://github.com/gurukiran10/ai-workforce/blob/main/worker/trace.py): `worker/trace.py`
- [Run report](https://github.com/gurukiran10/ai-workforce/blob/main/worker/report.py): `worker/report.py`
- [Saved run artifacts](https://github.com/gurukiran10/ai-workforce/tree/main/runs): `runs`

### Other components

- **Employee**
- **LLM service**

## Connections

- Employee → Workforce console: assigns work (evidence: `README.md`)
- Workforce console → Task runtime: routes tasks
- Task runtime → Role definitions: loads role (evidence: `worker/runtime.py`)
- Role definitions → Employee role files: reads definitions (evidence: `README.md`)
- Task runtime → Plans and prompts: builds prompts (evidence: `worker/runtime.py`)
- Task runtime → Model interface: requests decisions (evidence: `worker/runtime.py`)
- Model interface → Model providers: selects adapter (evidence: `worker/llm.py`)
- Model providers → LLM service: sends requests
- Task runtime → Generic action tools: dispatches tools (evidence: `worker/runtime.py`)
- Generic action tools → Browser interaction: performs actions (evidence: `worker/tools.py`)
- Task runtime → Safety policy: checks actions (evidence: `worker/runtime.py`)
- Task runtime → Human decision channel: requests decisions (evidence: `worker/runtime.py`)
- Human decision channel → Workforce console: exchanges responses (evidence: `worker/human.py`)
- Browser interaction → Sandbox web apps: uses web apps (evidence: `README.md`)
- Task runtime → Independent verifier: checks completion (evidence: `worker/runtime.py`)
- Independent verifier → Model interface: requests review (evidence: `worker/verifier.py`)
- Independent verifier → Browser interaction: rechecks systems (evidence: `README.md`)
- Task runtime → Learning and trust: records learning
- Learning and trust → Company memory: adds approved rules (evidence: `worker/learning.py`)
- Workforce console → Learning and trust: reviews proposals (evidence: `viewer/routes.py`)
- Task runtime → Run trace and state: records events (evidence: `worker/runtime.py`)
- Task runtime → Run report: creates report (evidence: `worker/runtime.py`)
- Run trace and state → Saved run artifacts: persists evidence
- Run report → Saved run artifacts: saves result
- Workforce console → Saved run artifacts: reads run evidence (evidence: `viewer/routes.py`)
- Sandbox web apps → Company sample data: uses sample data (evidence: `sandbox/app.py`)
- Company sample data → Invoice PDFs: renders invoices (evidence: `sandbox/seed.py`)
