# bytebot-ai/bytebot architecture

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

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

## Overview

##### Project type and purpose
- Bytebot is a full-stack, containerized microservices application providing an AI-driven virtual desktop agent.
- Key business goal: let an AI “user” with its own Ubuntu/XFCE desktop environment complete tasks via natural-language instructions, exposed through both a Web UI and REST APIs.

##### File structure
- Top level:
– docker/ & helm/: Docker-Compose files (dev, proxy, core, desktop, Claude) and Kubernetes Helm charts for 5 services (agent, desktop, llm-proxy, ui, postgresql).
– packages/: monorepo of 6 packages:
· bytebot-ui (Next.js frontend & API proxy)
· bytebot-agent & bytebot-agent-cc (NestJS task orchestrators with Prisma migrations)
· bytebot-llm-proxy (LiteLLM service for multi-provider support)
· bytebotd (headless desktop environment + computer-use & input-tracking APIs)
· shared (TypeScript types & utils)
- Each package includes a Dockerfile; NestJS services use Prisma + PostgreSQL; UI uses Next.js server.ts to proxy to NestJS; desktop uses Supervisor + VNC + API modules.

##### README for additional insights
- The “How It Works” section lists four integrated components: Virtual Desktop, AI Agent, Task Interface, REST APIs.
- Deployment options: Docker Compose for local dev, Helm for Kubernetes.
- Mentions ports: 9991 for task APIs, 9990 for desktop control.
- LLM integration via Anthropic, OpenAI, Google Gemini through the llm-proxy.

##### Detail
– Include the shared library as a dependency link between UI and agent code.
– Don’t omit the llm-proxy layer or the input-tracking/computer-use modules inside bytebotd.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        Browser["User Browser"]:::external
        UI["bytebot-ui:3000"]:::frontend
    end

    %% Business Logic Layer
    subgraph "Business Logic Layer"
        direction TB
        Agent["bytebot-agent:9991"]:::backend
        AgentCC["bytebot-agent-cc:9991"]:::backend
        Shared["shared (types & utils)"]:::external
    end

    %% Desktop Control Layer
    subgraph "Desktop Control Layer"
        direction TB
        Desktop["bytebotd:9990"]:::desktop
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        direction TB
        LLMProxy["bytebot-llm-proxy"]:::infra
        DB["PostgreSQL"]:::infra
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        ExternalLLM["LLM Providers"]:::external
        PasswordMgr["Password Managers"]:::external
        ExternalWeb["External Web Services"]:::external
    end

    %% Connections
    Browser -->|"HTTP/HTTPS"| UI
    Browser -->|~ WebSocket ~| Desktop
    UI -->|"REST @9991"| Agent
    UI -->|"REST @9991"| AgentCC
    UI -.->|"depends on"| Shared
    Agent -->|"Prisma ORM"| DB
    AgentCC -->|"Prisma ORM"| DB
    Agent -->|"HTTP @9990"| Desktop
    AgentCC -->|"HTTP @9990"| Desktop
    Agent -->|"HTTP"| LLMProxy
    AgentCC -->|"HTTP"| LLMProxy
    LLMProxy -->|"HTTP"| ExternalLLM
    Agent -->|"HTTP"| ExternalWeb
    AgentCC -->|"HTTP"| ExternalWeb

    %% Click Events
    click UI "https://github.com/bytebot-ai/bytebot/blob/main/packages/bytebot-ui/server.ts"
    click Agent "https://github.com/bytebot-ai/bytebot/tree/main/packages/bytebot-agent/src"
    click Agent "https://github.com/bytebot-ai/bytebot/blob/main/packages/bytebot-agent/prisma/schema.prisma"
    click AgentCC "https://github.com/bytebot-ai/bytebot/tree/main/packages/bytebot-agent-cc/src"
    click AgentCC "https://github.com/bytebot-ai/bytebot/blob/main/packages/bytebot-agent-cc/prisma/schema.prisma"
    click Desktop "https://github.com/bytebot-ai/bytebot/tree/main/packages/bytebotd/src/computer-use"
    click Desktop "https://github.com/bytebot-ai/bytebot/tree/main/packages/bytebotd/src/input-tracking"
    click LLMProxy "https://github.com/bytebot-ai/bytebot/blob/main/packages/bytebot-llm-proxy/litellm-config.yaml"
    click Shared "https://github.com/bytebot-ai/bytebot/tree/main/packages/shared/src/types"
    click DB "https://github.com/bytebot-ai/bytebot/tree/main/helm/charts/postgresql"

    %% Styles
    classDef frontend fill:#cfe2ff,stroke:#084298,color:#084298
    classDef backend fill:#d1e7dd,stroke:#0f5132,color:#0f5132
    classDef desktop fill:#fff3cd,stroke:#664d03,color:#664d03
    classDef infra fill:#f8d7da,stroke:#842029,color:#842029
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d
```
