# jodongguk/lobe-chat architecture

> Architecture diagram of the GitHub repository jodongguk/lobe-chat, 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/jodongguk/lobe-chat
- Repository: https://github.com/jodongguk/lobe-chat

## Overview

##### Main Components
- Frontend/UI Layer: This includes the “src/app” directory with its multiple subfolders (e.g. (main)/chat, (main)/market, (main)/settings, (main)/welcome) where various user interfaces are rendered. Note that the app is designed for modern dynamic interaction (e.g. progressive web app features, mobile adaptation, custom themes, etc.)
- API/Server Layer: The “src/app/api” directory and associated router files in “src/server/routers” handle authentication, chat routing, file/image processing, LLM provider interactions (such as providers for OpenAI, Anthropic, Groq, OpenRouter, etc.), and plugin gateway integration.
- Integration/Model Providers Subsystem: Under “src/config/modelProviders” and “src/libs/agent-runtime” you see support for a variety of external model APIs (AWS Bedrock, Anthropic, Google Gemini, etc.)—this subsystem manages calls to different LLM providers and local model support (i.e., using Ollama and local LLMs).
- State Management: The “src/store” directory contains several submodules (agent, chat, file, market, session, user, tool, etc.). This forms the central state management layer (likely using a library like Zustand) tracking conversation, user settings, and session data.
- Database / Persistence: Examine “src/database” and migration folders. Even though much data may be stored locally (for privacy protection) the project has a defined internal database schema and upgrade/migration routines.
- Utility & Shared Libraries: There are numerous utility directories (such as “src/helpers”, “src/utils”, “src/libs/trpc”, “src/config/”) that support both front- and back‑end functions (configuration, logging, error handling, i18n).
- Deployment/Infrastructure: Highlight that the project has Dockerfile, deployment workflows (GitHub Actions workflows in “.github/workflows”), Vercel/Netlify configurations, and self‑hosting documentation. These components sit outside the core business logic but are essential in the architecture.

