# open-webui/pipelines architecture

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

- Interactive diagram: https://gitdiagram.com/open-webui/pipelines
- Repository: https://github.com/open-webui/pipelines

## Overview

##### Project type and purpose
- This is an open-source, UI-agnostic plugin framework (“Pipelines”) for any client supporting the OpenAI API spec.
- Its job is to receive OpenAI-style HTTP requests, dispatch them through customizable Python “pipelines” (filters and workflows), call external LLM or other APIs, and return responses to the calling UI.

##### File structure
- Top‐level Docker and CI configs (.github, Dockerfile, docker-compose.yaml) indicate containerized deployment.
- `main.py`, `config.py`, `schemas.py` form the core HTTP server and configuration layer.
- `blueprints/` contains route definitions or FastAPI/Flask blueprints for OpenAI-compatible endpoints.
- `pipelines/` (loaded at startup) holds the user’s custom Python modules (filters, pipelines).
- `utils/` implements internal helpers (auth, request orchestration).
- `examples/` demonstrates how to write new filters, pipelines, or integration modules.
- Requirements, start scripts, and CI workflows support local development and Docker builds.

##### README for additional insights
- The README describes how to run the service, load pipelines dynamically, and wire it to an Open WebUI client via the OpenAI API URL.

a. Main components
- **Client/UI**
Any OpenAI-API-compatible UI (e.g., Open WebUI).
- **API Gateway / HTTP Server**
`main.py` + `blueprints/` serving POST /v1/chat/completions, function‐calling endpoints.
- **Pipeline Manager**
Discovers and loads modules in `/pipelines`. Orchestrates the execution chain (filters, custom logic).
- **Pipeline Modules**
User‐provided filters (data transformations, rate-limit, detoxify), workflows (LangChain, RAG).
- **Utils & Config**
Authentication, telemetry, environment variables, pipeline directory config.
- **External Services**
OpenAI, Anthropic, AWS Bedrock, local llama.cpp, translation APIs, Langfuse logs.
- **Deployment Layer**
Docker container, Docker Compose network, volumes for persistent pipelines.

b. Relationships & interactions
1) **Client** sends an OpenAI-style HTTP request →
2) **API Gateway** (FastAPI/Flask + blueprints)
3) Request flows into **Pipeline Manager**, which:
- Authenticates via `utils/pipelines/auth.py`
- Looks up matching pipeline module in `/pipelines`
- Passes the request through a chain of filters (e.g., rate limit, detoxify)
- Finally calls the selected LLM provider driver (e.g., `openai_pipeline.py`)
4) **Provider module** invokes the external API → returns a streaming or full response
5) Response travels back through any “after” filters → returned to **Client**
6) Logging, metrics, and optional admin UI interactions happen alongside.

c. Architectural patterns & principles
- **Plugin architecture**: pipelines directory is a drop-in plugin folder, loaded at runtime.
- **Separation of concerns**: request routing vs. pipeline orchestration vs. provider integrations.
- **Config-driven**: env vars (`PIPELINES_URLS`, `PIPELINES_DIR`, `PIPELINES_API_KEY`) control behavior.
- **Micro-workflow**: each pipeline is a composable chain of filters and provider calls.
- **Containerized deployment**: Dockerfile, docker-compose for isolation and scalability.

d. Key technologies & frameworks
- **Python 3.11**
- **FastAPI** or **Flask** blueprints (in `blueprints/`) for HTTP endpoints
- **uvicorn/gunicorn** (implied by start scripts)
- **Docker**, **Docker Compose**
- **External AI SDKs**: `openai`, `anthropic`, `azure`, etc.
- **Internal utils** for auth, orchestration, and environment config.

##### Elements
- **Clear labels**: Client, API Gateway, Pipeline Manager, Plugin Folder, Provider Modules, External APIs, Docker Host.
- Client → API Gateway → Pipeline Manager → Pipeline Module → External API
- External API → Pipeline Module → Pipeline Manager → Client
- Core components (blue)
- Plugin modules (green)
- External services (orange)
- Infrastructure (gray)

