# bahakizil/flows architecture

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

- Interactive diagram: https://gitdiagram.com/bahakizil/flows
- Repository: https://github.com/bahakizil/flows

## Overview

##### Project Type & Purpose
- This is a full-stack AI Workflow Builder.
- Frontend: React + ReactFlow + TypeScript + Zustand
- Backend: Python FastAPI + LangChain + Celery + Supabase (PostgreSQL + Auth)
- Purpose: Visual drag-and-drop workflow editor with real-time execution, streaming results, and a pluggable node system.

##### File Structure
- Top-Level
- .github/workflows: CI pipelines for backend (Python) and frontend (TypeScript)
- docker-compose.yml: orchestrates front-end, back-end, database, worker
- supabase/: DB schema & migrations
- backend/
- app/api: REST endpoints (auth, workflows, nodes, credentials, executions, SSE)
- app/auth: Supabase Auth integration, JWT middleware
- app/core: Workflow engine (graph_builder, engine_v2, auto_connector), Celery app, config, state management
- app/models & schemas: Pydantic models for data validation
- app/nodes: 18+ plugin-style node implementations (LLMs, chains, tools, memories, retrievers, vectorstores, etc.)
- app/services: Business logic (user, workflow, execution, credential)
- app/tasks: Celery tasks for asynchronous workflow execution & monitoring
- client/ (aiagent/client)
- app/components: UI (canvas, nodes, common components, modals, dashboard)
- app/routes: Page components (canvas, workflows, credentials, executions, auth)
- app/lib: HTTP API client, SSE hook
- app/services & app/stores: Frontend service layer + Zustand state management
- supabase/: Database schema & migrations

##### README Insights
- Real-time SSE streaming endpoint
- Dynamic node discovery & auto-registration
- Docker Compose for local & production
- Supabase Auth with RLS for per-user credential vault

##### Main Components & Interactions
a. Presentation Layer (Frontend UI)
- React App (3000/5173)
- ReactFlow Canvas + Node Palette + Modals
- Zustand for state (nodes, workflows, auth)
b. API Layer (FastAPI Backend)
- Authentication Endpoints → Supabase Auth
- Nodes Endpoint → Dynamic discovery via node_registry
- Workflow CRUD & Execute Endpoints → orchestrates engine + tasks
- SSE Endpoint → stream token-by-token execution results
c. Business & Core Engine
- Services (user, workflow, execution)
- Core Engine builds directed graph, applies LangChain chains, loops, conditionals
- Celery Worker executes workflows asynchronously, checkpoints state, publishes to SSE
d. Data Layer
- Supabase PostgreSQL: workflows, users, credentials, sessions
- RLS Policies guard per-user data
- Redis (optional) for caching & Celery broker/backend
e. External Services
- LangChain integrations: OpenAI, Cohere, Anthropic, Google Gemini
- Vectorstores: Chroma, FAISS, Pinecone, Qdrant, Weaviate
- Tools & APIs: Google Search, Wikipedia, Tavily, WolframAlpha
- Document Loaders: PDF, Web, YouTube, GitHub

##### Architectural Patterns & Principles
- Layered Architecture: Presentation → API → Services → Core Engine → Data
- Plugin Pattern: Nodes auto-registered via node_registry
- Event-Driven: Celery tasks + SSE streaming for real-time updates
- Separation of Concerns: Authentication, business logic, engine, persistence are distinct
- Containerization: Each layer runs in its own Docker container