##### Relationships and Interactions
- The API layer then interacts with the Integration layer (model providers and agent runtimes in “src/libs/agent-runtime” and “src/config/modelProviders”) to call external LLM or local inference services.
- The Plugin System, while logically distinct, hooks into both the UI (to render plugin interfaces and results) and the API (to handle function calls) and thus should be connected to both.
- The state management layer (multiple “src/store/*” directories) should be drawn as a central repository that feeds data to the UI and receives actions from UI events and API outcomes.
- Global localization (in “locales”, “src/locales”) and configuration modules (“src/config”) are cross-cutting concerns supporting both frontend and backend.
- Additional layers such as middleware (e.g. “src/middleware.ts”) handle request/response processing, error capturing, and authentication.

##### Architectural Patterns & Design Principles
- Use of a “Feature-driven Modular” approach is visible. The project separates concerns into “features” (chat, market, settings) and “components” (UI widgets, analytics, file lists, etc.).
- Emphasis on a unified state management pattern (central store slices for chat, agent, and session) and separation of business logic (services in “src/services”) from presentation (React components in “src/app” and “src/components”).
- The API and integration layers follow a microservice-like structure internally (with separate API endpoints for chat, auth, files, market, etc.) even though the deployment is monolithic in Next.js.
- The plugin system is built to be extensible and dynamic, allowing new plugins to be added and loaded at runtime.

##### Technologies, Frameworks & Libraries
- Next.js 13 for server-side rendering and routing.
- React (Functional Components, hooks) – visible in “src/app” and “src/components”.
- Zustand or similar state management libraries (evident from the “store” directories).
- Integration with third-party LLM providers and local model inference modules (using RESTful endpoints in “src/api”).
- Docker for containerized deployment and GitHub Actions for CI/CD.
- Internationalization using “locales” and tooling for i18n.

##### Conclusion
– Keep the overall design modular. For instance, each “feature” (chat, market, settings) can be shown as a sub‑module within the “Frontend” layer that communicates with its corresponding API endpoints.
– Ensure that critical integration points (such as the external LLM APIs and the plugin system) are clearly visible and show both the input (from the user via UI) and the output (back to the UI after processing).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend/UI Layer
    subgraph "Frontend/UI Layer"
        UI_Main["Next.js Frontend"]:::frontend
        ChatUI["Chat UI"]:::frontend
        MarketUI["Market UI"]:::frontend
        SettingsUI["Settings UI"]:::frontend
        WelcomeUI["Welcome UI"]:::frontend
        UI_Main --> ChatUI
        UI_Main --> MarketUI
        UI_Main --> SettingsUI
        UI_Main --> WelcomeUI
    end

    %% Plugin System
    subgraph "Plugin System"
        subgraph "Frontend"
            PluginDetail["Plugin Detail Modal"]:::plugin
            PluginDev["Plugin Dev Modal"]:::plugin
            PluginSettings["Plugin Settings"]:::plugin
            PluginStore["Plugin Store"]:::plugin
        end
        subgraph "Backend"
            PluginAPI["Plugin API Endpoints"]:::plugin
            PluginService["Plugin Service"]:::plugin
        end
        %% Connect Frontend Plugin components to Backend Plugin API
        PluginDetail -->|"callsPluginService"| PluginAPI
        PluginDev -->|"callsPluginService"| PluginAPI
        PluginSettings -->|"callsPluginService"| PluginAPI
        PluginStore -->|"callsPluginService"| PluginAPI
    end

    %% Backend/API & Integration Layer
    subgraph "Backend/API & Integration"
        API["API Endpoints"]:::backend
        Routers["Router Definitions"]:::backend
        API -->|"managedBy"| Routers
        IntegrationModel["Model Provider Configurations"]:::integration
        AgentRuntime["Agent Runtime Integrations"]:::integration
        API -->|"callsLLM"| IntegrationModel
        API -->|"callsRuntime"| AgentRuntime
    end

    %% State Management Layer
    subgraph "State Management"
        StateStore["Global State Store"]:::state
    end

    %% Database / Persistence Layer
    subgraph "Database / Persistence"
        Database["Database Schema & Client"]:::persistence
        Migrations["Migrations"]:::persistence
    end

    %% Utility & Shared Libraries
    subgraph "Utility & Shared Libraries"
        Helpers["Helper Utilities"]:::utility
        TRPC["TRPC & Config"]:::utility
    end

    %% Deployment / Infrastructure Layer
    subgraph "Deployment / Infrastructure"
        Docker["Docker Configuration"]:::deployment
        CICD["CI/CD Workflows"]:::deployment
        DeploymentSettings["Deployment Settings"]:::deployment
    end

    %% Connections between layers
    UI_Main -->|"sendsRequests"| API
    UI_Main -->|"updatesState"| StateStore
    API -->|"updatesState"| StateStore
    UI_Main -->|"usesPlugins"| PluginDetail
    UI_Main -->|"usesPlugins"| PluginDev
    UI_Main -->|"usesPlugins"| PluginSettings
    UI_Main -->|"usesPlugins"| PluginStore
    PluginAPI -->|"services"| PluginService

    %% Utility usage (shared by Frontend and Backend)
    UI_Main ---|"helpers"| Helpers
    API ---|"helpers"| Helpers
    UI_Main ---|"config"| TRPC
    API ---|"config"| TRPC

    %% Deployment links (conceptual)
    UI_Main ---|"deployedVia"| Docker
    API ---|"deployedVia"| Docker
    Database ---|"managedBy"| CICD
    Migrations ---|"managedBy"| CICD
    UI_Main ---|"settingsFrom"| DeploymentSettings
    API ---|"settingsFrom"| DeploymentSettings

    %% Click Events
    click UI_Main "https://github.com/jodongguk/lobe-chat/tree/main/src/app"
    click ChatUI "https://github.com/jodongguk/lobe-chat/tree/main/src/app/chat"
    click MarketUI "https://github.com/jodongguk/lobe-chat/tree/main/src/app/market"
    click SettingsUI "https://github.com/jodongguk/lobe-chat/tree/main/src/app/settings"
    click WelcomeUI "https://github.com/jodongguk/lobe-chat/tree/main/src/app/welcome"
    click API "https://github.com/jodongguk/lobe-chat/tree/main/src/app/api"
    click Routers "https://github.com/jodongguk/lobe-chat/tree/main/src/server/routers"
    click IntegrationModel "https://github.com/jodongguk/lobe-chat/tree/main/src/config/modelProviders"
    click AgentRuntime "https://github.com/jodongguk/lobe-chat/tree/main/src/libs/agent-runtime"
    click PluginAPI "https://github.com/jodongguk/lobe-chat/tree/main/src/app/api/plugin"
    click PluginDetail "https://github.com/jodongguk/lobe-chat/tree/main/src/features/PluginDetailModal"
    click PluginDev "https://github.com/jodongguk/lobe-chat/tree/main/src/features/PluginDevModal"
    click PluginSettings "https://github.com/jodongguk/lobe-chat/tree/main/src/features/PluginSettings"
    click PluginStore "https://github.com/jodongguk/lobe-chat/tree/main/src/features/PluginStore"
    click PluginService "https://github.com/jodongguk/lobe-chat/tree/main/src/services/plugin"
    click StateStore "https://github.com/jodongguk/lobe-chat/tree/main/src/store"
    click Database "https://github.com/jodongguk/lobe-chat/tree/main/src/database"
    click Migrations "https://github.com/jodongguk/lobe-chat/tree/main/src/migrations"
    click Helpers "https://github.com/jodongguk/lobe-chat/tree/main/src/helpers"
    click TRPC "https://github.com/jodongguk/lobe-chat/tree/main/src/libs/trpc"
    click Docker "https://github.com/jodongguk/lobe-chat/tree/main/Dockerfile"
    click CICD "https://github.com/jodongguk/lobe-chat/tree/main/.github/workflows"
    click DeploymentSettings "https://github.com/jodongguk/lobe-chat/blob/main/vercel.json"

    %% Styles
    classDef frontend fill:#f9e79f,stroke:#7d6608,stroke-width:2px;
    classDef backend fill:#aed6f1,stroke:#1b4f72,stroke-width:2px;
    classDef integration fill:#abebc6,stroke:#0e6251,stroke-width:2px;
    classDef plugin fill:#f5b7b1,stroke:#922b21,stroke-width:2px;
    classDef state fill:#fcf3cf,stroke:#7d6608,stroke-width:2px;
    classDef persistence fill:#d6eaf8,stroke:#1b4f72,stroke-width:2px;
    classDef utility fill:#d5f5e3,stroke:#145a32,stroke-width:2px;
    classDef deployment fill:#fadbd8,stroke:#943126,stroke-width:2px;
```
