# x-dify

**Repository Path**: chain-engine/x-dify

## Basic Information

- **Project Name**: x-dify
- **Description**: 一个基于 Dify 的工作流编排平台
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-19
- **Last Updated**: 2026-06-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# x-dify

## Project Introduction

A workflow orchestration platform based on Dify, providing core capabilities such as LLM conversation, multi-node process orchestration, task scheduling automation, and API orchestration and integration. Through standardized API interfaces and visual management interfaces, it helps enterprises quickly build intelligent workflow applications.

## Core Features

- **LLM Conversation Workflow**: Multi-turn conversations based on large models, RAG retrieval-augmented generation
- **Task Scheduling Automation**: Scheduled triggering, event-driven task scheduling and execution
- **Multi-node Process Orchestration**: Support for complex process controls such as conditional branching, loops, and parallelism
- **API Orchestration and Integration**: Orchestration capabilities connecting external APIs, databases, and third-party services
- **Production-grade Architecture**: Enterprise-level application architecture supporting high concurrency, scalability, and maintainability
- **Standardized API**: Follows RESTful specifications, providing OpenAPI documentation
- **Configuration Center**: Supports .env + config.yaml dual configuration system, multi-environment switching

## Project Structure

```
x-dify/
├── .env.example                # Environment variable template
├── config.yaml                 # Main configuration file (YAML 格式)
├── pyproject.toml              # Project configuration (recommended with uv)
├── uv.lock                     # Dependency lock file
├── uv.toml                     # uv configuration file
├── .python-version             # Python version specification
├── Dockerfile                  # Docker deployment file
├── src/                        # Core business code
│   ├── core/                   # Core modules
│   │   ├── config.py           # Configuration center (dual system: .env + config.yaml)
│   │   ├── logger.py           # Logging configuration
│   │   ├── exceptions.py       # Global exception definitions
│   │   ├── middleware.py       # Middleware definitions
│   │   ├── responses.py        # Response standardization tools
│   │   └── schemas.py          # Data models and Schema

│   ├── models/                 # Data models
│   │   └── schemas.py          # Pydantic request/response models
│   ├── services/               # External service calls
│   │   └── dify_client.py      # Dify API client (conversation, workflow, logs)
│   ├── workflows/              # Workflow orchestration engine
│   │   ├── engine.py           # Execution engine (multi-node orchestration, LLM/HTTP/conditional branches)
│   │   └── manager.py          # Workflow CRUD management
│   ├── scheduler/              # Task scheduling
│   │   └── task_scheduler.py   # Cron scheduled scheduler
│   ├── api/                    # API layer
│   │   ├── middleware/         # Middleware
│   │   │   ├── cors.py         # CORS cross-origin
│   │   │   ├── error_handler.py # Global exception handling
│   │   │   └── rate_limiter.py # Request rate limiting (token bucket)
│   │   └── routes/             # Routes
│   │       ├── health.py       # Health check + version interface
│   │       ├── chat.py         # Dify conversation interface
│   │       ├── workflow.py     # Workflow management interface
│   │       └── scheduler.py    # Task scheduling interface
│   ├── utils/                  # Utility functions
│   │   └── helpers.py
│   └── main.py                 # FastAPI main entry point
├── examples/                   # Usage examples
│   └── workflow_example.py     # Workflow call example
├── tests/                      # Test directory (to be filled)
├── scripts/                    # Deployment scripts
│   ├── start.sh                # Linux startup script
│   └── start.bat               # Windows startup script
├── docs/                       # Project documentation
├── .gitignore
├── LICENSE
├── README.md
├── README.en.md
├── pyproject.toml              # Project configuration (recommended with uv)
├── uv.lock                   # Dependency lock file
└── Dockerfile                  # Docker deployment file
```

## System Architecture

### System Layer Architecture Diagram

```mermaid
graph TB
    subgraph "Client Layer"
        A[Web UI] --> B[Mobile App]
        C[API Client] --> B
    end
    
    subgraph "API Gateway Layer"
        D[FastAPI] --> E[CORS Middleware]
        D --> F[Rate Limiter]
        D --> G[Error Handler]
    end
    
    subgraph "Business Logic Layer"
        H[Workflow Engine] --> I[Dify Client]
        J[Task Scheduler] --> K[Workflow Manager]
        L[Chat Service] --> I
    end
    
    subgraph "Data Model Layer"
        M[Pydantic Models] --> N[Request Validation]
        M --> O[Response Standardization]
    end
    
    subgraph "External Service Layer"
        P[Dify Platform] --> Q[LLM Services]
        R[Database] --> S[Redis Cache]
    end
    
    A --> D
    B --> D
    C --> D
    D --> H
    D --> J
    D --> L
    H --> M
    J --> M
    L --> M
    I --> P
    K --> R
```

### Core Function Business Process Diagram

```mermaid
sequenceDiagram
    participant Client as Client
    participant API as API Gateway
    participant Engine as Workflow Engine
    participant Dify as Dify Service
    participant LLM as LLM Service

    Client->>API: Initiate workflow execution request
    API->>Engine: Parse and validate request
    Engine->>Engine: Execute node orchestration logic
    loop Each LLM Node
        Engine->>Dify: Call Dify conversation API
        Dify->>LLM: Execute LLM inference
        LLM-->>Dify: Return inference result
        Dify-->>Engine: Return conversation result
    end
    Engine->>API: Return workflow execution result
    API-->>Client: Return final response
```

