# pradeepvish1213/openhands architecture

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

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

## Overview

Based on our review of the file tree and README content, OpenHands is a full-stack AI-driven development agent platform. Its purpose is to provide a system that can “code less, make more” by automating software development tasks via a suite of agents that interact with source code, run commands, browse the web, and integrate with external systems like GitHub/GitLab. The system is designed to work as a single-user local workstation application with containers, microagents, and multiple integration points.

##### Main Components
- Frontend: The “frontend” folder houses all client-side code, tests, assets, and routing. It provides the web UI (React-based) where the user interacts with the system.
- Backend and Server: The “openhands” directory contains key modules such as the server (app, auth, routes, session, conversation management) and core logic (agent hubs, controllers, event streaming). Also, subfolders like “controller,” “agenthub,” “runtime,” “integrations,” and “storage” show a clear separation of concerns for agent orchestration, LLM integration, and system control.
- Microagents: The “microagents” folder represents smaller agent tasks and knowledge bases that the system uses to perform specialized operations.
- Runtime Environment & Containers: The “containers” directory offers Dockerfiles and related scripts that manage various runtime environments (app, dev, sandbox, etc.). The “openhands/runtime” submodule contains implementations for different runtime scenarios—local, modal, Docker-based, etc.
- Evaluation and Testing: The “evaluation” folder (with its many benchmark subdirectories, integration tests, regression tests, etc.) and the “tests” folders capture how the system is exercised, ensuring functionality of components like browsing, file operations, and agent interactions.
- Integrations and External Services: There are dedicated subdirectories for integrations (e.g., GitHub, GitLab), indicating external API communications. Additionally, connectors for various LLM providers (Anthropic, etc.) are present.
- Documentation & Configurations: The “docs” folder and various configuration files (like config.template.toml and development scripts) show support for deployment, debug, and documentation.

##### Relationships and Data/Control Flows
- User Interaction Flow:
- The user interacts with the Frontend (web UI), which calls REST/WS endpoints provided by the Backend.
- Frontend communicates via APIs (found in axios modules, service layers) with server components that handle authentication, conversation state management, and file operations.
- Backend and Agent Coordination:
- The core of the backend (in “openhands”) routes incoming commands to the agent hub and controller.
- The Agent Hub orchestrates various specialized agents (codeact, browsing, dummy agent, visualbrowsing) that interact with external systems.
- Agents then interact with a runtime environment (using implementations found in “openhands/runtime”) which can be dynamically built and executed via Docker containers or local execution modules.
- Integration and External Communication:
- Components under “integrations” and “resolver” catch and manage interactions with GitHub/GitLab, converting agent input/output for code changes, pull requests, or issue handling.
- Persistence and Storage:
- The “storage” module manages conversation and file storage (using local filesystem, S3 or memory implementations) while “server/session” deals with session persistence.

##### Architectural Patterns and Design Principles
- Modular design: The project clearly separates agent logic, controller logic, UI, runtime, and integrations.
- Containerization: Use of Dockerfiles and container scripts indicates a containerized runtime environment.
- Event-driven communication: Components in “events” suggest the system employs event-streaming architectures, with directional data flows between modules (actions and observations).
- Clear separation of concerns: Frontend versus Backend, microagents versus core agents, and integration of LLM modules, demonstrates layered and decoupled architecture.

##### Elements
- Frontend/User Interface
- Backend/API Server
- Agent Hub / Controller
- Microagents / Specialized Agents
- Runtime Environment (with sub-components for Docker, local, remote runtimes)
- Integrations (GitHub/GitLab, LLM Providers)
- Storage / Persistence Layer
- Evaluation/Testing (optional for overview)
- Data/control flow between the UI and backend.
- Interactions between the backend, agent hub, and runtime systems.
- How integrations feed data into the system.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Layer
    FE("Frontend/User Interface"):::frontend

    %% Backend Layer
    BE("Backend/API Server & Core Logic"):::backend

    %% Agent Coordination Subgraph
    subgraph "Agent Coordination"
        A1("Agent Hub"):::agents
        A2("Controller"):::agents
    end

    %% Microagents and Integrations
    M("Microagents/Specialized Agents"):::agents
    I("Integrations & External Services"):::agents

    %% Runtime Environment Subgraph
    subgraph "Runtime Environment"
        R1("Containers"):::runtime
        R2("Runtime Implementations"):::runtime
        R1 -->|"initializes"| R2
    end

    %% Storage / Persistence Subgraph
    subgraph "Storage/Persistence"
        S1("Storage"):::storage
        S2("Session Management"):::storage
        S1 --> S2
    end

    %% Quality Assurance Subgraph
    subgraph "Quality Assurance"
        Q1("Evaluation"):::testing
        Q2("Tests"):::testing
        Q1 -->|"ensures"| Q2
    end

    %% Documentation & Configurations Subgraph
    subgraph "Documentation & Configurations"
        D1("Documentation"):::docs
        D2("Configurations"):::docs
        D1 -->|"references"| D2
    end

    %% Connections
    FE -->|"HTTP/REST,WS"| BE

    BE -->|"routes commands"| A1
    A1 -->|"orchestrates"| M
    A1 -->|"communicates"| I
    A2 -->|"executes"| R1

    BE -->|"manages"| S1
    BE -->|"monitors"| Q1
    BE -->|"supports"| D1

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef backend fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef agents fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef runtime fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef storage fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
    classDef testing fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef docs fill:#e2d5f5,stroke:#6f42c1,stroke-width:2px;

    %% Click Events
    click FE "https://github.com/pradeepvish1213/openhands/tree/main/frontend"
    click BE "https://github.com/pradeepvish1213/openhands/tree/main/openhands"
    click A1 "https://github.com/pradeepvish1213/openhands/tree/main/openhands/agenthub"
    click A2 "https://github.com/pradeepvish1213/openhands/tree/main/openhands/controller"
    click M "https://github.com/pradeepvish1213/openhands/tree/main/microagents"
    click I "https://github.com/pradeepvish1213/openhands/tree/main/openhands/integrations"
    click R1 "https://github.com/pradeepvish1213/openhands/tree/main/containers"
    click R2 "https://github.com/pradeepvish1213/openhands/tree/main/openhands/runtime"
    click S1 "https://github.com/pradeepvish1213/openhands/tree/main/openhands/storage"
    click S2 "https://github.com/pradeepvish1213/openhands/tree/main/openhands/server/session"
    click Q1 "https://github.com/pradeepvish1213/openhands/tree/main/evaluation"
    click Q2 "https://github.com/pradeepvish1213/openhands/tree/main/tests"
    click D1 "https://github.com/pradeepvish1213/openhands/tree/main/docs"
    click D2 "https://github.com/pradeepvish1213/openhands/blob/main/config.template.toml"
```
