# fellouai/eko architecture

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

- Interactive diagram: https://gitdiagram.com/fellouai/eko
- Repository: https://github.com/fellouai/eko

## Overview

##### Project type and purpose
- Eko is a production-ready JavaScript/TypeScript framework for building and executing multi-step agentic workflows via natural language.
- It exposes a unified API (`Eko.generate` & `Eko.execute`) and runs on three runtimes: Browser Extension, Web applications, and Node.js.

##### File structure
- **src/common**: shared logic (e.g. workflow summarization).
- **src/core**: engine entrypoint (`eko.ts`), tool registry.
- **src/services**:
- **llm** (Claude/OpenAI providers + factory)
- **parser** (DSL → Workflow models)
- **workflow** (generator + templates)
- **src/models**, **src/schemas**, **src/types**: domain definitions (Action, Workflow, schemas).
- **Platform adapters**:
- **src/extension/**: browser extension code (content script, tools, message handlers).
- **src/web/**: browser-based SDK (DOM access, web tools).
- **src/nodejs/**: Node.js SDK (FS, process tools).
- **docs/designs**: DSL and node type specifications.
- Rollup, Jest, CI configs, package.json.

##### Insights from README
- Core features: one-sentence to multi-step workflows, intervenability, cross-platform support.
- Use cases: browser automation, file system management, GUI tasks, data processing.
- Environments: Browser Extension, Web, Node.js.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% API Layer
    subgraph "API Layer"
        EkoSDK["Eko SDK\n(Eko.generate & Eko.execute)"]:::core
    end

    %% Core Engine
    subgraph "Core Engine" 
        Parser["Workflow Parser\n(src/services/parser)"]:::core
        Generator["Workflow Generator\n(src/services/workflow)"]:::core
        Executor["Workflow Executor\n(execute logic)"]:::core
        ToolRegistry["Tool Registry"]:::core
    end

    %% Services Layer
    subgraph "Services" 
        LLMFactory["LLM Provider Factory"]:::service
        OpenAI["OpenAI Provider"]:::service
        Claude["Claude Provider"]:::service
        Templates["Workflow Templates"]:::service
    end

    %% Common Utilities
    subgraph "Common Utilities"
        Common["Shared Logic"]:::common
    end

    %% Domain Models & Schemas
    subgraph "Domain & Schemas"
        Actions["Action Model"]:::domain
        WorkflowModel["Workflow Model"]:::domain
        WorkflowSchema["Workflow Schema"]:::domain
        Types["Type Definitions"]:::domain
    end

    %% Platform Adapters
    subgraph "Platform Adapters"
        subgraph "Browser Extension" 
            ExtCore["Extension Core"]:::adapter
            ExtContent["Content Scripts"]:::adapter
            ExtTools["Extension Tools"]:::adapter
        end
        subgraph "Web SDK"
            WebCore["Web Core"]:::adapter
            WebTools["Web Tools"]:::adapter
        end
        subgraph "Node.js SDK"
            NodeCore["Node.js Core"]:::adapter
            NodeTools["Node.js Tools"]:::adapter
        end
    end

    %% External Systems
    subgraph "External Systems"
        LLMAPI["LLM APIs\n(OpenAI/Claude)"]:::external
        BrowserAPI["Browser APIs"]:::external
        OSAPI["OS FS & Process"]:::external
    end

    %% Relationships
    Developer["Developer"]:::external
    Developer -->|invoke generate| EkoSDK
    EkoSDK -->|calls parser| Parser
    Parser -->|outputs model| WorkflowModel
    EkoSDK -->|calls generator| Generator
    Generator -->|uses templates| Templates
    Generator -->|calls LLM| LLMFactory
    LLMFactory -->|select provider| OpenAI
    LLMFactory -->|select provider| Claude
    OpenAI -->|API calls| LLMAPI
    Claude -->|API calls| LLMAPI
    EkoSDK -->|execute workflow| Executor
    Executor -->|fetch action impl| ToolRegistry
    ToolRegistry -->|dispatch to| ExtTools
    ToolRegistry -->|dispatch to| WebTools
    ToolRegistry -->|dispatch to| NodeTools
    ExtTools -->|use| BrowserAPI
    ExtCore -->|message| ExtContent
    WebTools -->|use| BrowserAPI
    NodeTools -->|use| OSAPI
    Common -->|shared by| Parser
    Common -->|shared by| Generator
    Common -->|shared by| Executor
    Actions -->|used by| Parser
    Actions -->|used by| Executor
    WorkflowSchema -->|validates| WorkflowModel
    Types -->|defines| Parser
    Developer -->|install SDK| Common

    %% Click Events
    click EkoSDK "https://github.com/fellouai/eko/blob/main/src/index.ts"
    click EkoSDK "https://github.com/fellouai/eko/blob/main/src/core/eko.ts"
    click Parser "https://github.com/fellouai/eko/blob/main/src/services/parser/workflow-parser.ts"
    click Generator "https://github.com/fellouai/eko/blob/main/src/services/workflow/generator.ts"
    click Executor "https://github.com/fellouai/eko/blob/main/src/core/eko.ts"
    click ToolRegistry "https://github.com/fellouai/eko/blob/main/src/core/tool-registry.ts"
    click LLMFactory "https://github.com/fellouai/eko/blob/main/src/services/llm/provider-factory.ts"
    click OpenAI "https://github.com/fellouai/eko/blob/main/src/services/llm/openai-provider.ts"
    click Claude "https://github.com/fellouai/eko/blob/main/src/services/llm/claude-provider.ts"
    click Templates "https://github.com/fellouai/eko/blob/main/src/services/workflow/templates.ts"
    click Common "https://github.com/fellouai/eko/tree/main/src/common"
    click Actions "https://github.com/fellouai/eko/blob/main/src/models/action.ts"
    click WorkflowModel "https://github.com/fellouai/eko/blob/main/src/models/workflow.ts"
    click WorkflowSchema "https://github.com/fellouai/eko/blob/main/src/schemas/workflow.schema.ts"
    click Types "https://github.com/fellouai/eko/tree/main/src/types"
    click ExtCore "https://github.com/fellouai/eko/blob/main/src/extension/core.ts"
    click ExtCore "https://github.com/fellouai/eko/blob/main/src/extension/index.ts"
    click ExtContent "https://github.com/fellouai/eko/blob/main/src/extension/content/index.ts"
    click ExtTools "https://github.com/fellouai/eko/blob/main/src/extension/tools/index.ts"
    click WebCore "https://github.com/fellouai/eko/blob/main/src/web/core.ts"
    click WebCore "https://github.com/fellouai/eko/blob/main/src/web/index.ts"
    click WebTools "https://github.com/fellouai/eko/blob/main/src/web/tools/index.ts"
    click NodeCore "https://github.com/fellouai/eko/blob/main/src/nodejs/core.ts"
    click NodeCore "https://github.com/fellouai/eko/blob/main/src/nodejs/index.ts"
    click NodeTools "https://github.com/fellouai/eko/blob/main/src/nodejs/tools/index.ts"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
    classDef service fill:#ffe0b2,stroke:#fb8c00,color:#e65100
    classDef adapter fill:#c8e6c9,stroke:#43a047,color:#1b5e20
    classDef external fill:#ffccbc,stroke:#e64a19,color:#bf360c
    classDef domain fill:#e1bee7,stroke:#8e24aa,color:#4a148c
    classDef common fill:#f0f4c3,stroke:#c0ca33,color:#827717
```
