# onelevenvy/flock architecture

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

- Interactive diagram: https://gitdiagram.com/onelevenvy/flock
- Repository: https://github.com/onelevenvy/flock

## Overview

Based on our analysis of the file structure and the README, we can see that Flock is a full-stack, workflow-based low-code platform designed for orchestrating collaborative agents. It supports complex workflows (like chatbots, RAG applications, and multi-agent systems) built on top of LangChain and LangGraph. The project is split into at least two major segments:

##### Backend (located under the “backend” directory)
- Built with Python and FastAPI; uses Uvicorn for serving the API.
- Contains model provider plugins (e.g., OpenAI, Google, Ollama, Qwen, ZhipuAI, Siliconflow) that enable the platform to interact with various external AI models.
- Uses Celery for asynchronous processing (especially for RAG features) and Alembic for database migrations.
- Manages dependencies like PostgreSQL (and likely Redis and Qdrant for messaging/search in the middleware docker compose) which are part of the ecosystem.

##### Frontend (located under the “web” directory)
- A React/Next.js application that leverages Chakra UI with custom components for dashboards, workflow visualization, chatbots, and settings.
- Provides the user interface for interacting with and visualizing workflows (including flow editors with nodes, connections, and detailed modals).
- Integrates with the backend using an OpenAPI-generated client (evident by extensive “client” modules) and uses modern state management (e.g., Contexts and Stores).

a. Main Architectural Components:
- Frontend UI Layer:
- Next.js/React application: Present its key routes (login, dashboard, workflow editor, settings) and its role as the consumer of backend APIs.
- Client SDK: Represents modules for handling API requests (in the “web/src/client” folder) and models.

- Backend API Service:
- API endpoints organized in “backend/app/api” (various route files for login, users, providers, workflows, etc.).
- Modular Workflow Engine: Highlight the internal workflow core (nodes, graph components, etc.) that facilitate various workflow operations.
- Model Provider Plugins: Represent the plugin architecture (under “app/core/model_providers” and “app/core/model_provider_plugins”) which allows integrating multiple AI models.

- Asynchronous Task Processing:
- Celery Worker Service: Illustrate the background processing of tasks (e.g., for RAG functions).

- Persistence and External Services:
- Database: PostgreSQL for persistence (with Alembic migrations), depicted as a storage component.
- Optional Components: Redis, Qdrant, and any other middleware (containerized in the docker-compose middleware setups) for caching, message brokering, or vector search.

- Docker and Deployment Components:
- Containerization: Show Docker deployment artifacts for both frontend and backend.
- “docker” folder elements and compose files which orchestrate services (frontend, backend, middleware).

b. Component Relationships and Data Flow:
- Backend interacting with the Database, and optionally with external services (plugins and tools providers).
- How the Model Provider Plugins interface with external AI services and how the platform retrieves and augments data using retrieval modules (RAG) and tool invocations.

c. Architectural Patterns and Design Principles:
- Modular Design & Extensibility:
- Pluggable model provider and tool systems.
- Demonstrate the separation of concerns between API routes, core workflow logic, and external integrations.
- Low-Code Workflow Orchestration:
- Internal workflow node framework (with various specialized node types) that let users create complex workflows visually.
- Microservices/Docker-based Deployment:
- Usage of Docker Compose to deploy distinct service components (frontend, backend, middleware).

d. Technologies and Frameworks:
- For the Frontend: React, Next.js, Chakra UI, TypeScript.
- For the Backend: Python 3.12, FastAPI, Uvicorn, Poetry, Alembic, Celery.
- For Data and Messaging: PostgreSQL, Redis (and Qdrant for vector search if used).
- Additional libraries: LangChain and LangGraph for workflow orchestration, and integration with various AI model providers.

- Separation of the full-stack application:
- Clearly delineate the frontend component with its user interaction for workflow editing and chat operations.
- Backend component as the core processing unit that integrates REST APIs with workflow orchestration.
- Extensible workflow system:
- How these nodes interact internally and depend on external models/services.
- For asynchronous and integration aspects:
- Don’t miss out on showcasing how Celery workers function as background processors.

- Component Labels: Each component (Frontend UI, API Gateway, Workflow Engine/Core, Database, Asynchronous Worker, External Service Integrations) should be clearly labeled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend UI Layer
    subgraph "Frontend UI Layer"
        F1("UI (Next.js/React, Login, Dashboard, Workflow Editor, Settings)"):::frontend
        F2("Client SDK"):::frontend
    end

    %% Backend Services
    subgraph "Backend Services"
        B1("API Gateway"):::backend
        B2("Workflow Engine (Nodes: Input,LLM,Retrieval,Tool,Subgraph)"):::backend
        subgraph "Model Providers"
            B3("Model Provider Plugins"):::backend
            B3a("Model Provider Modules"):::backend
        end
        B4("Asynchronous Task Processing (Celery)"):::backend
        subgraph "Persistence Layer"
            B5a("Alembic Config"):::database
            B5b("Database (PostgreSQL)"):::database
        end
        B6("External Services (Redis, Qdrant)"):::external
    end

    %% Deployment Components
    subgraph "Deployment"
        D1("Docker Deployment (General)"):::deployment
        D2("Backend Docker"):::deployment
    end

    %% Connections between Frontend layers
    F1 -->|"uses"| F2
    F2 -->|"REST_call"| B1

    %% Connections within Backend
    B1 -->|"triggers"| B2
    B1 -->|"integrates"| B3
    B1 -->|"integrates"| B3a
    B1 -->|"queries"| B5b
    B2 -->|"async_task"| B4
    B1 -->|"utilizes"| B6

    %% Deployment relationships
    D1 -->|"hosts"| F1
    D1 -->|"hosts"| F2
    D2 -->|"hosts"| B1
    D2 -->|"hosts"| B2
    D2 -->|"hosts"| B3
    D2 -->|"hosts"| B4

    %% Click events for mapped components
    click F1 "https://github.com/onelevenvy/flock/tree/main/web"
    click F2 "https://github.com/onelevenvy/flock/tree/main/web/src/client"
    click B1 "https://github.com/onelevenvy/flock/tree/main/backend/app/api"
    click B2 "https://github.com/onelevenvy/flock/tree/main/backend/app/core/workflow"
    click B3 "https://github.com/onelevenvy/flock/tree/main/backend/app/core/model_provider_plugins"
    click B3a "https://github.com/onelevenvy/flock/tree/main/backend/app/core/model_providers"
    click B4 "https://github.com/onelevenvy/flock/blob/main/backend/app/core/celery_app.py"
    click B5a "https://github.com/onelevenvy/flock/blob/main/backend/alembic.ini"
    click B5b "https://github.com/onelevenvy/flock/blob/main/backend/app/core/database.py"
    click D1 "https://github.com/onelevenvy/flock/tree/main/docker"
    click D2 "https://github.com/onelevenvy/flock/tree/main/backend/docker"

    %% Styles/Classes
    classDef frontend fill:#a3c8f3,stroke:#333,stroke-width:2px;
    classDef backend fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef database fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef external fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef deployment fill:#d7bde2,stroke:#333,stroke-width:2px;
```
