# gensx-inc/gensx architecture

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

- Interactive diagram: https://gitdiagram.com/gensx-inc/gensx
- Repository: https://github.com/gensx-inc/gensx

## Overview

Overview:
- This project is a monorepo for GenSX – a TypeScript framework that enables users to build agents and workflows in a React-like style but using a data-flow model. The framework helps developers compose LLM (Large Language Model) calls into workflows using pure, composable components. The repository includes the core framework packages, adapters for various AI providers, CLI tools, example workflows, containerization scripts, and a documentation website.

Identifying the Main Components:
##### Packages
- Core Framework (e.g., packages/gensx-core): Contains the fundamental APIs and utility functions to create, compose, and execute components.
- Provider-specific Adapters (e.g., packages/gensx-openai, packages/gensx-anthropic, packages/gensx-vercel-ai-sdk, etc.): These packages connect the framework’s workflow components to external LLM services.
- CLI Tools (e.g., packages/gensx-cli, packages/create-gensx): Provide command-line interfaces for project scaffolding, deployment, and workflow execution.
- Specialized Rules and Extensions (e.g., packages/gensx-cursor-rules, packages/gensx-cline-rules, packages/gensx-windsurf-rules) that manage runtime rules for various operational scenarios.

##### Examples
- The examples directory demonstrates how to build workflows using GenSX. There are multiple subdirectories featuring different use cases (e.g., streaming, contexts, nested providers, reflection, blog writing, etc.).
- These examples are essential for understanding how the components are composed in a real-world scenario.

##### Containers
- The containers directory includes Dockerfiles and shell scripts used for containerizing parts of the GenSX system. This implies a deployment or build-time environment separation, often required for CI/CD.

##### Website/Documentation
- The website folder contains the GenSX website and documentation. This helps users learn about the framework’s features, usage patterns, API references, and guides.

##### CI/CD and Testing
- The .github/workflows and related configuration files ensure that the code is built, linted, and tested automatically.
- There are also testing configurations (Vitest, test directories inside packages) that underline a strong emphasis on quality assurance.

- Main Components to Represent:
1. Client/User Interaction and Frontend:
- CLI Interfaces (packages/gensx-cli, packages/create-gensx)
- Example Projects (located in the examples folder)
- Documentation and User Guidance (website)

2. Framework Core:
- Core Engine (packages/gensx-core) handling workflow orchestration, parallel execution, and data flow management.
- Component System – the React-like components that encapsulate LLM calls and other functionalities.
- Workflow Management – the abstraction that connects and composes individual components into end-to-end workflows.

3. Provider/Adapters Layer:
- External AI integrations: packages/gensx-openai, packages/gensx-anthropic, and others.
- These packages manage the communication between GenSX components and third-party LLM services (like OpenAI, Anthropic, etc.).

4. Utility and Tooling:
- Container builds (containers folder), CI/CD pipelines (.github/workflows)
- Testing and linting configurations integrated across multiple packages.
- Configuration and environment management (e.g., .env.test, tsconfig.json, eslint.config.mjs)

Relationships & Data Flow:
- From the Core Engine, illustrate how component composition flows bidirectionally into the Provider/Adapters layer, which in turn communicates with external services.
- Input “prompts” and “research” flow into workflow components.
- Results and streaming outputs travel back through the workflow.
- That the CI/CD layer and containerization support are parallel processes for build, test, and deployment independent of the runtime workflow.

Architectural Patterns and Design Principles:
- Component-Based Architecture: Inspired by React components, where each part of the workflow is a self-contained, pure function.
- Data Flow Orchestration: Components compose workflows that automatically manage execution order, dependencies, and even parallel processing.
- Modularity and Extensibility: The division into multiple packages ensures that providers, core functionality, CLI tools, and rules can be maintained, tested, and extended independently.
- Infrastructure as Code: Containerization scripts and CI/CD configurations are vital for automated builds and deployments.

