# cloudgeometry/langbuilder architecture

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

- Interactive diagram: https://gitdiagram.com/cloudgeometry/langbuilder
- Repository: https://github.com/cloudgeometry/langbuilder

## Overview

##### Project type and purpose
- This is a full-stack, self-hostable AI workflow builder and execution platform (“LangBuilder”), derived from LangFlow.
- It combines a React/TypeScript visual flow editor (frontend), a Python-based API & orchestration engine (backend), background workers (Celery), and a suite of deployment/infrastructure scripts.

##### High-level file structure
- Top level:
- src/frontend – React + Vite + ReactFlow editor, UI components, API hooks
- src/backend – Python package “langflow” with submodules: API routes, services (database, cache, chat, storage, task queue, telemetry), core, CLI, server, Celery app
- scripts/ – IaC and deployment helpers (AWS CDK, GCP, CI)
- docker/ & deploy/ – Dockerfiles and docker-compose configs for each service
- docs/ – Docusaurus site for user & dev guides

##### README insights
- Three layers:
1. Visual IDE (frontend + ReactFlow)
2. Programmable framework (backend API, LCEL orchestration, Python components)
3. Deployment & management (Celery, Docker, CDK, Kubernetes, CI/CD)
- Core technologies: Python 3.10+, uvicorn/uv, FastAPI-style routing, SQLAlchemy + Alembic migrations, Celery, Redis/RabbitMQ (for task queue), React, TypeScript, Vite, Docker, AWS CDK / GCP scripts

##### Main components & interactions (
A. Frontend application
- React/Vite SPA
- ReactFlow-based visual editor & playground
- API client layer (REST + WebSocket)
B. Backend API server
- Uvicorn/uv entrypoint (server.py)
- FastAPI-style routers under api/v1 & api/v2
- Authentication, authorization, feature-flags
- Control-plane (flow definitions) and data-plane (runtime events)
C. Background worker
- Celery app (celery_app.py + celeryconfig.py)
- Executes long-running flows, asynchronous tasks, callbacks
D. Data stores
- Relational DB (PostgreSQL, MySQL, etc. via SQLAlchemy + Alembic)
- Cache / message broker (Redis or RabbitMQ)
- Object storage (local disk or S3)
E. External services
- LLM providers (OpenAI, Anthropic, Bedrock, local models)
- Vector DBs (Chroma, Pinecone, Redis, Milvus, etc.)
- Third-party connectors (Notion, Gmail, Slack, etc.)
F. Infrastructure & deployment
- Dockerized microservices (API server, Celery worker, Redis, DB)
- Docker-compose and Kubernetes configurations
- AWS CDK (scripts/aws) and GCP scripts

- Frontend → HTTP/WS → Backend API
- Backend API → SQLAlchemy → Relational DB
- Backend API → Celery → Message Broker
- Celery Worker → executes tasks, writes results → DB / Storage
- Backend & Worker → integrate with external LLM & Vector services
- Admin CLI & scripts → deploy via Docker / CDK

