# tonikiri666/langflow architecture

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

- Interactive diagram: https://gitdiagram.com/tonikiri666/langflow
- Repository: https://github.com/tonikiri666/langflow

## Overview

##### Project type and purpose
- Langflow is a full-stack AI workflow builder. It consists of:
- A React/TypeScript single-page application (src/frontend)
- A Python/FastAPI Uvicorn server (src/backend/base/langflow + server.py)
- Background workers (Celery) for executing flows
- A relational database (Postgres via SQLAlchemy + Alembic migrations)
- An optional object storage (local disk or S3)
- External integrations (LLM APIs, vector DBs, telemetry, etc.)
- The README highlights visual flow authoring, built-in API server, multi-agent orchestration, and “deploy as API” capabilities.

##### File structure
- Top level:
- src/frontend → React SPA, Vite, custom nodes/components, Cypress/Playwright tests
- src/backend → FastAPI app, routers, services, models, Celery config, workers, scripts
- deploy/docker/docker_example → Docker Compose files for self-managed deployment
- scripts/aws and scripts/gcp → IaC (AWS CDK, GCP shell scripts)
- Patterns:
- MVC-like layering: routers → services → database models
- Asynchronous tasks via Celery (core/celery_app.py + services/task/backends)
- Infrastructure as code (CDK) and containerization (Dockerfiles per component).

##### README for additional insights
- Docs refer to “visual builder” (frontend), “built-in API server” (backend FastAPI), “background tasks” (flow execution), and “vector databases”/“LLM providers” (external services).

##### Main components
a. Frontend SPA
- React/TypeScript app served by Nginx (docker/frontend/nginx.conf)
- Communicates over REST/WebSocket with backend
b. API Server
- FastAPI app (main.py, server.py)
- Exposes HTTP endpoints (api/v1, api/v2) and WebSocket for playground
- Handles authentication, file management, user management, flow CRUD
c. Task Queue & Workers
- Celery broker (Redis or RabbitMQ)
- Celery workers (celery_app.py, core tasks) execute flow graphs
d. Database
- Postgres (SQLAlchemy models in services/database/models + Alembic migrations)
e. Storage
- Local disk or AWS S3 for file uploads (services/storage)
f. External Services
- LLM providers (OpenAI, Anthropic, etc.)
- Vector stores (Chroma, Pinecone, etc.)
- Telemetry/tracing (LangSmith, LangFuse)

##### Relationships and interactions
- Frontend → Backend: HTTP/HTTPS requests & WebSocket
- Backend → Database: SQL queries via ORM
- Backend → Broker: publish tasks to Celery broker
- Workers → External LLMs/Vector DBs: HTTP/SDK calls
- Backend → Storage: read/write file objects
- Backend/Workers → Telemetry APIs

##### Architectural patterns and design principles
- Layered architecture: Controllers (routers) → Domain services → Data access
- Asynchronous processing: Task queue pattern for long-running flows
- Containerized micro-services: Separate containers for frontend, API, workers, broker, database
- Infrastructure as Code: CDK stacks define VPC, ECS/ECR or Lambda deployments

##### Relevant technologies
- Frontend: React, Zustand, React-Flow, TypeScript, Vite, Playwright/Cypress
- Backend: Python 3.10+, FastAPI, Uvicorn, Pydantic, SQLAlchemy, Alembic, Celery
- Broker: Redis or RabbitMQ
- Database: Postgres
- Storage: Local FS or S3
- IaC: AWS CDK (TypeScript), GCP deploy scripts
- Containerization: Docker, Docker Compose

