# jdhubbard777/agentus.app architecture

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

- Interactive diagram: https://gitdiagram.com/jdhubbard777/agentus.app
- Repository: https://github.com/jdhubbard777/agentus.app

## Overview

AgentUS is a specialist-hiring product: customers configure named specialists, use them interactively, and define unattended workflows whose runs and outcomes are retained. The documented architecture separates interactive chat through the OpenClaw gateway from webhook/scheduled dispatch, which calls model APIs directly and records results and token costs in D1. The dashboard and Worker expose the product’s workflow, specialist, account, and administration capabilities; provisioning connects specialist instances to Hetzner VMs. Several route implementations were not sampled, so those branches reflect README capability descriptions rather than inspected call chains.

Main entry points: [`backend/src/worker.ts`](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/worker.ts) (HTTP and scheduled entry), [`frontend/src/App.tsx`](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/App.tsx) (Dashboard routes), [`backend/src/routes/dispatcher.ts`](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/dispatcher.ts) (Workflow dispatcher), [`backend/src/workflows/provision.ts`](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/workflows/provision.ts) (VM provisioning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dashboard["Customer dashboard"]
  node_dashboard_app["Dashboard routes<br/>[App.tsx]"]
  node_auth_ui["Session and user state<br/>[AuthContext.tsx]"]
  node_specialist_ui["Specialist workspace<br/>[Team.tsx]"]
  node_workflow_ui["Workflow builder"]
  node_history_ui["Run history"]
  node_admin_ui["Administration"]
end

subgraph group_api["Worker API"]
  node_api_worker["HTTP and scheduled entry<br/>[worker.ts]"]
  node_auth_routes["Authentication<br/>[auth.ts]"]
  node_workflow_routes["Workflow endpoints<br/>[workflows.ts]"]
  node_dispatch_routes["Dispatcher endpoints<br/>[dispatcher.ts]"]
  node_persona_routes["Specialist endpoints<br/>[personas.ts]"]
  node_task_routes["Task run endpoints<br/>[taskRuns.ts]"]
  node_auth_middleware["Token and role checks<br/>[auth.ts]"]
end

subgraph group_execution["Specialist execution"]
  node_chat["Interactive chat<br/>[chat.ts]"]
  node_openclaw["OpenClaw gateway"]
  node_dispatcher["Workflow dispatcher<br/>[dispatcher.ts]"]
  node_model_runtime["Direct model runtime"]
  node_destinations["Slack, email, webhook"]
end

subgraph group_state["Product state"]
  node_d1[("Cloudflare D1")]
  node_db_access["D1 query adapter<br/>[db.ts]"]
  node_workflow_state["Workflow and task records"]
  node_instance_state["Instance records"]
end

subgraph group_operations["Provisioning and operations"]
  node_provisioning["VM provisioning<br/>[provision.ts]"]
  node_hetzner["Hetzner Cloud<br/>[hetzner.js]"]
  node_warm_pool["Warm VM pool<br/>[warmPoolManager.ts]"]
end

node_customer(("Customer"))

node_customer -->|"uses"| node_dashboard_app
node_dashboard_app -->|"checks session"| node_auth_ui
node_dashboard_app -->|"routes to"| node_specialist_ui
node_dashboard_app -->|"routes to"| node_workflow_ui
node_dashboard_app -->|"routes to"| node_history_ui
node_dashboard_app -->|"routes to"| node_admin_ui
node_dashboard_app -->|"calls API"| node_api_worker
node_api_worker -->|"mounts"| node_auth_routes
node_api_worker -->|"mounts"| node_workflow_routes
node_api_worker -->|"mounts"| node_dispatch_routes
node_api_worker -->|"mounts"| node_persona_routes
node_api_worker -->|"mounts"| node_task_routes
node_api_worker -->|"applies"| node_auth_middleware
node_customer -->|"chats with specialist"| node_chat
node_chat -->|"uses gateway"| node_openclaw
node_customer -->|"configures"| node_workflow_ui
node_workflow_routes -.->|"persists workflows"| node_workflow_state
node_customer -->|"triggers work"| node_dispatcher
node_dispatcher -->|"calls model API"| node_model_runtime
node_dispatcher -->|"delivers output"| node_destinations
node_dispatcher -->|"records runs and costs"| node_workflow_state
node_task_routes -.->|"serves run records"| node_workflow_state
node_api_worker -->|"uses D1 access"| node_db_access
node_db_access -->|"queries"| node_d1
node_workflow_state -.->|"stores records"| node_d1
node_instance_state -.->|"stores instances"| node_d1
node_api_worker -.->|"starts provisioning"| node_provisioning
node_provisioning -->|"creates VMs"| node_hetzner
node_provisioning -.->|"tracks instances"| node_instance_state
node_api_worker -->|"runs scheduled refill"| node_warm_pool
node_warm_pool -.->|"requests capacity"| node_provisioning
node_admin_ui -.->|"manages service"| node_api_worker

click node_dashboard_app "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/App.tsx"
click node_auth_ui "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/context/AuthContext.tsx"
click node_specialist_ui "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/Team.tsx"
click node_workflow_ui "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/WorkflowBuilder.tsx"
click node_history_ui "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/WorkflowHistory.tsx"
click node_api_worker "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/worker.ts"
click node_auth_routes "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/auth.ts"
click node_workflow_routes "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/workflows.ts"
click node_dispatch_routes "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/dispatcher.ts"
click node_persona_routes "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/personas.ts"
click node_task_routes "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/taskRuns.ts"
click node_auth_middleware "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/middleware/auth.ts"
click node_chat "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/chat.ts"
click node_dispatcher "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/dispatcher.ts"
click node_model_runtime "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/runtime/directModelRuntime.ts"
click node_db_access "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/db.ts"
click node_workflow_state "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/repositories/workflowRepository.ts"
click node_instance_state "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/repositories/instanceRepository.ts"
click node_provisioning "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/workflows/provision.ts"
click node_hetzner "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/providers/hetzner.js"
click node_warm_pool "https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/warmPool/warmPoolManager.ts"
click node_admin_ui "https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/AdminHetznerPage.tsx"

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_dashboard_app,node_auth_ui,node_specialist_ui,node_workflow_ui,node_history_ui,node_admin_ui toneBlue
class node_api_worker,node_auth_routes,node_workflow_routes,node_dispatch_routes,node_persona_routes,node_task_routes,node_auth_middleware toneAmber
class node_chat,node_openclaw,node_dispatcher,node_model_runtime,node_destinations toneMint
class node_d1,node_db_access,node_workflow_state,node_instance_state toneRose
class node_provisioning,node_hetzner,node_warm_pool,node_customer toneIndigo
```

## Components

### Customer dashboard

- [Dashboard routes](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Session and user state](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Specialist workspace](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/Team.tsx): `frontend/src/pages/Team.tsx`
- [Workflow builder](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/WorkflowBuilder.tsx): `frontend/src/pages/WorkflowBuilder.tsx`
- [Run history](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/WorkflowHistory.tsx): `frontend/src/pages/WorkflowHistory.tsx`
- [Administration](https://github.com/jdhubbard777/agentus.app/blob/main/frontend/src/pages/AdminHetznerPage.tsx): `frontend/src/pages/AdminHetznerPage.tsx`

### Worker API

- [HTTP and scheduled entry](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/worker.ts): `backend/src/worker.ts`
- [Authentication](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/auth.ts): `backend/src/routes/auth.ts`
- [Workflow endpoints](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/workflows.ts): `backend/src/routes/workflows.ts`
- [Dispatcher endpoints](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/dispatcher.ts): `backend/src/routes/dispatcher.ts`
- [Specialist endpoints](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/personas.ts): `backend/src/routes/personas.ts`
- [Task run endpoints](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/taskRuns.ts): `backend/src/routes/taskRuns.ts`
- [Token and role checks](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/middleware/auth.ts): `backend/src/middleware/auth.ts`

### Specialist execution

- [Interactive chat](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/chat.ts): `backend/src/routes/chat.ts`
- **OpenClaw gateway**
- [Workflow dispatcher](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/routes/dispatcher.ts): `backend/src/routes/dispatcher.ts`
- [Direct model runtime](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/runtime/directModelRuntime.ts): `backend/src/runtime/directModelRuntime.ts`
- **Slack, email, webhook**

### Product state

- **Cloudflare D1**
- [D1 query adapter](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/db.ts): `backend/src/database/db.ts`
- [Workflow and task records](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/repositories/workflowRepository.ts): `backend/src/database/repositories/workflowRepository.ts`
- [Instance records](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/database/repositories/instanceRepository.ts): `backend/src/database/repositories/instanceRepository.ts`

### Provisioning and operations

- [VM provisioning](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/workflows/provision.ts): `backend/src/workflows/provision.ts`
- [Hetzner Cloud](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/providers/hetzner.js): `backend/src/providers/hetzner.js`
- [Warm VM pool](https://github.com/jdhubbard777/agentus.app/blob/main/backend/src/warmPool/warmPoolManager.ts): `backend/src/warmPool/warmPoolManager.ts`

### Other components

- **Customer**

## Connections

- Customer → Dashboard routes: uses
- Dashboard routes → Session and user state: checks session (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Specialist workspace: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Workflow builder: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Run history: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → Administration: routes to (evidence: `frontend/src/App.tsx`)
- Dashboard routes → HTTP and scheduled entry: calls API
- HTTP and scheduled entry → Authentication: mounts (evidence: `backend/src/worker.ts`)
- HTTP and scheduled entry → Workflow endpoints: mounts (evidence: `backend/src/worker.ts`)
- HTTP and scheduled entry → Dispatcher endpoints: mounts (evidence: `backend/src/worker.ts`)
- HTTP and scheduled entry → Specialist endpoints: mounts (evidence: `backend/src/worker.ts`)
- HTTP and scheduled entry → Task run endpoints: mounts (evidence: `backend/src/worker.ts`)
- HTTP and scheduled entry → Token and role checks: applies (evidence: `backend/src/worker.ts`)
- Customer → Interactive chat: chats with specialist
- Interactive chat → OpenClaw gateway: uses gateway
- Customer → Workflow builder: configures
- Workflow endpoints → Workflow and task records: persists workflows
- Customer → Workflow dispatcher: triggers work
- Workflow dispatcher → Direct model runtime: calls model API
- Workflow dispatcher → Slack, email, webhook: delivers output
- Workflow dispatcher → Workflow and task records: records runs and costs
- Task run endpoints → Workflow and task records: serves run records
- HTTP and scheduled entry → D1 query adapter: uses D1 access (evidence: `backend/src/worker.ts`)
- D1 query adapter → Cloudflare D1: queries (evidence: `backend/src/database/db.ts`)
- Workflow and task records → Cloudflare D1: stores records
- Instance records → Cloudflare D1: stores instances
- HTTP and scheduled entry → VM provisioning: starts provisioning
- VM provisioning → Hetzner Cloud: creates VMs
- VM provisioning → Instance records: tracks instances
- HTTP and scheduled entry → Warm VM pool: runs scheduled refill (evidence: `backend/src/worker.ts`)
- Warm VM pool → VM provisioning: requests capacity
- Administration → HTTP and scheduled entry: manages service