# cloudwego/eino-examples architecture

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

- Interactive diagram: https://gitdiagram.com/cloudwego/eino-examples
- Repository: https://github.com/cloudwego/eino-examples

## Overview

##### Project type and purpose
- This is an open-source examples repository (“Eino Examples”) that demonstrates how to use the Eino framework.
- It is not a single running application but a set of illustrative modules: reusable extension components, orchestration patterns (chains and graphs), flow-based demos, and quickstart clients.

##### File structure
- Top-level directories:
- components/ – individual extension modules (document parsers, prompt builders, retrievers, lambda wrappers, tools)
- compose/    – orchestration examples (chain and graph patterns)
- flow/       – flow-based pipelines and multi-agent demos
- quickstart/ – runnable sample apps (chat, assistant, todo agent)
- internal/   – shared framework glue code (logging, pointer utilities)
- devops/     – debugging harnesses and local testing utilities
- Configuration & scaffolding: GitHub workflows (.github/workflows), lint, module files (go.mod / go.sum), code of conduct, contribution guidelines.

##### Extract architectural insights from the README
- The README describes four major example categories (components, compose, flow, quickstart)
- No single “live” service—each example instantiates different Eino extension points and orchestration patterns.

##### Main components & interactions
a. Core Eino Framework (implicit)
- internal/gptr, internal/logs, plus the Eino runtime that examples import
b. Extension Components (components/)
- document parsers (customparser, extparser, textparser)
- prompts (chat_prompt)
- retriever routers & multi-query
- lambda invocation wrapper
- openapi3 tooling
c. Orchestration Modules (compose/)
- Chain runner: linear sequence of component calls
- Graph executor: DAG of steps with interrupt/react patterns, two-model chat, stateful graphs, tool-call agent
d. Flow Pipelines (flow/)
- Single-agent binaries (manus, react)
- Multi-agent hosts (journal-driven, plan_execute)
- Data flows for stream processing and tool orchestration
e. Quickstart Clients (quickstart/)
- CLI/HTTP chat (openai, ollama)
- Eino assistant service (Docker + web UI + Redis/memory back-ends)
- Todo agent demo

##### Relationships & data flow
- Quickstart clients invoke orchestrators or components through the Eino framework API.
- Orchestrators (compose/flow) coordinate component calls in chains or graphs.
- Components perform discrete tasks: parsing, retrieval, LLM prompts, external API calls.
- Data flows from user input → orchestrator → component sequence → aggregated response → user output.

##### Architectural patterns & design principles
- Plug-in architecture: components/ directory implements well-defined interfaces that orchestrators load at runtime.
- Orchestration patterns: chain-of-responsibility for Chain, DAG execution for Graph, event-driven/reactive for stateful flows.
- Flow-based programming: pipelines that allow streaming and agent-to-agent communication.
- Separation of concerns: core framework (internal/) vs extensions (components/) vs demos (compose/, flow/, quickstart/).

##### Technologies & frameworks
- Go modules (go.mod)
- Eino extension packages (cloudwego/eino-ext)
- LLM backends (OpenAI, Ollama)
- Redis and in-memory stores in quickstart
- Web UI components (HTML/JS) for the Eino assistant

## Diagram (Mermaid)

