# arcadeai/arcade-ai architecture

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

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

## Overview

##### Project Type and Purpose
- The project is an SDK and developer platform for building, deploying, and managing “tools” that AI agents can use. It provides a CLI for tool creation and deployment, along with libraries to integrate these tools into various agent frameworks (like LangChain, CrewAI, etc.). The project also hosts a collection of pre-built toolkits (e.g., GitHub, Google, Slack, etc.) and includes deployment integrations (with Docker, workflows, etc.).

##### Key Components

a. Developer/Client Interface:
- Arcade CLI: This is the point of entry for developers (commands like arcade login, arcade new, arcade chat, arcade deploy, etc.).

b. Core Functionality (under arcade/arcade/core):
- Core Library Components: Include modules for authentication, configuration management, command parsing, execution, schema management, tooling, telemetry, and error handling.
- These modules work together to provide the central logic for tool definition, invocation, and communication with agent frameworks.

c. CLI Components (under arcade/arcade/cli):
- They leverage core functionality to generate new toolkits, deploy workers, and interface with external APIs.

d. Worker/Deployment Architecture (under arcade/arcade/worker):
- This part includes components for managing and executing deployed tools. It has submodules for configuration (deployment settings), core worker functionality, and a FastAPI-based HTTP serving component.
- The worker components handle incoming tool execution requests (possibly from the Arcade Engine or command-line calls) and manage authentication flows.

e. SDK & Integration Layer (under arcade/arcade/sdk):
- Contains integrations and helper utilities (for example, annotations, authentication bindings, evaluation functions, and direct tool invocation).
- How this layer can be used to integrate with external client libraries (arcade-py, arcade-js, etc.) and agent frameworks.

f. Template/Toolkit Generation (under arcade/arcade/templates and toolkits/):
- The project has a templating mechanism to scaffold new toolkits – represent a component that takes CLI input and outputs a correctly structured toolkit (files under templates/{{toolkit_name}}).
- Additionally, show the various toolkits (GitHub, Google, LinkedIn, etc.) that reside under the toolkits directory as plug-and-play components.

g. CI/CD and Deployment:
- An area for the continuous integration/deployment pipelines. This encompasses GitHub Actions (workflows folder), Dockerfiles, and deployment scripts (in docker/ and Makefile).
- How the CI pipelines interact with both the codebase (tests, linting, etc.) and the deployment of worker instances.

h. External and Cloud Services:
- External services such as OAuth providers (for Arcade Auth API), LLM providers (via the extended LLM API), and third-party integrations.

##### Relationships and Interactions
- The CLI component issues commands (like toolkit creation, login, deploy) that travel through the Core and invoke appropriate actions.
- The Core interacts with the SDK integration layer and may forward tool execution commands to the Worker, which exposes a FastAPI interface.
- The Worker communicates with the Arcade Engine (or cloud infrastructure) via HTTP APIs.
- The authentication process flows from the Auth API (in core and in SDK) to external OAuth providers, sending back tokens that are used by CLI commands or the worker processes.

##### Architectural Patterns & Design Principles
- Modularity: The project is broken into clear modules (CLI, core library, SDK, worker, templates, toolkits) that can be developed, tested, and deployed independently.
- Extensibility: The templating system and multiple toolkit modules facilitate easy addition of new tools/services.
- Separation of Concerns: The CLI focuses on user interaction; the core modules handle business logic; the worker components manage deployment/execution; and the CI/CD pipelines handle build and integration.
- Inter-component Communication: Highlight RESTful interactions (in the worker’s FastAPI server) and command-line invocations (from the CLI).

