How bahakizil/flows works
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”