# oraichain/openhands architecture

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

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

## Overview

- Frontend/UI: Represented by the “frontend” directory. This is the web client (built with React/TypeScript) that users interact with. It handles authentication, chat interfaces, GitHub connectivity, file explorer, settings, and various interactive features.
- Core Agent & Controller Modules: Group the “openhands/agenthub”, “openhands/controller”, “openhands/core”, “openhands/llm”, “openhands/microagent”, and “openhands/events”. These modules form the AI agent logic and orchestration layer. They are responsible for parsing user input, dispatching actions to agents, managing the multiagent workflows, and handling agent feedback or observations.
- Storage & Memory: Represent modules like “openhands/storage” and “openhands/memory” where conversation history, session data, and file states are stored.

- Backend to the Agent/Controller modules. Illustrate requests for code execution, messaging, and agent coordination.
- Storage component as a separate module that is consumed by the Backend and Agent layers for persisting conversations, file edits, and configuration/state information.

##### Architectural Patterns and Design Principles
- Modularity—the system is broken down into distinct modules (agent logic, integration, runtime, storage) that communicate through well-defined APIs.
- Containerization and deployment abstraction (Docker, Kubernetes flags, runtime builders, and isolated execution environments).
- Separation of concerns between user interface, API server logic, agent decision making, execution, and testing.

##### Technologies and Frameworks to Note
- Frontend: React/TypeScript (from the “frontend” directory, with tests, React components, hooks).
- Backend: Python-based modules running the OpenHands server (likely using a lightweight framework, with REST and WebSocket endpoints).
- Docker: Multiple container definitions and Dockerfiles (in “containers” and “docker-compose.yml”) represent the deployment and runtime environments.
- Testing Frameworks: A rich set of unit, integration, and regression tests (files under “tests” and “evaluation”), ensuring reliability.
- Integration with external code hosting and AI models (GitHub/Latte integrations, Anthropic API keys, etc.).

## Diagram (Mermaid)

```mermaid
graph TD
    F["Frontend/UI"]:::frontend
    BS["Backend/API Server"]:::backend

    subgraph "Agent Platform"
        AH["Agent Hub"]:::agent
        CTRL["Controller"]:::agent
        CORE["Core"]:::agent
        LLM["LLM"]:::agent
        MICRO["Microagent"]:::agent
        EVTS["Events"]:::agent
    end

    RT["Runtime Environment"]:::runtime
    CONT["Container Configurations"]:::config
    INTG["Integrations & External Services"]:::integration

    subgraph "Data Layer"
        STORE["Storage"]:::storage
        MEM["Memory"]:::storage
    end

    EVAL["Evaluation/Testing Suite"]:::evaluation

    %% Connections
    F -->|"UserRequests_APIcalls_WebSocketEvents"| BS
    BS -->|"DispatchAgentCommands"| AH
    AH -->|"InternalCommunication"| CTRL
    CTRL -->|"ProcessingLogic"| CORE
    CORE -->|"LLMInteraction"| LLM
    LLM -->|"AgentCoordination"| MICRO
    MICRO -->|"EventHandling"| EVTS

    AH -->|"ExecutionCommands"| RT
    RT -->|"FeedbackResults"| AH

    INTG -->|"ProvideData"| BS
    INTG -->|"ProvideData"| AH

    BS -->|"PersistData"| STORE
    AH -->|"CacheData"| MEM

    CONT -->|"Orchestration"| RT

    EVAL -->|"TestAPIs"| BS
    EVAL -->|"TestRuntime"| RT

    %% Click Events
    click F "https://github.com/oraichain/openhands/tree/main/frontend"
    click BS "https://github.com/oraichain/openhands/tree/main/openhands/server"
    click AH "https://github.com/oraichain/openhands/tree/main/openhands/agenthub"
    click CTRL "https://github.com/oraichain/openhands/tree/main/openhands/controller"
    click CORE "https://github.com/oraichain/openhands/tree/main/openhands/core"
    click LLM "https://github.com/oraichain/openhands/tree/main/openhands/llm"
    click MICRO "https://github.com/oraichain/openhands/tree/main/openhands/microagent"
    click EVTS "https://github.com/oraichain/openhands/tree/main/openhands/events"
    click RT "https://github.com/oraichain/openhands/tree/main/openhands/runtime"
    click CONT "https://github.com/oraichain/openhands/tree/main/containers/runtime"
    click INTG "https://github.com/oraichain/openhands/tree/main/openhands/integrations"
    click STORE "https://github.com/oraichain/openhands/tree/main/openhands/storage"
    click MEM "https://github.com/oraichain/openhands/tree/main/openhands/memory"
    click CONT "https://github.com/oraichain/openhands/tree/main/containers"
    click EVAL "https://github.com/oraichain/openhands/tree/main/evaluation"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef backend fill:#FAD7A0,stroke:#9A7D0A,stroke-width:2px;
    classDef agent fill:#ABEBC6,stroke:#186A3B,stroke-width:2px;
    classDef runtime fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef integration fill:#F5CBA7,stroke:#A04000,stroke-width:2px;
    classDef storage fill:#D2B4DE,stroke:#6C3483,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#1F618D,stroke-width:2px;
    classDef evaluation fill:#FADBD8,stroke:#943126,stroke-width:2px;
```
