# lobehub/lobe-chat-agents architecture

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

- Interactive diagram: https://gitdiagram.com/lobehub/lobe-chat-agents
- Repository: https://github.com/lobehub/lobe-chat-agents

## Overview

This project is a repository for “Lobe Chat Agents Index” – essentially a catalog of many “agent” definitions that Lobe Chat uses to display a rich variety of configurable conversational assistants. The repository is maintained by Lobehub and includes not only the agents’ metadata (in many languages, stored in JSON files under src and locales) but also all the supporting scripts, build configurations, testing and CI configurations (in .github and scripts folders), internationalization settings, and schema definitions.

##### Main functional components
- Data Repository (Agent Definitions): The source “src” directory holds hundreds of JSON files that specify each agent’s configuration – these files serve as the “agent database” or index. In addition, an “agents” directory (referenced in the README by its template files) and a “locales” folder hold internationalized content.
- Supporting Build and Testing Pipeline: The “scripts” directory contains various TypeScript scripts (e.g. build.ts, format.ts, test.ts, updateAwesome.ts) that process, validate, and publish the agent index. The “schema” subfolder and agent-template files indicate that the project uses a defined JSON schema for agents.
- CI/CD and Deployment Configuration: The .github folder (with workflows and issue templates) defines automated testing, code formatting, and release pipelines. In addition, package.json, tsconfig.json, and configuration files (e.g. .npmrc, .gitignore) define the Node.js environment.
- External Integrations: The README shows that the “Agents Index” is used by Lobe Chat’s website (and also by the Plugin Index in a separate linked repository). This means that there is an external consumer (the Lobe Chat UI) that fetches the index.

##### Relationships and interactions
- The agent definitions (data) in the “src” and “locales” directories are processed by the build scripts in “scripts” to generate an index artifact – this artifact is consumed by the main Lobe Chat service externally.
- CI/CD pipelines (configured in .github/workflows) automatically run tests and deploy changes (for example, using Vercel) whenever new commits or pull requests are merged.
- External clients (the Lobe Chat frontend, and the Plugin Index) retrieve the agents index from a deployed endpoint (as indicated by the “Website” links in the README).

##### Architectural patterns and design principles used
- Separation of Concerns: The project is clearly divided between data (agent definitions and internationalized content) and the build/test automation layer.
- CI/CD Automation: The use of GitHub workﬂows and scripts highlights an agile, automated deployment pipeline.
- Extensibility and Modularity: Agent templates and numerous JSON files show that the architecture facilitates adding new agents easily via pull requests.
- Internationalization: The locales folder and i18n configurations indicate a design that supports multiple languages.

##### Relevant technologies and frameworks
- Node.js (supported by package.json, tsconfig.json, and TypeScript scripts).
- GitHub Actions (for CI/CD workflows).
- Vercel (for self-hosting/deployment as noted in the README).
- JSON Schema (in the schema folder) to validate agent definitions.
- Internationalization tools (as evidenced by the i18n configuration files, e.g. .i18nrc.js).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Layer
    subgraph "Data Layer"
        A1["Agent Definitions (src/*.json)"]:::data
        A2["Agent Templates (agent-template.json & agent-template-full.json)"]:::data
        A3["Internationalization (locales/)"]:::data
        A4["i18n Configuration (.i18nrc.js)"]:::data
    end

    %% Build & Processing Layer
    subgraph "Build & Processing Layer"
        P1["Build Scripts (scripts/build.ts, format.ts, updateAwesome.ts)"]:::process
        P2["Testing Scripts (scripts/test.ts, testLocale.ts)"]:::process
        P3["Schema Definitions (schema/lobeAgentSchema_v1.json)"]:::process
        P4["Script-based Schema Extensions (scripts/schema/)"]:::process
    end

    %% CI/CD Automation Layer
    subgraph "CI/CD Automation"
        C1["CI/CD Config (.github workflows, package.json, tsconfig.json, .npmrc, .gitignore)"]:::automation
    end

    %% Deployment & Integration Layer
    subgraph "Deployment & Integration"
        D1["Deployed Agent Index Endpoint (Vercel)"]:::deployment
        D2["External Consumers (Lobe Chat UI & Plugin Index)"]:::deployment
    end

    %% Data Flow Connections
    A1 -->|"provides data"| P1
    A2 -->|"provides templates"| P1
    A3 -->|"localization data"| P1
    A4 -->|"i18n settings"| P1

    %% Supportive connections within Processing Layer
    P2 -.->|"testing supports"| P1
    P3 -.->|"schema validates"| P1
    P4 -.->|"schema extensions"| P1

    %% Deployment Pipeline Flow
    P1 -->|"triggers build"| C1
    C1 -->|"deploys update"| D1
    D1 -->|"consumed by"| D2

    %% Click Events
    click A1 "https://github.com/lobehub/lobe-chat-agents/tree/main/src/"
    click A2 "https://github.com/lobehub/lobe-chat-agents/blob/main/agent-template.json"
    click A3 "https://github.com/lobehub/lobe-chat-agents/tree/main/locales/"
    click A4 "https://github.com/lobehub/lobe-chat-agents/blob/main/.i18nrc.js"
    click P1 "https://github.com/lobehub/lobe-chat-agents/tree/main/scripts/"
    click P2 "https://github.com/lobehub/lobe-chat-agents/blob/main/scripts/test.ts"
    click P3 "https://github.com/lobehub/lobe-chat-agents/blob/main/schema/lobeAgentSchema_v1.json"
    click P4 "https://github.com/lobehub/lobe-chat-agents/tree/main/scripts/schema/"
    click C1 "https://github.com/lobehub/lobe-chat-agents/tree/main/.github/"

    %% Styles
    classDef data fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef process fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef automation fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef deployment fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
```