##### Important architectural patterns
- Layered architecture: UI layer, API layer, service layer, data layer
- Service-oriented design within a monorepo (services/* factories)
- Repository/Factory patterns for database models, storage, caching
- Task queue pattern with Celery for asynchronous orchestration
- Plugin pattern for components and connectors (dynamic import, custom components)

##### Detail level
- Essential elements (UI, API, services, DB, queues, external)
- Avoid over-splitting; group similar connectors into “Component Plugins”
- Both synchronous (HTTP) and asynchronous (message queue) flows
- Deployment artifacts (Docker, CDK) as infrastructure notes or a footer layer

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Frontend Layer
  subgraph "Frontend Layer"
    direction TB
    FE_App["React/Vite SPA"]:::frontend
    FE_Editor["ReactFlow Editor"]:::frontend
    FE_API["API Client (REST + WS)"]:::frontend
  end

  click FE_App "https://github.com/cloudgeometry/langbuilder/blob/main/src/frontend/src/index.tsx"
  click FE_App "https://github.com/cloudgeometry/langbuilder/blob/main/src/frontend/src/App.tsx"
  click FE_API "https://github.com/cloudgeometry/langbuilder/blob/main/src/frontend/src/controllers/API/api.tsx"
  click FE_Editor "https://github.com/cloudgeometry/langbuilder/tree/main/src/frontend/src/CustomNodes"
  click FE_Editor "https://github.com/cloudgeometry/langbuilder/tree/main/src/frontend/src/CustomEdges"

  %% Backend API Server
  subgraph "Backend API Server"
    direction TB
    API_Server["Uvicorn/FastAPI Server"]:::backend
    API_Router["API Routers (router.py, v1, v2)"]:::backend
  end

  click API_Server "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/server.py"
  click API_Server "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/main.py"
  click API_Router "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/api/router.py"
  click API_Router "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/api/v1"
  click API_Router "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/api/v2"

  %% Core Orchestration & Services
  subgraph "Core & Services"
    direction TB
    Flow_Engine["Flow Engine & Runner"]:::backend
    Event_Manager["Event Manager"]:::backend
    Auth_Service["Auth Service"]:::backend
    Feature_Flags["Feature Flags"]:::backend
  end

  click Flow_Engine "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/flow/service.py"
  click Event_Manager "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/events"
  click Auth_Service "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/auth/service.py"
  click Feature_Flags "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/settings/feature_flags.py"

  %% Background Worker
  subgraph "Background Worker"
    direction TB
    Celery_App["Celery App Factory"]:::worker
    Celery_Config["Celery Configuration"]:::worker
    Worker_CLI["Worker CLI"]:::worker
  end

  click Celery_App "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/core/celery_app.py"
  click Celery_Config "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/core/celeryconfig.py"
  click Worker_CLI "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/worker.py"

  %% Data Stores
  subgraph "Data Stores"
    direction TB
    DB["Relational DB (PostgreSQL)"]:::datastore
    Broker["Cache/Message Broker"]:::datastore
    Storage["Object Storage"]:::datastore
  end

  click DB "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/alembic/env.py"
  click DB "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/services/database/models"
  click DB "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/database/service.py"
  click Broker "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/cache/service.py"
  click Broker "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/job_queue/backends/celery.py"
  click Storage "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/storage/local.py"
  click Storage "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/services/storage/s3.py"

  %% External Integrations
  subgraph "External Services"
    direction TB
    LLM["LLM Providers"]:::external
    Vector["Vector Stores"]:::external
    Connectors["Third-Party Connectors"]:::external
  end

  click LLM "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/components"
  click Vector "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/components/vectorstores"

  %% CLI & Initial Setup
  subgraph "Admin CLI & Setup"
    direction TB
    CLI["CLI Commands"]:::backend
    Init_Setup["Initial Setup"]:::backend
  end

  click CLI "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/cli"
  click Init_Setup "https://github.com/cloudgeometry/langbuilder/tree/main/src/backend/base/langflow/initial_setup"
  click Init_Setup "https://github.com/cloudgeometry/langbuilder/blob/main/src/backend/base/langflow/initial_setup/setup.py"

  %% Infrastructure & Deployment
  subgraph "Infrastructure & Deployment"
    direction TB
    Docker_Comp["Docker & Compose"]:::infra
    CDK_Scripts["AWS CDK Scripts"]:::infra
    GCP_Scripts["GCP Deployment Scripts"]:::infra
  end

  click Docker_Comp "https://github.com/cloudgeometry/langbuilder/blob/main/deploy/docker-compose.yml"
  click Docker_Comp "https://github.com/cloudgeometry/langbuilder/blob/main/docker/dev.docker-compose.yml"
  click CDK_Scripts "https://github.com/cloudgeometry/langbuilder/blob/main/scripts/aws/lib/cdk-stack.ts"
  click GCP_Scripts "https://github.com/cloudgeometry/langbuilder/blob/main/scripts/gcp/deploy_langflow_gcp.sh"

  %% Connections
  FE_API -->|"HTTP/REST & WS"| API_Server
  FE_API -->|"HTTP/REST & WS"| API_Router
  API_Router -->|"SQL (via SQLAlchemy)"| DB
  API_Router -->|"AMQP (via Celery)"| Broker
  API_Router -->|"Service Calls"| Flow_Engine
  API_Router -->|"Auth/API"| Auth_Service
  Flow_Engine -->|"Events"| Event_Manager
  Event_Manager -->|"Task Dispatch"| Celery_App
  Celery_App -->|"AMQP"| Broker
  Celery_App -->|"Exec Tasks"| Worker_CLI
  Worker_CLI -->|"Write Results"| DB
  Worker_CLI -->|"Store Artifacts"| Storage
  API_Router -->|"External API"| LLM
  Flow_Engine -->|"Vector Queries"| Vector
  API_Router -->|"Plugin Load"| Connectors
  CLI -->|"Deploy Scripts"| Docker_Comp
  CLI -->|"Deploy Scripts"| CDK_Scripts
  CLI -->|"Deploy Scripts"| GCP_Scripts

  %% Styles
  classDef frontend fill:#D0E8FF,stroke:#73B1FF,stroke-width:1px;
  classDef backend fill:#DFFFE0,stroke:#8CD68C,stroke-width:1px;
  classDef worker fill:#FFE6C7,stroke:#FFB14E,stroke-width:1px;
  classDef datastore fill:#E0E0E0,stroke:#A0A0A0,stroke-width:1px;
  classDef external fill:#F3E0FF,stroke:#C17AFF,stroke-width:1px;
  classDef infra fill:#F0F0F0,stroke:#C0C0C0,stroke-width:1px;
```
