# openagentsinc/openagents architecture

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

- Interactive diagram: https://gitdiagram.com/openagentsinc/openagents
- Repository: https://github.com/openagentsinc/openagents

## Overview

Based on our analysis of both the file tree and the README, the project is clearly a cross‐platform monorepo for an AI Agents platform (OpenAgents) that supports several client types. The key purpose is to enable a collaborative agentic chat experience using open protocols, with distinct applications for web (chatserver and coder for desktop) and mobile (onyx for chat and bitcoin wallet functionality), plus various shared libraries that define the agents and core business logic.

##### Main Components
- Apps (Client Applications):
- Chatserver: This is the backend AI SDK chat API service.
- Coder: The desktop application (a drop-in replacement for a previous tool) built using React and TypeScript, featuring chat UI, thread history, and MCP integration.
- MCP GitHub Server: A remote server that provides GitHub tools and MCP integration.
- Onyx: The mobile app that not only provides chat functionality but also acts as a Bitcoin wallet.
- Shared Packages:
- Agents: Contains definitions and reusable agent logic.
- Core: Provides shared core logic, utility functions, and integration with MCP (message control protocol) components.
- UI: Contains reusable UI components for chat, buttons, cards, toasts, and other visual elements.
- Documentation: Although not part of runtime architecture, the docs folder gives insight into integration, troubleshooting, and design considerations.
- External Services & Integrations:
- Cloudflare stack for the backend (including Durable Objects for the Agents).
- Auth (with better-auth).
- Vercel AI SDK for additional AI integrations.
- External wallets (Breez SDK, Spark wallet) for Bitcoin/Lightning network operations.
- Open protocols integration (MCP, Nostr network) for interoperability.

##### Relationships and Interactions
- Client Applications (coder, onyx) interface with:
- The shared packages (agents, core, ui) to render consistent UIs and reuse business logic.
- The backend services such as the Chatserver API and MCP GitHub server.
- Chatserver and MCP GitHub server are backend services that handle API requests, agent interactions, and MCP integrations.
- Agents run as long-lived processes (for instance, on Cloudflare’s Durable Objects) and communicate with both the backend services and client applications.
- There is an interoperability link between chat clients (e.g., coder, onyx) and external protocols (MCP and Nostr) that enables actions like chat-based commands and integration with GitHub workflows.
- The shared core logic is used across both client and server components to standardize communication, command parsing/execution, error handling, and more.

##### Important Architectural Patterns and Design Principles
- Monorepo Structure: Emphasizes code reuse across diverse client implementations and servers.
- Separation of Concerns: Each app (chatserver, coder, mcp-github-server, onyx) has clearly delineated responsibilities (backend API vs. frontend UI vs. mobile wallet).
- Reusable Shared Libraries: Agent definitions, core logic, and UI components are built as separate packages to be consumed by multiple applications.
- Cross-Platform Development: Use of React/React Native and TypeScript to ensure consistency across desktop, mobile, and web.
- Integration with External Protocols: MCP, Nostr, and external wallet integrations that define the data flow between internal components and third-party services.
- Cloudflare Backend Architecture: Utilization of Cloudflare’s capabilities (including Durable Objects) for running long-lived agent processes.

##### Relevant Technologies and Frameworks
- Frontend: React, React Native, TypeScript.
- Backend: Cloudflare (Durable Objects, wrangler configuration), Node (for chatserver and MCP GitHub server).
- Testing: Jest, Playwright, Vitest (as indicated by the test configurations found in the apps).
- Build & Config: Vite and TypeScript configuration files across the apps and packages.
- Wallet/Payment Integration: Breez SDK (for onyx) and considerations for Spark wallet integration.
- Other: Better-auth for authentication, and integration with Vercel AI SDK.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Applications
    subgraph "Frontend Applications"
        Coder["Coder (Desktop App)"]:::frontend
        Onyx["Onyx (Mobile App)"]:::frontend
    end

    %% Shared Packages
    subgraph "Shared Packages"
        Agents["Agents"]:::shared
        Core["Core"]:::shared
        UI["UI"]:::shared
    end

    %% Backend Services
    subgraph "Backend Services"
        Chatserver["Chatserver (Backend API)"]:::backend
        MCP_GitHub_Server["MCP GitHub Server"]:::backend
    end

    %% External Integrations
    subgraph "External Integrations"
        Cloudflare["Cloudflare (Durable Objects)"]:::external
        Auth["Auth (better-auth)"]:::external
        Vercel["Vercel AI SDK"]:::external
        Wallets["Wallet Integrations (Breez SDK, Spark)"]:::external
        OpenProtocols["Open Protocols (MCP, Nostr)"]:::external
        GitHubTools["GitHub Tools"]:::external
    end

    %% Documentation
    Docs["Documentation"]:::docs

    %% Relationships from Frontend to Shared Packages
    Coder -->|"uses"| Core
    Coder -->|"renders"| UI
    Onyx -->|"uses"| Core
    Onyx -->|"renders"| UI

    %% Relationships from Frontend to Backend Services
    Coder -->|"calls"| Chatserver
    Coder -->|"integrates"| MCP_GitHub_Server
    Onyx -->|"calls"| Chatserver
    Onyx -->|"integrates"| MCP_GitHub_Server

    %% Relationships from Backend Services to Shared Packages
    Chatserver -->|"executes"| Agents
    Chatserver -->|"utilizes"| Core
    MCP_GitHub_Server -->|"executes"| Agents
    MCP_GitHub_Server -->|"utilizes"| Core

    %% Relationships connecting Shared Packages and External Integration
    Agents <-->|"hosted on"| Cloudflare

    %% External Integration connections to Backend
    Chatserver -->|"integrates"| OpenProtocols
    Chatserver -->|"leverages"| Vercel
    Chatserver -->|"authenticates"| Auth
    MCP_GitHub_Server -->|"integrates"| GitHubTools
    MCP_GitHub_Server -->|"authenticates"| Auth

    %% External Integration connection to Frontend
    Onyx -->|"wallet operations"| Wallets

    %% Documentation note (informational)
    Docs ---|"details integration & design"| Core

    %% Click Events
    click Chatserver "https://github.com/openagentsinc/openagents/tree/main/apps/chatserver"
    click Coder "https://github.com/openagentsinc/openagents/tree/main/apps/coder"
    click MCP_GitHub_Server "https://github.com/openagentsinc/openagents/tree/main/apps/mcp-github-server"
    click Onyx "https://github.com/openagentsinc/openagents/tree/main/apps/onyx"
    click Agents "https://github.com/openagentsinc/openagents/tree/main/packages/agents"
    click Core "https://github.com/openagentsinc/openagents/tree/main/packages/core"
    click UI "https://github.com/openagentsinc/openagents/tree/main/packages/ui"
    click Docs "https://github.com/openagentsinc/openagents/tree/main/docs"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px
    classDef shared fill:#FFD700,stroke:#000,stroke-width:2px
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px
    classDef docs fill:#D3D3D3,stroke:#000,stroke-width:2px
```