##### Detail & Granularity
- Break into sub-components: e.g., within “Engine” show GraphBuilder, NodeRegistry, Checkpointer
- Both synchronous flows (login, CRUD) and asynchronous flows (workflow execution via Celery + SSE)
- 18+ node categories abstractly under “Node Plugins”

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User & Browser"
        User["User"]:::user
        Browser["Browser"]:::browser
    end

    User-->Browser

    subgraph "Frontend (React)" 
        direction TB
        Canvas["ReactFlow Canvas"]:::frontend
        UICommon["UI Components (common)"]:::frontend
        AuthGuard["AuthGuard"]:::frontend
        Modals["Node Configuration Modals"]:::frontend
        NodeRender["Node Renderers"]:::frontend
        Routes["Frontend Routes"]:::frontend
        APIClient["API Client & SSE Hook"]:::frontend
        StateStore["Zustand Stores"]:::frontend
        FrontServices["Frontend Services"]:::frontend
    end

    Browser-->AuthGuard
    AuthGuard-->Routes
    Browser-->Canvas
    Browser-->Routes
    Canvas-->APIClient
    Routes-->APIClient
    APIClient-->FrontServices
    FrontServices-->StateStore
    StateStore-->Canvas
    StateStore-->NodeRender

    subgraph "Backend (FastAPI)" 
        direction TB
        API["FastAPI /api/v1"]:::api
        Auth["Supabase Auth Integration & JWT"]:::api
        DBAccess["DB Access"]:::api
    end

    API-->Auth
    API-->DBAccess

    subgraph "Core Engine & Tasks"
        direction TB
        GraphBuilder["GraphBuilder"]:::core
        NodeRegistry["NodeRegistry & Discovery"]:::core
        AutoConnector["AutoConnector"]:::core
        Checkpointer["Checkpointer"]:::core
        Engine["Workflow Engine"]:::core
        CeleryApp["Celery App"]:::core
        Tasks["Celery Tasks"]:::core
        Services["Business Logic Services"]:::core
    end

    API-->Services
    Services-->Engine
    Engine-->GraphBuilder
    Engine-->NodeRegistry
    NodeRegistry-->AutoConnector
    Engine-->Checkpointer
    Engine-->CeleryApp
    CeleryApp-->Tasks
    Tasks-->Engine
    Tasks-->Checkpointer
    Tasks-->|gRPC/Redis|RedisBroker

    subgraph "Data Stores"
        direction TB
        SupaDB["Supabase PostgreSQL"]:::db
        RedisBroker["Redis (Broker & Cache)"]:::db
    end

    DBAccess-->SupaDB
    RedisBroker-->Tasks

    subgraph "External AI & Vector Services"
        direction TB
        AI["External AI Services"]:::external
        VStore["Vectorstores & Tools"]:::external
    end

    Engine-->AI
    Engine-->VStore

    Canvas-->|"SSE"|API
    API-->|"SSE"|Canvas

    %% Click events
    click Canvas "https://github.com/bahakizil/flows/blob/main/client/app/components/canvas/FlowCanvas.tsx"
    click UICommon "https://github.com/bahakizil/flows/tree/main/client/app/components/common"
    click AuthGuard "https://github.com/bahakizil/flows/blob/main/client/app/components/AuthGuard.tsx"
    click Modals "https://github.com/bahakizil/flows/tree/main/client/app/components/modals"
    click NodeRender "https://github.com/bahakizil/flows/tree/main/client/app/components/nodes"
    click Routes "https://github.com/bahakizil/flows/tree/main/client/app/routes"
    click APIClient "https://github.com/bahakizil/flows/blob/main/client/app/lib/api-client.ts"
    click APIClient "https://github.com/bahakizil/flows/blob/main/client/app/lib/useSSE.ts"
    click StateStore "https://github.com/bahakizil/flows/blob/main/client/app/stores/auth.ts"
    click StateStore "https://github.com/bahakizil/flows/blob/main/client/app/stores/nodes.ts"
    click StateStore "https://github.com/bahakizil/flows/blob/main/client/app/stores/workflows.ts"
    click FrontServices "https://github.com/bahakizil/flows/blob/main/client/app/services/auth.ts"
    click FrontServices "https://github.com/bahakizil/flows/blob/main/client/app/services/nodes.ts"
    click FrontServices "https://github.com/bahakizil/flows/blob/main/client/app/services/workflows.ts"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/main.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/auth.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/workflows.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/nodes.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/executions.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/credentials.py"
    click API "https://github.com/bahakizil/flows/blob/main/backend/app/api/tasks.py"
    click Auth "https://github.com/bahakizil/flows/blob/main/backend/app/auth/supabase_client.py"
    click Auth "https://github.com/bahakizil/flows/blob/main/backend/app/auth/middleware.py"
    click Auth "https://github.com/bahakizil/flows/blob/main/backend/app/auth/dependencies.py"
    click GraphBuilder "https://github.com/bahakizil/flows/blob/main/backend/app/core/graph_builder.py"
    click NodeRegistry "https://github.com/bahakizil/flows/blob/main/backend/app/core/node_registry.py"
    click NodeRegistry "https://github.com/bahakizil/flows/blob/main/backend/app/core/node_discovery.py"
    click AutoConnector "https://github.com/bahakizil/flows/blob/main/backend/app/core/auto_connector.py"
    click Checkpointer "https://github.com/bahakizil/flows/blob/main/backend/app/core/checkpointer.py"
    click CeleryApp "https://github.com/bahakizil/flows/blob/main/backend/app/core/celery_app.py"
    click Engine "https://github.com/bahakizil/flows/blob/main/backend/app/core/engine_v2.py"
    click Services "https://github.com/bahakizil/flows/blob/main/backend/app/services/user_service.py"
    click Services "https://github.com/bahakizil/flows/blob/main/backend/app/services/workflow_service.py"
    click Services "https://github.com/bahakizil/flows/blob/main/backend/app/services/execution_service.py"
    click Services "https://github.com/bahakizil/flows/blob/main/backend/app/services/credential_service.py"
    click Services "https://github.com/bahakizil/flows/blob/main/backend/app/services/task_service.py"
    click Tasks "https://github.com/bahakizil/flows/blob/main/backend/app/tasks/workflow_tasks.py"
    click Tasks "https://github.com/bahakizil/flows/blob/main/backend/app/tasks/monitoring_tasks.py"
    click SupaDB "https://github.com/bahakizil/flows/tree/main/supabase/"
    click RedisBroker "https://github.com/bahakizil/flows/blob/main/docker-compose.yml"

    classDef user fill:#a2d2ff,stroke:#000
    classDef browser fill:#bde0fe,stroke:#000
    classDef frontend fill:#90e0ef,stroke:#000
    classDef api fill:#8ac926,stroke:#000
    classDef core fill:#ffba08,stroke:#000
    classDef db fill:#8338ec,stroke:#000
    classDef external fill:#adb5bd,stroke:#000
```