##### Essential details
- API’s dual role: responding synchronously and dispatching asynchronous flows
- Pluggable integrations layer (components/*.py) and vector store abstractions

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    subgraph "User & Browser"
        direction TB
        Browser["User Browser"]:::external
    end

    %% Frontend Layer
    subgraph "Frontend Container" 
        direction TB
        NGINX["Nginx"]:::frontend
        ReactApp["React/TypeScript SPA"]:::frontend
    end

    %% API Layer
    subgraph "API Server (FastAPI)" 
        direction TB
        APIServer["FastAPI/Uvicorn"]:::backend
        Routers["API Routers"]:::backend
        Schemas["Request/Response Schemas"]:::backend
    end

    %% Worker Layer
    subgraph "Workers & Broker"
        direction TB
        Broker["Celery Broker\n(Redis/RabbitMQ)"]:::worker
        Worker["Celery Workers"]:::worker
    end

    %% Data Layer
    subgraph "Database & Storage"
        direction TB
        Postgres["Postgres DB"]:::database
        Storage["Object Storage\n(Local/S3)"]:::storage
    end

    %% Integrations
    subgraph "External Services"
        direction TB
        LLM["LLM Providers"]:::external
        VectorDB["Vector Stores"]:::external
        Telemetry["Telemetry/Tracing"]:::external
    end

    %% Connections
    Browser -->|"HTTP/WS"| NGINX
    NGINX --> ReactApp
    ReactApp -->|"REST/WebSocket"| APIServer
    APIServer --> Routers
    Routers --> Schemas
    APIServer -->|"SQL via ORM"| Postgres
    APIServer -->|"Publish Tasks"| Broker
    APIServer -->|"Read/Write Files"| Storage
    APIServer -->|"Telemetry Data"| Telemetry

    Broker --> Worker
    Worker -->|"LLM Calls"| LLM
    Worker -->|"Vector DB Calls"| VectorDB
    Worker -->|"Telemetry Data"| Telemetry

    %% Click Events - Frontend
    click NGINX "https://github.com/tonikiri666/langflow/blob/main/docker/frontend/nginx.conf"
    click ReactApp "https://github.com/tonikiri666/langflow/tree/main/src/frontend"
    click ReactApp "https://github.com/tonikiri666/langflow/tree/main/src/frontend/Dockerfile"

    %% Click Events - API Server
    click APIServer "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/server.py"
    click APIServer "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/__main__.py"
    click Routers "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/api/router.py"
    click Routers "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/api/v1"
    click Routers "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/api/v2"
    click Schemas "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/api/schemas.py"
    click Schemas "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/api/v1/schemas.py"

    %% Click Events - Workers
    click Worker "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/core/celery_app.py"
    click Worker "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/core/celeryconfig.py"
    click Worker "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/worker.py"
    click Worker "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/task/backends/celery.py"

    %% Click Events - Database
    click Postgres "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/services/database/models"
    click Postgres "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/database/service.py"
    click Postgres "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/database/factory.py"
    click Postgres "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/alembic"

    %% Click Events - Storage
    click Storage "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/storage/service.py"
    click Storage "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/storage/factory.py"
    click Storage "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/storage/local.py"
    click Storage "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/storage/s3.py"

    %% Click Events - Integrations
    click LLM "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/components"
    click LLM "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/base/models"
    click LLM "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/base/langchain_utilities"
    click VectorDB "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/base/vectorstores"
    click VectorDB "https://github.com/tonikiri666/langflow/tree/main/src/backend/base/langflow/components/vectorstores"
    click Telemetry "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/telemetry/opentelemetry.py"
    click Telemetry "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/tracing/langsmith.py"
    click Telemetry "https://github.com/tonikiri666/langflow/blob/main/src/backend/base/langflow/services/tracing/langfuse.py"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#0366d6,stroke-width:1px
    classDef backend fill:#DFFFE0,stroke:#22863a,stroke-width:1px
    classDef worker fill:#FFEFD0,stroke:#d1860b,stroke-width:1px
    classDef database fill:#FFF5B1,stroke:#bf8700,stroke-width:1px
    classDef storage fill:#FFF5B1,stroke:#bf8700,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#6a737d,stroke-width:1px
```
