# yaoapp/yao architecture

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

- Interactive diagram: https://gitdiagram.com/yaoapp/yao
- Repository: https://github.com/yaoapp/yao

## Overview

- CLI & Command Modules: The “cmd” folder holds various CLI commands (e.g., dump, get, inspect, migrate, run, upgrade, version, etc.). These are the entry points that a developer uses to interact with the engine.
- DSL & Engine Core: The DSL processing and execution layers are spread over packages such as “engine”, “sui”, “neo”, “pipe”, and “moapi”. These modules parse the DSL input, translate it into executable actions, and integrate with the built-in V8 engine (which provides native TypeScript support).
- API Layer: The “api” along with “moapi” directories represent web API handling. They expose endpoints and/or provide REST/API gateways for the deployed applications.
- AI Integration: The “aigc” and “openai” folders indicate integration with AI services for generating or assisting with application code.
- Data & Persistence: Components such as “data”, “store”, “model”, “connector”, “config”, and “share” handle various configuration settings, data binding, and interactions with databases or caching layers.
- Plugin and Extension Mechanisms: Modules under “plugin” and several “widgets” directories provide extension points, visual components, and additional services, allowing the system to be customized or extended.
- External Services & Integrations: Folders such as “neo/assistant”, “neo/vision”, “wework”, “socket”, “crypto”, and “cert” illustrate integrations with external APIs, cloud storage, security/encryption, and certificates.
- DevOps & Deployment: The presence of multiple Docker-related directories (“docker/build”, “docker/development”, “docker/production”), GitHub Actions workflows (.github/workflows), and Makefile indicate that deployment, CI/CD, and containerization are first-class citizens in the system.

##### Relationships and Interactions Between Components
- The journey begins at the CLI interface (commands in “cmd”), which takes user inputs and translates them through the DSL.
- The DSL parser and runtime (in “engine”, “sui”, “neo”, “pipe”, etc.) processes the commands and instructions. It then interacts with lower-level components (for instance, helpers in “helper”, “importer”, and “data” management modules) to transform and execute the application logic.
- The API layer exposes services through REST endpoints (in folder “api” and “moapi”), which might interact with the DSL engine for executing business flows.
- AI modules (“aigc”, “openai”) communicate with the DSL core to provide auto-generated code or suggestions – usually collaborating with the core DSL engine.
- Plugin and widget systems (directories like “widgets”, “plugin”) allow external or additional components to be integrated, thereby extending the core functionality.
- Storage and external communication (handled by “store”, “connector”, “socket”, etc.) form the backbone for data persistence and interoperability between different modules.
- The entire system is containerized and prepared for different deployment environments using Docker and GitHub Actions, ensuring a smooth CI/CD pipeline.

##### Architectural Patterns and Design Principles
- Modular Design: The codebase is clearly segmented by function (CLI, engines, API, integrations, plugins), which promotes separation of concerns.
- Layered Architecture: The application clearly separates concerns—presentation (CLI/API), business logic (DSL engine, core processors), and data/integration layers.
- Extensibility & Plugin-based: With multiple “plugin” and “widgets” directories, the system is built to be extended in a plug-and-play manner.
- All-in-One Deployment: Yao is designed with a single executable in mind that encapsulates everything, reducing external dependencies.

