Getting Started
Architecture
Understand how ConvoFlow is structured and how components interact.
ConvoFlow follows a modular architecture with clear separation between the frontend, backend, and core components. This architecture enables easy customization and extension.
System Overview
Frontend
Next.js React UI
Backend
FastAPI Python API
Database
PostgreSQL
Project Structure
bash
convoflow-v2/
├── frontend/ # Next.js React frontend
│ ├── app/ # Next.js app router pages
│ │ ├── page.tsx # Home page (workflow dashboard)
│ │ └── workflow/ # Workflow builder page
│ ├── components/ # React components
│ │ ├── canvas/ # React Flow canvas components
│ │ └── workflow/ # Workflow-specific components
│ ├── hooks/ # Custom React hooks
│ │ ├── useWorkflowState.ts
│ │ ├── useWorkflowQueries.ts
│ │ └── useWorkflowExecution.ts
│ └── lib/ # Utility functions
│
├── backend/ # FastAPI Python backend
│ ├── api/ # API endpoints
│ │ └── v1/ # API version 1
│ │ ├── nodes.py # Node-related endpoints
│ │ └── workflows.py
│ ├── nodes/ # Workflow node implementations
│ │ ├── base_node.py # Base node class
│ │ ├── node_registry.py
│ │ ├── query_node/
│ │ ├── language_model_node/
│ │ └── ...
│ ├── tools/ # Utility tools and services
│ │ ├── language_model_tool/
│ │ ├── web_search_tool/
│ │ └── ...
│ ├── language_model_services/ # LLM integrations
│ ├── vector_store_services/ # Vector database services
│ └── main.py # Application entry point
│
└── docker-compose.yml # Docker configurationComponent Architecture
Frontend Architecture
The frontend is built with Next.js 16 using the App Router:
- Pages: Home dashboard and workflow builder
- Components: Reusable UI components for nodes, canvas, and workflow management
- Hooks: Custom React hooks for state management, data fetching, and workflow execution
- API Client: Functions to communicate with the backend API
Backend Architecture
The backend follows a modular structure:
- API Layer: FastAPI routes handling HTTP requests
- Node System: Base node class and node registry for managing workflow nodes
- Tools: Reusable utility classes for common operations
- Services: Integration with external services (LLMs, vector stores, etc.)
Data Flow
- User Interaction: User creates/edits workflow in the frontend
- Frontend State: React state manages nodes, edges, and workflow configuration
- API Request: Frontend sends workflow data to backend API
- Node Execution: Backend processes workflow, executing nodes in dependency order
- Tool Usage: Nodes use tools to perform operations (LLM calls, searches, etc.)
- Response: Backend returns execution results to frontend
- UI Update: Frontend displays results and updates workflow visualization
Node System
The node system is the core of ConvoFlow's extensibility:
python
BaseNode (Abstract Class)
├── _define_inputs() # Define node inputs
├── _define_outputs() # Define node outputs
├── _define_parameters() # Define configurable parameters
├── _define_styling() # Define visual styling
├── execute() # Core execution logic
└── get_schema() # Generate node schema
NodeRegistry
├── register_node() # Register a node class
├── create_node() # Create node instance
└── get_node_schema() # Get node schemaWorkflow Execution
When a workflow is executed:
- Workflow graph is parsed to build dependency map
- Nodes are executed in topological order (dependencies first)
- Each node receives inputs from connected upstream nodes
- Node executes its logic, potentially using tools
- Outputs are passed to connected downstream nodes
- Final result is returned from the ResponseNode
Extension Points
ConvoFlow provides several extension points:
- Custom Nodes: Create new node types by extending BaseNode
- Custom Tools: Create reusable tools for use in nodes
- Service Integrations: Add new LLM providers or vector stores
- UI Components: Customize node appearance and configuration UI
Was this page helpful?