# ibm/wxflows architecture

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

- Interactive diagram: https://gitdiagram.com/ibm/wxflows
- Repository: https://github.com/ibm/wxflows

## Overview

##### Main Components
- Tool Building & Deployment Core: This is the heart of the system, with tools defined in the “tools” directory. Each tool (e.g., exchange, wikipedia, google_books, math, weather) contains GraphQL definition files, configuration files (like stepzen.config.json), and sometimes environment configurations. These files define the behavior, API schema, and deployment parameters.
- Agent Integrations Layer: These are integrations shown under the “examples/tool-calling” directory, where various frameworks (LangGraph, LangChain, watsonx.ai, OpenAI) are set up to call the tools. The architecture should show how these agents connect to and make requests to the tools endpoints.
- Examples & Demos: There are several examples (chat-app, langgraph-math-agent, text-to-sql-agent, etc.) that demonstrate full-stack interactions. These examples include frontend components (React or Next.js apps), backend configurations, and client-side logic that invoke the built tools.
- Assets and Documentation: The “assets” folder and various README.md files provide documentation and static content. While less central to runtime execution, they support development and deployment.

##### Relationships and Data Flow
- That each tool is designed as a cloud endpoint that deploys via preconfigured “stepzen.config.json” files or similar deployment mechanisms.
- How configuration files and GraphQL schemas tie into the deployment and integration layers.
- An input/flow from external applications (e.g., chat apps) to the integration layer, then onward to the tool engine which processes requests and returns results.

##### Architectural Patterns & Design Principles
- Modularity: Clearly separate each tool as an independent module with its own configurations and schemas. Use grouping (e.g., “tools”, “examples/agents”, “examples/tool-calling”) to show clean separation.
- Loose Coupling: Emphasize that the integration layer (agents) interacts with tools using standardized GraphQL interfaces and configuration files, enabling easy plug-and-play.
- Extensibility: The system is built so that new tools can be “built your own tool” as indicated in the README. Represent this by drawing a pattern where tools can be added to the engine without major changes to other components.
- Multi-Frontend & API-First: The examples demonstrate both frontend (React/Next.js based UIs) and backend/API components; thus, a layered architecture (user interface, API gateway, business logic/tool engine) is recommended.

##### Relevant Technologies and Frameworks
- GraphQL: Used extensively to define API schemas (file extensions .graphql) and interactions.
- StepZen: Seen in configuration files (stepzen.config.json) that likely handle aspects of deployment and endpoint management.
- Frontend Frameworks: React, Next.js, Vite (as seen in demo applications) are used in various examples.
- Tool-specific SDKs: Provided for Python & JavaScript to integrate with the deployed tools.

##### Final Overview
- Then, optionally zoom into individual components (such as a single tool’s internal structure) if further detail is needed.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Frontend Examples (UI)
    subgraph "Frontend Examples (UI)"
        A1["Chat App"]:::frontend
        A2["LangGraph Math Agent"]:::frontend
        A3["Text-to-SQL Agent"]:::frontend
        A4["Other Demos"]:::frontend
    end

    %% Agent Integrations
    subgraph "Agent Integrations"
        B1["LangChain Integration"]:::integration
        B2["LangGraph Integration"]:::integration
        B3["OpenAI Integration"]:::integration
        B4["watsonx.ai Integration"]:::integration
    end

    %% Tool Engine (Backend Tools)
    subgraph "Tool Engine (Backend Tools)"
        C1["Exchange Tool"]:::tool
        C2["Google Books Tool"]:::tool
        C3["Math Tool"]:::tool
        C4["Weather Tool"]:::tool
        C5["Wikipedia Tool"]:::tool
        C6["YouTube Transcript Tool"]:::tool
    end

    %% Deployment Configurations
    subgraph "Deployment Configurations"
        D1["StepZen & GraphQL Schemas"]:::config
    end

    %% Assets & Documentation
    subgraph "Assets & Documentation"
        E1["Assets"]:::documentation
        E2["README Files"]:::documentation
    end

    %% Flow connections from Frontend to Agent Integrations
    A1 -->|"requests"| B1
    A1 -->|"requests"| B2
    A1 -->|"requests"| B3
    A1 -->|"requests"| B4

    A2 -->|"requests"| B2
    A3 -->|"requests"| B3
    A4 -->|"requests"| B1

    %% Agent Integrations to Tool Engine
    B1 -->|"calls"| C1
    B1 -->|"calls"| C2
    B1 -->|"calls"| C3

    B2 -->|"calls"| C3
    B2 -->|"calls"| C4

    B3 -->|"calls"| C5

    B4 -->|"calls"| C6

    %% Tool Engine to Deployment Configurations (Configuration Flow)
    C1 -->|"configures"| D1
    C2 -->|"configures"| D1
    C3 -->|"configures"| D1
    C4 -->|"configures"| D1
    C5 -->|"configures"| D1
    C6 -->|"configures"| D1

    %% Deployment Configurations to Assets & Documentation
    D1 ---|"docs"| E2
    D1 ---|"assets"| E1

    %% Click Events for Tool Building & Deployment Core
    click C1 "https://github.com/ibm/wxflows/tree/main/tools/exchange"
    click C2 "https://github.com/ibm/wxflows/tree/main/tools/google_books"
    click C3 "https://github.com/ibm/wxflows/tree/main/tools/math"
    click C4 "https://github.com/ibm/wxflows/tree/main/tools/weather"
    click C5 "https://github.com/ibm/wxflows/tree/main/tools/wikipedia"
    click C6 "https://github.com/ibm/wxflows/tree/main/tools/youtube_transcript"

    %% Click Events for Agent Integrations Layer
    click B1 "https://github.com/ibm/wxflows/tree/main/examples/tool-calling/langchain"
    click B2 "https://github.com/ibm/wxflows/tree/main/examples/tool-calling/langgraph"
    click B3 "https://github.com/ibm/wxflows/tree/main/examples/tool-calling/openai"
    click B4 "https://github.com/ibm/wxflows/tree/main/examples/tool-calling/watsonx"

    %% Click Events for Frontend Examples & Demos
    click A1 "https://github.com/ibm/wxflows/tree/main/examples/chat-app"
    click A2 "https://github.com/ibm/wxflows/tree/main/examples/langgraph-math-agent"
    click A3 "https://github.com/ibm/wxflows/tree/main/examples/text-to-sql-agent"
    click A4 "https://github.com/ibm/wxflows/tree/main/examples/mcp"

    %% Click Events for Assets & Documentation
    click E1 "https://github.com/ibm/wxflows/tree/main/assets"
    click E2 "https://github.com/ibm/wxflows/blob/main/README.md"

    %% Styling
    classDef frontend fill:#9fdf9f,stroke:#333,stroke-width:2px;
    classDef integration fill:#9fcdef,stroke:#333,stroke-width:2px;
    classDef tool fill:#fff79f,stroke:#333,stroke-width:2px;
    classDef config fill:#ffa500,stroke:#333,stroke-width:2px;
    classDef documentation fill:#d3d3d3,stroke:#333,stroke-width:2px;
```