##### Putting It All Together
- Below that, outline the DSL Engine layer with sub-modules (engine core, sui, neo, pipe) that process the DSL and manage AI integration.
- To the side, note the API layer (api, moapi), which handles incoming external requests, connecting to the DSL engine as needed.
- Finally, include separate blocks for Deployment & DevOps tools (docker, GitHub Actions) that ensure continuous integration and containerized deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Global Nodes
    Developer("Developer"):::user

    %% Command Interface
    CLI("CLI (cmd)"):::cli

    %% DSL Engine Layer
    subgraph "DSL Engine Layer"
        Engine("Engine (engine)"):::dsl
        Sui("Sui (sui)"):::dsl
        Neo("Neo (neo)"):::dsl
        Pipe("Pipe (pipe)"):::dsl
        Moapi_DSL("Moapi (moapi)"):::dsl
    end

    %% API Layer
    subgraph "API Layer"
        API("API (api)"):::api
        Moapi_API("Moapi (moapi)"):::api
    end

    %% AI Integration
    subgraph "AI Integration"
        Aigc("AIGC (aigc)"):::ai
        OpenAI("OpenAI (openai)"):::ai
    end

    %% Data & Persistence
    subgraph "Data & Persistence"
        Data("Data (data)"):::data
        Store("Store (store)"):::data
        Model("Model (model)"):::data
        Connector("Connector (connector)"):::data
        Config("Config (config)"):::data
        Share("Share (share)"):::data
    end

    %% Plugin and Extensions
    subgraph "Plugins & Extensions"
        Plugin("Plugin (plugin)"):::plugin
        Widgets("Widgets (widgets)"):::plugin
    end

    %% External Services
    subgraph "External Services"
        NeoAss("Neo Assistant (neo/assistant)"):::external
        NeoVis("Neo Vision (neo/vision)"):::external
        Wework("Wework (wework)"):::external
        Socket("Socket (socket)"):::external
        Crypto("Crypto (crypto)"):::external
        Cert("Cert (cert)"):::external
    end

    %% DevOps & Deployment
    subgraph "DevOps & Deployment"
        Docker("Docker (docker)"):::devops
        Github("GitHub Actions (.github)"):::devops
        Makefile("Makefile"):::devops
    end

    %% Connections
    Developer -->|"triggers"| CLI
    CLI -->|"executes"| Engine
    CLI -->|"executes"| Sui
    CLI -->|"executes"| Neo
    CLI -->|"executes"| Pipe
    CLI -->|"executes"| Moapi_DSL

    Engine -->|"processes"| API
    Sui -->|"processes"| API
    Neo -->|"processes"| API
    Pipe -->|"processes"| API
    Moapi_DSL -->|"processes"| API

    API -->|"exposes"| Developer

    Engine -->|"integrates_with"| Aigc
    Engine -->|"integrates_with"| OpenAI
    Aigc -->|"assists"| Engine
    OpenAI -->|"assists"| Engine

    Engine -->|"stores_data_in"| Data
    Data -->|"communicates_with"| Connector
    API -->|"fetches_data_from"| Data
    API -->|"utilizes"| Connector

    Engine -->|"invokes"| Plugin
    Engine -->|"invokes"| Widgets
    API -->|"invokes"| Plugin
    API -->|"invokes"| Widgets
    Plugin -->|"extends"| Engine
    Widgets -->|"extends"| Engine

    Neo ---|"integrates"| NeoAss
    Neo ---|"integrates"| NeoVis

    API ---|"communicates_via"| Socket
    API ---|"secured_by"| Crypto
    API ---|"secured_by"| Cert

    Docker -->|"builds"| API
    Docker -->|"builds"| Engine
    Github -->|"triggers_CI/CD_for"| Docker
    Makefile -->|"automates_build"| Docker

    %% Click Events
    click CLI "https://github.com/yaoapp/yao/tree/main/cmd/"
    click Engine "https://github.com/yaoapp/yao/tree/main/engine/"
    click Sui "https://github.com/yaoapp/yao/tree/main/sui/"
    click Neo "https://github.com/yaoapp/yao/tree/main/neo/"
    click Pipe "https://github.com/yaoapp/yao/tree/main/pipe/"
    click Moapi_DSL "https://github.com/yaoapp/yao/tree/main/moapi/"
    click API "https://github.com/yaoapp/yao/tree/main/api/"
    click Moapi_API "https://github.com/yaoapp/yao/tree/main/moapi/"
    click Aigc "https://github.com/yaoapp/yao/tree/main/aigc/"
    click OpenAI "https://github.com/yaoapp/yao/tree/main/openai/"
    click Data "https://github.com/yaoapp/yao/tree/main/data/"
    click Store "https://github.com/yaoapp/yao/tree/main/store/"
    click Model "https://github.com/yaoapp/yao/tree/main/model/"
    click Connector "https://github.com/yaoapp/yao/tree/main/connector/"
    click Config "https://github.com/yaoapp/yao/tree/main/config/"
    click Share "https://github.com/yaoapp/yao/tree/main/share/"
    click Plugin "https://github.com/yaoapp/yao/tree/main/plugin/"
    click Widgets "https://github.com/yaoapp/yao/tree/main/widgets/"
    click NeoAss "https://github.com/yaoapp/yao/tree/main/neo/assistant/"
    click NeoVis "https://github.com/yaoapp/yao/tree/main/neo/vision/"
    click Wework "https://github.com/yaoapp/yao/tree/main/wework/"
    click Socket "https://github.com/yaoapp/yao/tree/main/socket/"
    click Crypto "https://github.com/yaoapp/yao/tree/main/crypto/"
    click Cert "https://github.com/yaoapp/yao/tree/main/cert/"
    click Docker "https://github.com/yaoapp/yao/tree/main/docker/"
    click Github "https://github.com/yaoapp/yao/tree/main/.github/"
    click Makefile "https://github.com/yaoapp/yao/tree/main/Makefile"

    %% Styles
    classDef cli fill:#FFDDAD,stroke:#FFAA00,stroke-width:2px;
    classDef dsl fill:#D0E6A5,stroke:#8FB339,stroke-width:2px;
    classDef api fill:#A0D2DB,stroke:#1C89BF,stroke-width:2px;
    classDef ai fill:#F7C6C7,stroke:#E06666,stroke-width:2px;
    classDef data fill:#D6E6F2,stroke:#84A9C0,stroke-width:2px;
    classDef plugin fill:#F3E5F5,stroke:#AB47BC,stroke-width:2px;
    classDef external fill:#ECE5FF,stroke:#5E35B1,stroke-width:2px;
    classDef devops fill:#FFE0B2,stroke:#F57C00,stroke-width:2px;
    classDef user fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
```
