# arafa1974/openhands architecture

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

- Interactive diagram: https://gitdiagram.com/arafa1974/openhands
- Repository: https://github.com/arafa1974/openhands

## Overview

Agent Canvas is a self-hosted developer control center for running coding agents and automations across local, remote, and cloud backends. A user selects a backend, starts or resumes a conversation, and works with agent events, files, browser, and terminal views; automations provide a separate scheduled or webhook-triggered workflow. The graph also includes model profiles, cloud services, and extensions as major product capabilities. Source excerpts establish backend selection and conversation-history access; several UI and automation links are documented capabilities, so their implementation relationships are left unasserted.

Main entry points: [`src/components/features/chat/chat-interface.tsx`](https://github.com/arafa1974/openhands/blob/main/src/components/features/chat/chat-interface.tsx) (Conversation workspace), [`src/hooks/query/conversation-history-query-options.ts`](https://github.com/arafa1974/openhands/blob/main/src/hooks/query/conversation-history-query-options.ts) (Conversation history), [`src/api/backend-registry/active-store.ts`](https://github.com/arafa1974/openhands/blob/main/src/api/backend-registry/active-store.ts) (Active backend registry), [`src/api/agent-server-client-options.ts`](https://github.com/arafa1974/openhands/blob/main/src/api/agent-server-client-options.ts) (Agent client options)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend access"]
  node_backend_ui["Backend controls"]
  node_backend_registry["Active backend registry<br/>[active-store.ts]"]
  node_backend_storage[("Backend persistence<br/>[storage.ts]")]
  node_agent_options["Agent client options"]
  node_agent_server["Agent server"]
end

subgraph group_conversation["Agent conversations"]
  node_chat_ui["Conversation workspace<br/>[chat-interface.tsx]"]
  node_conversation_api["Conversation service"]
  node_history_query["Conversation history"]
  node_event_service["Event service"]
  node_event_views["Agent event views<br/>[messages.tsx]"]
  node_conversation_state[("Conversation preferences")]
end

subgraph group_automation["Automations"]
  node_automations_ui["Automation workflows"]
  node_automation_api["Automation service"]
  node_automation_integrations["Workflow integrations"]
end

subgraph group_platform["Product platform"]
  node_profiles_ui["Model profiles"]
  node_profiles_api["Profiles service"]
  node_cloud_services["Cloud services<br/>[client.ts]"]
  node_extensions["Canvas extensions"]
  node_ui_library["Embeddable UI<br/>[index.ts]"]
end

node_developer(("Developer"))

node_developer -.->|"chooses backend"| node_backend_ui
node_backend_registry -->|"reads and writes"| node_backend_storage
node_backend_registry -->|"resolves backend"| node_agent_options
node_agent_options -.->|"configures requests"| node_agent_server
node_developer -.->|"starts conversation"| node_chat_ui
node_chat_ui -.->|"manages conversations"| node_conversation_api
node_conversation_api -.->|"sends agent requests"| node_agent_server
node_history_query -->|"loads history"| node_event_service
node_event_service -.->|"requests events"| node_agent_server
node_chat_ui -.->|"queries history"| node_history_query
node_chat_ui -.->|"persists preferences"| node_conversation_state
node_history_query -.->|"provides event history"| node_event_views
node_developer -.->|"creates workflows"| node_automations_ui
node_automations_ui -.->|"manages automations"| node_automation_api
node_automation_api -.->|"uses integrations"| node_automation_integrations
node_developer -.->|"configures models"| node_profiles_ui
node_profiles_ui -->|"loads and saves"| node_profiles_api
node_developer -.->|"connects cloud"| node_cloud_services
node_developer -.->|"adds extensions"| node_extensions
node_ui_library -.->|"exposes UI components"| node_developer

click node_backend_ui "https://github.com/arafa1974/openhands/blob/main/src/components/features/backends/backend-selector.tsx"
click node_backend_registry "https://github.com/arafa1974/openhands/blob/main/src/api/backend-registry/active-store.ts"
click node_backend_storage "https://github.com/arafa1974/openhands/blob/main/src/api/backend-registry/storage.ts"
click node_agent_options "https://github.com/arafa1974/openhands/blob/main/src/api/agent-server-client-options.ts"
click node_chat_ui "https://github.com/arafa1974/openhands/blob/main/src/components/features/chat/chat-interface.tsx"
click node_conversation_api "https://github.com/arafa1974/openhands/blob/main/src/api/conversation-service/agent-server-conversation-service.api.ts"
click node_history_query "https://github.com/arafa1974/openhands/blob/main/src/hooks/query/conversation-history-query-options.ts"
click node_event_service "https://github.com/arafa1974/openhands/blob/main/src/api/event-service/event-service.api.ts"
click node_event_views "https://github.com/arafa1974/openhands/blob/main/src/components/conversation-events/chat/messages.tsx"
click node_conversation_state "https://github.com/arafa1974/openhands/blob/main/src/utils/conversation-local-storage.ts"
click node_automations_ui "https://github.com/arafa1974/openhands/blob/main/src/components/features/automations/automation-card.tsx"
click node_automation_api "https://github.com/arafa1974/openhands/blob/main/src/api/automation-service/automation-service.api.ts"
click node_automation_integrations "https://github.com/arafa1974/openhands/blob/main/src/api/automation-setup-plugins.ts"
click node_profiles_ui "https://github.com/arafa1974/openhands/blob/main/src/components/features/settings/llm-profiles/llm-profiles-manager.tsx"
click node_profiles_api "https://github.com/arafa1974/openhands/blob/main/src/api/profiles-service/profiles-service.api.ts"
click node_cloud_services "https://github.com/arafa1974/openhands/blob/main/src/api/cloud/client.ts"
click node_extensions "https://github.com/arafa1974/openhands/blob/main/src/api/canvas-extensions-service.ts"
click node_ui_library "https://github.com/arafa1974/openhands/blob/main/src/lib/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_backend_ui,node_backend_registry,node_backend_storage,node_agent_options,node_agent_server toneBlue
class node_chat_ui,node_conversation_api,node_history_query,node_event_service,node_event_views,node_conversation_state toneAmber
class node_automations_ui,node_automation_api,node_automation_integrations toneMint
class node_profiles_ui,node_profiles_api,node_cloud_services,node_extensions,node_ui_library toneRose
class node_developer toneIndigo
```

## Components

### Backend access

- [Backend controls](https://github.com/arafa1974/openhands/blob/main/src/components/features/backends/backend-selector.tsx): `src/components/features/backends/backend-selector.tsx`
- [Active backend registry](https://github.com/arafa1974/openhands/blob/main/src/api/backend-registry/active-store.ts): `src/api/backend-registry/active-store.ts`
- [Backend persistence](https://github.com/arafa1974/openhands/blob/main/src/api/backend-registry/storage.ts): `src/api/backend-registry/storage.ts`
- [Agent client options](https://github.com/arafa1974/openhands/blob/main/src/api/agent-server-client-options.ts): `src/api/agent-server-client-options.ts`
- **Agent server**

### Agent conversations

- [Conversation workspace](https://github.com/arafa1974/openhands/blob/main/src/components/features/chat/chat-interface.tsx): `src/components/features/chat/chat-interface.tsx`
- [Conversation service](https://github.com/arafa1974/openhands/blob/main/src/api/conversation-service/agent-server-conversation-service.api.ts): `src/api/conversation-service/agent-server-conversation-service.api.ts`
- [Conversation history](https://github.com/arafa1974/openhands/blob/main/src/hooks/query/conversation-history-query-options.ts): `src/hooks/query/conversation-history-query-options.ts`
- [Event service](https://github.com/arafa1974/openhands/blob/main/src/api/event-service/event-service.api.ts): `src/api/event-service/event-service.api.ts`
- [Agent event views](https://github.com/arafa1974/openhands/blob/main/src/components/conversation-events/chat/messages.tsx): `src/components/conversation-events/chat/messages.tsx`
- [Conversation preferences](https://github.com/arafa1974/openhands/blob/main/src/utils/conversation-local-storage.ts): `src/utils/conversation-local-storage.ts`

### Automations

- [Automation workflows](https://github.com/arafa1974/openhands/blob/main/src/components/features/automations/automation-card.tsx): `src/components/features/automations/automation-card.tsx`
- [Automation service](https://github.com/arafa1974/openhands/blob/main/src/api/automation-service/automation-service.api.ts): `src/api/automation-service/automation-service.api.ts`
- [Workflow integrations](https://github.com/arafa1974/openhands/blob/main/src/api/automation-setup-plugins.ts): `src/api/automation-setup-plugins.ts`

### Product platform

- [Model profiles](https://github.com/arafa1974/openhands/blob/main/src/components/features/settings/llm-profiles/llm-profiles-manager.tsx): `src/components/features/settings/llm-profiles/llm-profiles-manager.tsx`
- [Profiles service](https://github.com/arafa1974/openhands/blob/main/src/api/profiles-service/profiles-service.api.ts): `src/api/profiles-service/profiles-service.api.ts`
- [Cloud services](https://github.com/arafa1974/openhands/blob/main/src/api/cloud/client.ts): `src/api/cloud/client.ts`
- [Canvas extensions](https://github.com/arafa1974/openhands/blob/main/src/api/canvas-extensions-service.ts): `src/api/canvas-extensions-service.ts`
- [Embeddable UI](https://github.com/arafa1974/openhands/blob/main/src/lib/index.ts): `src/lib/index.ts`

### Other components

- **Developer**

## Connections

- Developer → Backend controls: chooses backend (evidence: `README.md`)
- Active backend registry → Backend persistence: reads and writes (evidence: `src/api/backend-registry/active-store.ts`)
- Active backend registry → Agent client options: resolves backend (evidence: `src/api/agent-server-client-options.ts`)
- Agent client options → Agent server: configures requests
- Developer → Conversation workspace: starts conversation (evidence: `README.md`)
- Conversation workspace → Conversation service: manages conversations
- Conversation service → Agent server: sends agent requests
- Conversation history → Event service: loads history (evidence: `src/hooks/query/conversation-history-query-options.ts`)
- Event service → Agent server: requests events
- Conversation workspace → Conversation history: queries history
- Conversation workspace → Conversation preferences: persists preferences
- Conversation history → Agent event views: provides event history
- Developer → Automation workflows: creates workflows (evidence: `README.md`)
- Automation workflows → Automation service: manages automations
- Automation service → Workflow integrations: uses integrations
- Developer → Model profiles: configures models (evidence: `README.md`)
- Model profiles → Profiles service: loads and saves (evidence: `src/components/features/settings/llm-profiles/llm-profiles-manager.tsx`)
- Developer → Cloud services: connects cloud (evidence: `README.md`)
- Developer → Canvas extensions: adds extensions
- Embeddable UI → Developer: exposes UI components