- For a framework/monorepo:
- Clearly separate the “Core” layer from “Adapters/Providers” and “CLI/Examples.”
- How workflows (shown as chains or pipelines of components) interact with external services.

Conclusion:

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction Layer
    subgraph "User Interaction"
        cliTool["GenSX CLI (CLI Tools)"]:::cli
        scaffoldTool["Project Scaffolding (CLI)"]:::cli
        workflowExamples["Workflow Examples (Examples)"]:::example
        websiteDoc["Website Documentation (Website)"]:::website
    end

    %% Core Framework Layer
    subgraph "Core Framework"
        coreEngine["Core Engine (gensx-core)"]:::core
    end

    %% Provider/Adapters Layer
    subgraph "Provider/Adapters"
        openai["OpenAI Adapter (gensx-openai)"]:::provider
        anthropic["Anthropic Adapter (gensx-anthropic)"]:::provider
        vercel["Vercel AI SDK (gensx-vercel-ai-sdk)"]:::provider
    end

    %% Specialized Rules Layer
    subgraph "Specialized Rules"
        cursorRules["Cursor Rules (gensx-cursor-rules)"]:::rules
        clineRules["Cline Rules (gensx-cline-rules)"]:::rules
        windsurfRules["Windsurf Rules (gensx-windsurf-rules)"]:::rules
    end

    %% Utility & Tooling Layer
    subgraph "Utility & Tooling"
        container["Containerization & Build Scripts (containers)"]:::utility
        cicd["CI/CD & Testing (.github)"]:::utility
    end

    %% Connections from User Interaction to Core Framework
    cliTool -->|"startWorkflow"| coreEngine
    scaffoldTool -->|"startWorkflow"| coreEngine
    workflowExamples -->|"demoWorkflow"| coreEngine
    websiteDoc -->|"guides"| cliTool

    %% Connections from Core Framework to Provider/Adapters
    coreEngine -->|"callsLLM"| openai
    coreEngine -->|"callsLLM"| anthropic
    coreEngine -->|"callsLLM"| vercel

    %% Connections from Core Framework to Specialized Rules
    coreEngine -->|"usesRules"| cursorRules
    coreEngine -->|"usesRules"| clineRules
    coreEngine -->|"usesRules"| windsurfRules

    %% Utility & Tooling Connections
    container -->|"build"| cicd
    cicd -->|"deploy"| coreEngine

    %% Styles
    classDef core fill:#CFE2F3,stroke:#6C8EBF,stroke-width:2px;
    classDef provider fill:#D9EAD3,stroke:#6AA84F,stroke-width:2px;
    classDef cli fill:#F9CB9C,stroke:#E69138,stroke-width:2px;
    classDef example fill:#FFE599,stroke:#BF9000,stroke-width:2px;
    classDef website fill:#B4A7D6,stroke:#8E7CC3,stroke-width:2px;
    classDef utility fill:#D9D2E9,stroke:#8E7CC3,stroke-width:2px;
    classDef rules fill:#F4CCCC,stroke:#CC0000,stroke-width:2px;

    %% Click Events
    click coreEngine "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-core"
    click openai "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-openai"
    click anthropic "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-anthropic"
    click vercel "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-vercel-ai-sdk"
    click cliTool "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-cli"
    click scaffoldTool "https://github.com/gensx-inc/gensx/tree/main/packages/create-gensx"
    click cursorRules "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-cursor-rules"
    click clineRules "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-cline-rules"
    click windsurfRules "https://github.com/gensx-inc/gensx/tree/main/packages/gensx-windsurf-rules"
    click workflowExamples "https://github.com/gensx-inc/gensx/tree/main/examples"
    click container "https://github.com/gensx-inc/gensx/tree/main/containers"
    click cicd "https://github.com/gensx-inc/gensx/blob/main/.github"
    click websiteDoc "https://github.com/gensx-inc/gensx/tree/main/website"
```
