Skip to main content

Architecture Overview

BoCoFlow is built with a modular, microservices-inspired architecture that separates concerns and enables independent development of components.

System Architecture​

┌─────────────────────────────────────────────┐
│           Electron Desktop App              │
│  ┌─────────────────────────────────────┐   │
│  │         React Web UI                 │   │
│  │    (bocoflow-web)                   │   │
│  └─────────────────────────────────────┘   │
│                    │                        │
│  ┌─────────────────────────────────────┐   │
│  │     Electron Main Process            │   │
│  │    (bocoflow-electron)              │   │
│  └─────────────────────────────────────┘   │
└─────────────────────────────────────────────┘
                     │
                     │ HTTP/REST
                     │
    ┌────────────────────────────────┐
    │      FastAPI Server             │
    │    (bocoflow-server)           │
    └────────────────────────────────┘
                     │
    ┌────────────────────────────────┐
    │      Workflow Engine            │
    │     (bocoflow-core)            │
    └────────────────────────────────┘
                     │
    ┌────────────────────────────────┐
    │   Python Environments (UV)      │
    │   - Node execution              │
    │   - Dependency isolation        │
    └────────────────────────────────┘

Component Overview​

bocoflow-core​

Purpose: Core workflow engine and node system

Key Features:

  • Workflow execution engine
  • Node base classes and interfaces
  • Parameter system for node configuration
  • Caching and dependency tracking
  • Status management

Technologies: Python 3.8+, NetworkX

bocoflow-server​

Purpose: REST API server for workflow operations

Key Features:

  • RESTful API endpoints
  • Workflow execution management
  • File operations and data handling
  • WebSocket support for real-time updates
  • Database integration

Technologies: FastAPI, Uvicorn, SQLAlchemy

bocoflow-web​

Purpose: React-based web user interface

Key Features:

  • Visual workflow editor (React Flow)
  • Node configuration panels
  • Real-time execution monitoring
  • File management interface
  • Responsive design

Technologies: React 18, TypeScript, React Flow, Material-UI

bocoflow-electron​

Purpose: Desktop application wrapper

Key Features:

  • Native desktop integration
  • UV package manager integration
  • Backend server lifecycle management
  • Auto-updater support
  • Cross-platform packaging

Technologies: Electron, TypeScript, electron-builder

bocoflow-docs​

Purpose: Documentation website

Key Features:

  • User guides and tutorials
  • API documentation
  • Architecture documentation
  • Contributing guidelines

Technologies: Docusaurus, React, MDX

Data Flow​

Workflow Execution​

  1. User Action: User designs workflow in the UI
  2. API Request: UI sends workflow to server via REST API
  3. Validation: Server validates workflow structure
  4. Execution: Core engine executes nodes in dependency order
  5. Results: Results streamed back to UI via WebSocket
  6. Storage: Results cached for future use

Node Execution​

  1. Preparation: Node parameters validated
  2. Environment: Python environment activated if specified
  3. Execution: Node's execute() method called
  4. Output: Results serialized and returned
  5. Caching: Results stored in cache database

Environment Management​

BoCoFlow uses UV (Astral's package manager) for Python environment management:

Benefits of UV​

  • Fast: 10-100x faster than pip
  • Reliable: Built-in dependency resolution
  • Isolated: Each environment is completely isolated
  • Cross-platform: Works on Windows, macOS, and Linux

Environment Structure​

bocoflow-server-env/
├── bin/           # Executables (Unix)
├── Scripts/       # Executables (Windows)
├── lib/           # Python packages
└── pyvenv.cfg     # Environment configuration

Communication Protocols​

REST API​

Primary endpoints:

  • POST /workflow/execute - Execute workflow
  • GET /workflow/status - Get execution status
  • POST /node/configure - Configure node parameters
  • GET /files/list - List workspace files
  • POST /files/upload - Upload data files

WebSocket​

Real-time communication for:

  • Execution progress updates
  • Log streaming
  • Error notifications
  • Status changes

Security Considerations​

Process Isolation​

  • Each node runs in a separate process
  • Environment variables are isolated
  • File system access is sandboxed to workspace

Authentication​

  • Desktop app: Local-only by default
  • Server deployment: JWT token authentication
  • API keys for remote execution

Extensibility​

Custom Nodes​

Developers can create custom nodes by:

  1. Extending the Node base class
  2. Defining input/output ports
  3. Implementing the execute() method
  4. Placing in the nodes directory

Plugin System (Planned)​

Future support for:

  • Node packages
  • UI extensions
  • Custom executors
  • Workflow templates

Performance Optimization​

Caching Strategy​

  • Result Caching: Node outputs cached by input hash
  • Dependency Tracking: Only re-execute changed nodes
  • Lazy Loading: Load data only when needed
  • Parallel Execution: Independent nodes run in parallel

Resource Management​

  • Memory Limits: Configurable per-node memory limits
  • Timeout Control: Execution timeouts prevent hanging
  • Queue Management: Job queue for resource allocation
  • Cleanup: Automatic cleanup of temporary files

Deployment Options​

Desktop (Primary)​

  • Self-contained Electron application
  • Includes embedded Python environment
  • No external dependencies required

Server​

  • Docker containerization
  • Kubernetes deployment support
  • Horizontal scaling capability
  • Load balancing for multiple workers

Cloud​

  • AWS/Azure/GCP deployment guides
  • Serverless function support (planned)
  • Cloud storage integration

Future Architecture Plans​

Planned Enhancements​

  1. Distributed Execution: Run nodes across multiple machines
  2. Workflow Marketplace: Share and discover workflows
  3. Version Control: Git-like workflow versioning
  4. Real-time Collaboration: Multiple users editing workflows
  5. GPU Support: CUDA/ROCm acceleration for compatible nodes

Modular Package System​

Future architecture will support:

  • Separate Python packages per node type
  • Dynamic environment creation
  • Dependency conflict resolution
  • Package versioning and updates

Development Workflow​

Repository Structure​

bocoflow/                    # Parent repository
├── bocoflow-core/           # Git submodule
├── bocoflow-server/         # Git submodule
├── bocoflow-web/            # Git submodule
├── bocoflow-electron/       # Git submodule
├── bocoflow-docs/           # Git submodule
└── dev-notes/               # Development documentation

Development Scripts​

Universal development script handles:

  • Environment setup
  • Dependency installation
  • Service orchestration
  • Hot reloading
  • Log aggregation

Contributing​

See our Contributing Guide for details on:

  • Development setup
  • Code style guidelines
  • Testing requirements
  • Pull request process