# ai-app/opendevin.opendevin architecture

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

- Interactive diagram: https://gitdiagram.com/ai-app/opendevin.opendevin
- Repository: https://github.com/ai-app/opendevin.opendevin

## Overview

##### Project Type and Purpose
- OpenDevin is an open-source project aiming to replicate and extend the capabilities of Devin, an autonomous AI software engineer. Its purpose is to combine AI (powered by various LLMs) with software engineering tools (a shell, code editor, browser, etc.) to automate complex engineering tasks.
- The README emphasizes that it is both a research and production-style tool (even if still in alpha) and covers both the frontend (React-based UI) and the backend (FastAPI/UVicorn services, agent server, sandboxed execution).

##### Analyzing the File Structure
- There are clear top-level directories for different system concerns:
- "frontend" – Contains a React-based UI implementation (components, hooks, services, state management, etc.) that includes tests, assets, and configuration files.
- "agenthub" – Hosts multiple implementations of “agents” (like MonologueAgent, SWE_agent, codeact_agent, planner_agent) which suggests a modular design where different agent versions are encapsulated in their own sub-modules.
- "opendevin" – This folder represents core system logic and likely the backbone of the autonomous operations. It includes subdirectories for actions, controllers, LLM integration, server endpoints (including authentication, session management), sandbox integration, logging, and exceptions.
- "containers" – Contains Docker-related setup and scripts for app, evaluation sandboxing, and isolated execution environments.
- "evaluation" – Provides scripts, notebooks, and regression test cases – important for measuring performance/accuracy across different test cases.
- There are additional configuration files (like Makefile, Dockerfiles, development configs, pre-commit hooks) which speak to a well-engineered CI/CD and linting/testing pipeline.

##### Key Elements and Architectural Patterns
- Components:
- Frontend Client (web interface built with React, communicating via HTTP/WebSocket)
- Backend API and Agent Server (likely built using FastAPI & Uvicorn; manages LLM calls, agent management, and orchestrates tasks)
- Agent Modules (implemented under agenthub and plural agent modules under opendevin that execute different tasks)
- Sandbox Environment (Dockerized environment under “containers” and “sandbox” that safely executes shell commands)
- Evaluation and Testing Routines (evaluation directory for both functional and regression tests)
- Relationships:
- The frontend interacts with the backend via defined service endpoints (chat services, file operations, authentication, session handling).
- The backend orchestrates multiple agents that perform actions such as code generation, file system edits, and possibly dynamic planning.
- The sandbox containers are triggered by the backend to safely run shell or bash commands in an isolated environment.
- There is a dependency on LLM backends (OpenAI, etc.) that are abstracted out and configured via environment variables.
- Architectural Patterns:
- Separation of concerns is evident (UI vs. backend vs. execution/sandbox).
- Modular design for extensibility in agent implementations.
- Containerization for execution safety.
- RESTful (or WebSocket) API design to decouple the UI and backend.
- CI/CD integration and automated testing pipelines (GitHub workflows, evaluation tests).

a. Main Components:
- UI Layer: Frontend client (React) with components such as ChatInterface, CodeEditor, Terminal, and Workspace.
- Application Server / API: The backend built in opendevin (FastAPI endpoints, controllers, session and authentication management).
- Agent Modules / Manager: Group of autonomous agent implementations located in the agenthub and opendevin folders.
- Sandbox / Execution Environment: Dockerized containers (containers/app, containers/sandbox, containers/evaluation) that execute commands securely.
- Evaluation and Testing Module: Evaluation scripts, regression tests, and notebooks that ensure proper agent performance.
- External LLM Services: Configurable API endpoints for the various LLM backends used.

b. Relationships and Interactions:
- How the Application Server delegates tasks to the Agent Modules.
- Application Server to external LLM services, indicating API calls made for LLM-driven processing.

c. Architectural Patterns and Technologies:
- Explicitly label technologies such as React in the UI layer, FastAPI and Uvicorn in the backend, Docker for sandboxing, and integration of LLMs (for example, via LiteLLM).
- Modular design for agents and dynamic sandbox execution safely isolated from the host system.

d. Use Visual Elements and Legends:
- Annotations for critical environment configurations – for instance, environment variables such as LLM_API_KEY passing from the system to external LLM integration.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        FR["React Frontend UI"]:::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        BA["Backend API (FastAPI & Uvicorn)"]:::backend
        CT["Controller & Session/Auth"]:::backend
        LLM["LLM Integration"]:::backend
    end

    %% Agent Modules
    subgraph "Agent Modules"
        AM["Agent Manager"]:::agent
        MA["MonologueAgent"]:::agent
        SWE["SWE Agent"]:::agent
        CA["CodeactAgent"]:::agent
        PA["PlannerAgent"]:::agent
    end

    %% Sandbox Environment
    subgraph "Sandbox Environment"
        SB["Sandbox (Backend)"]:::sandbox
        Docker["Sandbox (Docker)"]:::sandbox
    end

    %% Evaluation Module
    subgraph "Evaluation Module"
        EV["Evaluation & Testing"]:::evaluation
    end

    %% External Services
    subgraph "External Services"
        EXLLM["External LLM APIs"]:::external
    end

    %% Connections
    FR -->|"HTTP/WebSocket"| BA
    BA -->|"Delegates tasks"| AM
    BA -->|"Manages sessions"| CT
    BA -->|"LLM API calls"| LLM
    AM -->|"Executes task"| MA
    AM -->|"Executes task"| SWE
    AM -->|"Executes task"| CA
    AM -->|"Executes task"| PA
    BA -->|"Sandboxed execution"| SB
    BA -->|"Dockerized commands"| Docker
    BA -->|"LLM integration"| EXLLM
    EV -->|"Feedback loop"| BA

    %% Click Events
    click FR "https://github.com/ai-app/opendevin.opendevin/tree/main/frontend/"
    click BA "https://github.com/ai-app/opendevin.opendevin/blob/main/opendevin/main.py"
    click LLM "https://github.com/ai-app/opendevin.opendevin/blob/main/opendevin/llm/llm.py"
    click MA "https://github.com/ai-app/opendevin.opendevin/tree/main/agenthub/monologue_agent"
    click SWE "https://github.com/ai-app/opendevin.opendevin/tree/main/agenthub/SWE_agent"
    click CA "https://github.com/ai-app/opendevin.opendevin/tree/main/agenthub/codeact_agent"
    click PA "https://github.com/ai-app/opendevin.opendevin/tree/main/agenthub/planner_agent"
    click SB "https://github.com/ai-app/opendevin.opendevin/tree/main/opendevin/sandbox/"
    click Docker "https://github.com/ai-app/opendevin.opendevin/tree/main/containers/sandbox/"
    click EV "https://github.com/ai-app/opendevin.opendevin/tree/main/evaluation/"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#0000FF,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#008000,stroke-width:2px;
    classDef agent fill:#FFFACD,stroke:#DAA520,stroke-width:2px;
    classDef sandbox fill:#FFC0CB,stroke:#FF69B4,stroke-width:2px;
    classDef evaluation fill:#D3D3D3,stroke:#A9A9A9,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#9370DB,stroke-width:2px;
```