```mermaid
graph TB
    %% Quickstart Clients
    subgraph "Quickstart Clients"
        style QS fill:#d3b0ff,stroke:#8041d9,stroke-width:1px
        ChatSample["Chat CLI/HTTP Sample"]:::qs
        EinoAssistant["Eino Assistant Service"]:::qs
        TodoAgent["Todo Agent Demo"]:::qs
    end

    %% Flow Pipelines
    subgraph "Flow Pipelines"
        style FL fill:#ffd8a8,stroke:#ff7f11,stroke-width:1px
        Manus["Single-Agent ‘Manus’"]:::flow
        ReactAgent["Single-Agent ‘React’"]:::flow
        JournalHost["Multi-Agent Journal Host"]:::flow
        PlanExecute["Multi-Agent Plan-Execute"]:::flow
    end

    %% Orchestration Modules
    subgraph "Orchestration Modules"
        style OR fill:#b7e4c7,stroke:#40916c,stroke-width:1px
        ChainRunner["Chain Runner"]:::orch
        GraphSimple["Graph Executor – Simple"]:::orch
        GraphReact["Graph Executor – React with Interrupt"]:::orch
        GraphState["Graph Executor – Stateful"]:::orch
        GraphToolCall["Graph Executor – Tool-Call Agent"]:::orch
        GraphTwoModel["Graph Executor – Two-Model Chat"]:::orch
    end

    %% Extension Components
    subgraph "Extension Components"
        style EX fill:#a2d2ff,stroke:#1d4e89,stroke-width:1px
        CustomParser["Custom Document Parser"]:::ext
        ExtParser["External Document Parser"]:::ext
        TextParser["Text Document Parser"]:::ext
        LambdaWrapper["Lambda Invocation Wrapper"]:::ext
        ChatPrompt["Chat Prompt Builder"]:::ext
        MultiQuery["Retriever – Multi-Query"]:::ext
        Router["Retriever – Router"]:::ext
        OpenAPI3["OpenAPI3 Tooling"]:::ext
    end

    %% Core Eino Framework
    subgraph "Core Eino Framework"
        style CO fill:#e0e0e0,stroke:#6e6e6e,stroke-width:1px
        Ptr["Pointer Utilities (gptr/ptr.go)"]:::core
        Logger["Logging (logs/logger.go)"]:::core
    end

    %% Data Flow Arrows
    ChatSample -->|"uses"| ChainRunner
    ChatSample -->|"uses"| GraphSimple
    EinoAssistant -->|"uses"| GraphState
    EinoAssistant -->|"uses"| ChainRunner
    TodoAgent -->|"uses"| GraphToolCall

    Manus -->|"example flow"| ChainRunner
    ReactAgent -->|"example flow"| GraphReact
    JournalHost -->|"hosts agents"| PlanExecute
    PlanExecute -->|"plans & executes"| GraphTwoModel

    %% Orchestrators to Components (Dependencies)
    ChainRunner -.->|implements interface| CustomParser
    ChainRunner -.->|implements interface| ChatPrompt
    GraphSimple -.->|loads| ExtParser
    GraphReact -.->|loads| LambdaWrapper
    GraphState -.->|loads| TextParser
    GraphToolCall -.->|calls| OpenAPI3
    GraphTwoModel -.->|retrieves via| MultiQuery
    GraphTwoModel -.->|routes via| Router

    %% Component to Core
    CustomParser -.->|"uses runtime"| Ptr
    ExtParser -.->|"uses runtime"| Ptr
    TextParser -.->|"uses runtime"| Ptr
    ChatPrompt -.->|"logs via"| Logger
    LambdaWrapper -.->|"logs via"| Logger
    MultiQuery -.->|"logs via"| Logger
    Router -.->|"logs via"| Logger
    OpenAPI3 -.->|"uses runtime"| Ptr

    %% Quickstart to Core
    EinoAssistant -->|"logs via"| Logger

    %% Click Events
    click Ptr "https://github.com/cloudwego/eino-examples/blob/main/internal/gptr/ptr.go"
    click Logger "https://github.com/cloudwego/eino-examples/blob/main/internal/logs/logger.go"
    click CustomParser "https://github.com/cloudwego/eino-examples/blob/main/components/document/parser/customparser/custom_parser.go"
    click ExtParser "https://github.com/cloudwego/eino-examples/blob/main/components/document/parser/extparser/ext_parser.go"
    click TextParser "https://github.com/cloudwego/eino-examples/blob/main/components/document/parser/textparser/text_parser.go"
    click LambdaWrapper "https://github.com/cloudwego/eino-examples/blob/main/components/lambda/lambda.go"
    click ChatPrompt "https://github.com/cloudwego/eino-examples/blob/main/components/prompt/chat_prompt/chat_prompt.go"
    click MultiQuery "https://github.com/cloudwego/eino-examples/blob/main/components/retriever/multiquery/main.go"
    click Router "https://github.com/cloudwego/eino-examples/blob/main/components/retriever/router/main.go"
    click OpenAPI3 "https://github.com/cloudwego/eino-examples/blob/main/components/tool/openapi3/main.go"
    click ChainRunner "https://github.com/cloudwego/eino-examples/blob/main/compose/chain/main.go"
    click GraphSimple "https://github.com/cloudwego/eino-examples/blob/main/compose/graph/simple/graph.go"
    click GraphReact "https://github.com/cloudwego/eino-examples/blob/main/compose/graph/react_with_interrupt/main.go"
    click GraphState "https://github.com/cloudwego/eino-examples/blob/main/compose/graph/state/state_graph.go"
    click GraphToolCall "https://github.com/cloudwego/eino-examples/blob/main/compose/graph/tool_call_agent/tool_call_agent.go"
    click GraphTwoModel "https://github.com/cloudwego/eino-examples/blob/main/compose/graph/two_model_chat/two_model_chat.go"
    click Manus "https://github.com/cloudwego/eino-examples/blob/main/flow/agent/manus/manus.go"
    click ReactAgent "https://github.com/cloudwego/eino-examples/blob/main/flow/agent/react/react.go"
    click JournalHost "https://github.com/cloudwego/eino-examples/blob/main/flow/agent/multiagent/host/journal/main.go"
    click PlanExecute "https://github.com/cloudwego/eino-examples/blob/main/flow/agent/multiagent/plan_execute/main.go"
    click ChatSample "https://github.com/cloudwego/eino-examples/blob/main/quickstart/chat/main.go"
    click EinoAssistant "https://github.com/cloudwego/eino-examples/blob/main/quickstart/eino_assistant/cmd/einoagent/agent/server.go"
    click TodoAgent "https://github.com/cloudwego/eino-examples/blob/main/quickstart/todoagent/main.go"

    %% Styles
    classDef core fill:#e0e0e0,stroke:#6e6e6e,color:#000
    classDef ext fill:#a2d2ff,stroke:#1d4e89,color:#000
    classDef orch fill:#b7e4c7,stroke:#40916c,color:#000
    classDef flow fill:#ffd8a8,stroke:#ff7f11,color:#000
    classDef qs fill:#d3b0ff,stroke:#8041d9,color:#000
```