### Module Dependency Relationship Diagram

```mermaid
graph LR
    A[src/main.py] --> B[FastAPI]
    A --> C[Config]
    A --> D[Logger]
    
    C --> E[config.yaml]
    C --> F[.env]
    
    B --> G[API Routes]
    G --> H[Health]
    G --> I[Chat]
    G --> J[Workflow]
    G --> K[Scheduler]
    
    J --> L[Workflow Engine]
    J --> M[Workflow Manager]
    L --> N[Dify Client]
    M --> L
    
    K --> O[Task Scheduler]
    O --> L
    
    P[Pydantic Models] --> H
    P --> I
    P --> J
    P --> K
```

## Quick Start

### ① Environment Requirements

#### Windows
- Python 3.11+
- pip
- Git

#### Linux
- Python 3.11+
- pip
- Git
- virtualenv (optional)

### ② Project Clone

```bash
git clone https://gitee.com/your-repo/x-dify.git
cd x-dify
```

### ③ Dependency Installation

```bash
# Install uv (if not already installed)
pip install uv

# Using pyproject.toml (recommended)
# Sync project dependencies directly
uv sync
# Or install only runtime dependencies
uv sync --no-dev
```

### ④ Configuration File Creation

Copy the configuration file template:

```bash
copy .env.example .env
```

Edit the `.env` file and configure the following parameters:

```env
# Dify Configuration
DIFY_BASE_URL=http://localhost/v1
DIFY_API_KEY=your-dify-api-key-here

# Database Configuration (optional)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=xdify
DB_USER=your-db-user
DB_PASSWORD=your-db-password

# Redis Configuration (optional)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=
```

### ⑤ Service Startup

#### 1. Local Development Mode Startup

```bash
# Ensure virtual environment is activated
# Run with uv (recommended)
uv run python -m src.main
# Or run directly
python -m src.main
```

The service will start at `http://localhost:8000`, supporting hot reloading and debugging mode.

#### 2. Docker Containerized Deployment

First create Dockerfile:

```dockerfile
FROM python:3.11-slim

# Install uv
RUN pip install uv

WORKDIR /app

COPY pyproject.toml .
COPY uv.lock .
RUN python -m uv sync --no-dev

COPY . .

EXPOSE 8000

CMD ["python", "-m", "src.main"]
```

Then deploy using Docker Compose:

```yaml
version: '3.8'

services:
  x-dify:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "8000:8000"
    environment:
      - APP_ENV=production
      - DIFY_BASE_URL=${DIFY_BASE_URL}
      - DIFY_API_KEY=${DIFY_API_KEY}
    volumes:
      - ./config.yaml:/app/config.yaml
      - ./.env:/app/.env
      - ./logs:/app/logs
    restart: unless-stopped
```

When deploying with Docker Compose, ensure the following files are copied to the container:
- pyproject.toml
- uv.lock
- .env (if exists)
- config.yaml
- src/ (source code directory)

### ⑥ Common Commands

```bash
# Start service
python -m src.main
# Or using uv
uv run python -m src.main

# Run tests
pytest tests/
# Or using uv
uv run pytest tests/

# Code formatting
uv run black src/

# Code checking
uv run flake8 src/
```

## Tech Stack

### Dependency Management
- uv: Fast Python package installer and project manager

### Web Framework
- FastAPI: Modern high-performance web framework
- Uvicorn: ASGI server

### Data Validation & Configuration Management
- Pydantic: Data validation and settings management
- Pydantic Settings: Configuration management extension
- Python-dotenv: Environment variable loading

### HTTP Client
- Httpx: Modern asynchronous HTTP client

### Logging Management
- Loguru: Modern logging library

### Configuration Parsing
- PyYAML: YAML configuration file parsing

### Task Scheduling
- APScheduler: Advanced Python scheduler

### Development & Testing
- Pytest: Testing framework
- Pytest-asyncio: Asynchronous testing support

## API Documentation

- Swagger UI Interactive API Documentation: [http://localhost:8000/docs](http://localhost:8000/docs)
- ReDoc Read-only API Documentation: [http://localhost:8000/redoc](http://localhost:8000/redoc)
- OpenAPI JSON Documentation: [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json)

## Storage Configuration

### Local Storage
- Log files stored in `logs/` directory
- Configuration files stored in `config/` directory

### Object Storage
- Object storage functionality integrated through Dify service
- Supports multiple object storage services like Alibaba Cloud OSS, AWS S3, etc.

## License

This project is licensed under the [LICENSE](./LICENSE) license.

## References

- [uv Official Documentation](https://docs.astral.sh/uv/)
- [FastAPI Official Documentation](https://fastapi.tiangolo.com/)
- [Python Official Documentation](https://docs.python.org/3/)
- [Pydantic Official Documentation](https://docs.pydantic.dev/)
- [Dify Official Documentation](https://docs.dify.ai/)

## Contact Information

- Author: John Young
- Online Nickname: 夜雨诗来 (Night Rain Poetry Comes)
- Email: john.young@foxmail.com
- Gitee: [https://gitee.com/yeyushilai](https://gitee.com/yeyushilai)
- GitHub: [https://github.com/yeyushilai](https://github.com/yeyushilai)