##### Detail
- Layer: HTTP routing, auth, pipeline dispatch, filters chain, provider invocation, response streaming.
- Config/env var influences (e.g., `PIPELINES_DIR`).
- Docker networking: host.docker.internal, service name resolution.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    Client["OpenAI-API Compatible UI"]:::external

    %% Docker Deployment
    subgraph "Docker Deployment" 
        direction TB
        DockerfileNode["Dockerfile"]:::infra
        DockerCompose["docker-compose.yaml"]:::infra
        GithubCI[".github/workflows"]:::infra
    end

    %% Core Server
    subgraph "Core Server" 
        direction TB
        APIGateway["API Gateway / HTTP Server"]:::core
        Config["Configuration Layer<br/>(config.py)"]:::core
        PipelineManager["Pipeline Manager<br/>(utils/pipelines/main.py)"]:::core
        Auth["Auth & Orchestration<br/>(auth.py)"]:::core
        Misc["Misc Utilities<br/>(misc.py)"]:::core
    end

    %% API Gateway internals
    subgraph "API Gateway Implementation" 
        direction TB
        MainPy["main.py"]:::core
        Blueprint["blueprints/function_calling_blueprint.py"]:::core
        Schemas["schemas.py"]:::core
    end

    %% Plugin Modules
    subgraph "Plugin Modules" 
        direction TB
        PipelinesDir["pipelines/"]:::plugin
    end

    %% Examples
    subgraph "Built-in Examples" 
        direction TB
        ExamplesFilters["examples/filters/"]:::plugin
        ExamplesPipelines["examples/pipelines/"]:::plugin
        ExamplesProviders["examples/pipelines/providers/"]:::plugin
    end

    %% External Services
    subgraph "External AI Services" 
        direction TB
        External["OpenAI, Anthropic, Bedrock,…"]:::external
    end

    %% Connections
    Client -->|"HTTP Request"| APIGateway
    APIGateway --> MainPy
    MainPy --> Blueprint
    MainPy --> Schemas
    APIGateway -->|"load config"| Config
    APIGateway -->|"invoke"| PipelineManager
    PipelineManager --> Auth
    PipelineManager --> Misc
    PipelineManager --> PipelinesDir
    PipelineManager -->|"fallback to examples"| ExamplesPipelines
    ExamplesPipelines --> ExamplesProviders
    ExamplesPipelines --> ExamplesFilters
    PipelineManager -->|"call provider"| External
    External -->|"response"| PipelineManager
    PipelineManager --> APIGateway
    APIGateway --> Client

    %% Click Events
    click MainPy "https://github.com/open-webui/pipelines/blob/main/main.py"
    click Blueprint "https://github.com/open-webui/pipelines/blob/main/blueprints/function_calling_blueprint.py"
    click Schemas "https://github.com/open-webui/pipelines/blob/main/schemas.py"
    click Config "https://github.com/open-webui/pipelines/blob/main/config.py"
    click PipelineManager "https://github.com/open-webui/pipelines/blob/main/utils/pipelines/main.py"
    click PipelinesDir "https://github.com/open-webui/pipelines/tree/main/pipelines/"
    click Auth "https://github.com/open-webui/pipelines/blob/main/utils/pipelines/auth.py"
    click Misc "https://github.com/open-webui/pipelines/blob/main/utils/pipelines/misc.py"
    click ExamplesFilters "https://github.com/open-webui/pipelines/tree/main/examples/filters/"
    click ExamplesPipelines "https://github.com/open-webui/pipelines/tree/main/examples/pipelines/"
    click ExamplesProviders "https://github.com/open-webui/pipelines/tree/main/examples/pipelines/providers/"
    click DockerfileNode "https://github.com/open-webui/pipelines/tree/main/Dockerfile"
    click DockerCompose "https://github.com/open-webui/pipelines/blob/main/docker-compose.yaml"
    click GithubCI "https://github.com/open-webui/pipelines/tree/main/.github/workflows/"

    %% Styles
    classDef core fill:#bbdefb,stroke:#1e88e5,color:#0d47a1;
    classDef plugin fill:#c8e6c9,stroke:#43a047,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#fb8c00,color:#e65100;
    classDef infra fill:#eceff1,stroke:#90a4ae,color:#37474f;
```