- At the top, place “User/Developer” with the Arcade CLI.
- In the middle, show “Core Services” (Core, CLI, SDK, Templates/Toolkits) that handle tool creation, configuration, and integration.
- Command invocation from CLI to Core.
- Configuration management from Core to Worker.
- Credential and token retrieval from Auth API to External OAuth.
- Data flow from Worker to external APIs (LLM endpoints) and back.
- Internal modules (CLI, Core, Worker, SDK)
- Template/Scaffolding components (Toolkits)
- External integrations (OAuth, LLM services, CI/CD pipelines)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Developer Interface Layer
    subgraph "User/Developer Interface"
        CLI["Arcade CLI"]:::developer
        DOC["Documentation & Quickstart"]:::developer
    end

    %% Core Services Layer
    subgraph "Core Services"
        CORE["Core Library (arcade/arcade/core)"]:::core
        CLIComp["CLI Components (arcade/arcade/cli)"]:::core
        SDK["SDK & Integration Layer (arcade/arcade/sdk)"]:::core
        TEMPLATES["Template Generation (arcade/arcade/templates/{{ toolkit_name }})"]:::templates
        TOOLKITS["Pre-built Toolkits (toolkits/)"]:::templates
    end

    %% Worker/Deployment Layer
    subgraph "Worker/Deployment"
        WORKER_CORE["Worker Core (arcade/arcade/worker/core)"]:::worker
        WORKER_API["Worker FastAPI (arcade/arcade/worker/fastapi)"]:::worker
        WORKER_CONFIG["Worker Config (arcade/arcade/worker/config/deployment.py)"]:::worker
    end

    %% External Systems & CI/CD Layer
    subgraph "External Systems & CI/CD"
        OAUTH["OAuth Providers"]:::external
        LLM["LLM Services"]:::external
        CICD["CI/CD Pipelines (.github/workflows)"]:::external
        DEPLOY["Deployment Scripts (docker/, Makefile)"]:::external
    end

    %% Relationships and Interactions
    CLI -->|"executeCommands"| CLIComp
    DOC -->|"guideUsage"| CLI
    CLIComp -->|"processCommands"| CORE
    CORE -->|"utilizeIntegrations"| SDK
    CORE -->|"scaffoldTools"| TEMPLATES
    TEMPLATES -->|"integrateToolkits"| TOOLKITS
    CORE -->|"triggerDeployment"| WORKER_CORE
    SDK -->|"authenticateVia"| OAUTH
    SDK -->|"invokeLLM"| LLM
    WORKER_CORE -->|"executeTools"| WORKER_API
    WORKER_CORE -->|"loadConfig"| WORKER_CONFIG
    WORKER_API -->|"communicateHTTP"| LLM
    CICD -->|"runTestsDeployments"| CORE
    DEPLOY -->|"containerize"| WORKER_CORE
    CICD -->|"triggerWorkerDeployments"| WORKER_CORE

    %% Click Events
    click CLI "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/cli"
    click DOC "https://github.com/arcadeai/arcade-ai/blob/main/README.md"
    click CORE "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/core"
    click CLIComp "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/cli"
    click SDK "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/sdk"
    click TEMPLATES "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/templates/{{ toolkit_name }}"
    click TOOLKITS "https://github.com/arcadeai/arcade-ai/tree/main/toolkits/"
    click WORKER_CORE "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/worker/core"
    click WORKER_API "https://github.com/arcadeai/arcade-ai/tree/main/arcade/arcade/worker/fastapi"
    click WORKER_CONFIG "https://github.com/arcadeai/arcade-ai/blob/main/arcade/arcade/worker/config/deployment.py"
    click CICD "https://github.com/arcadeai/arcade-ai/tree/main/.github/workflows"
    click DEPLOY "https://github.com/arcadeai/arcade-ai/tree/main/docker/"

    %% Styles
    classDef developer fill:#f9c74f,stroke:#000,stroke-width:2px;
    classDef core fill:#90be6d,stroke:#000,stroke-width:2px;
    classDef templates fill:#f8961e,stroke:#000,stroke-width:2px;
    classDef worker fill:#f94144,stroke:#000,stroke-width:2px;
    classDef external fill:#577590,stroke:#000,stroke-width:2px;
```
