Related Pages

Related topics: System Architecture, Quick Start Guide

Project Introduction

Overview

Refly.ai is a comprehensive workflow automation platform designed for developers and creators. The platform enables users to build, schedule, and automate workflows through a visual canvas interface combined with AI-powered capabilities. Refly.ai provides integrations with popular development tools and supports programmatic access through REST APIs and a Command Line Interface (CLI).

Sources: README.md

Architecture

The platform follows a modular monorepo architecture with multiple packages organized under a unified structure.

Package Structure

Sources: packages/layout/README.md

Core Features

Visual Workflow Canvas

The workspace provides a drag-and-drop canvas interface for building workflows. Users can:

• Add and configure various node types including code artifacts
• Connect nodes to define workflow dependencies
• Preview artifacts and outputs directly within the canvas
• Share workflow configurations

graph TD
    A[User Canvas] --> B[Canvas Nodes]
    A --> C[Resource Import]
    A --> D[Integration Docs]
    B --> E[Code Artifact]
    B --> F[Skill Execution]
    E --> G[Renderer]
    F --> H[Action Steps]
    G --> I[Preview Output]

Sources: packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx

Layout System

The application provides two primary layout components:

PrimaryPageLayout: Used for main application pages

• Configuration options include title, actions, extra content
• Supports fixHeight, noPaddingY, noPaddingX options

SecondaryPageLayout: Designed for detail pages and sub-functional pages

• Includes title, description, and back button support
• Ideal for nested views and detail information

<PrimaryPageLayout>
  {({ context, onContextChange }) => (
    <>
      <PrimaryPageLayoutContextUpdater
        title="Page Title"
        actions={<Button>Action Button</Button>}
        deps={[]}
      />
      <div>Page Content</div>
    </>
  )}
</PrimaryPageLayout>

Sources: packages/layout/README.md

Scheduled Workflows

The platform supports scheduled workflow execution with configurable limits based on user subscription plans.

Sources: packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx

Template Marketplace

Refly.ai includes a template marketplace where users can publish and discover workflow templates. The platform rewards creators with discount vouchers for publishing templates.

Email Notification Flow:

graph LR
    A[User Publishes Template] --> B[Generate Voucher]
    B --> C{Locale Detection}
    C -->|zh| D[Chinese Email Template]
    C -->|en| E[English Email Template]
    D --> F[Send Email]
    E --> F
    F --> G[Creator Receives Discount]

Sources: apps/api/src/modules/voucher/voucher-email-templates.ts

Integrations

Claude Code Integration

After running refly init, skill files are installed to Claude Code's directory structure:

This enables AI assistants to:

• Understand Refly workflow concepts
• Use builder mode correctly
• Handle state transitions
• Output deterministic results

Sources: packages/cli/README.md

Webhook Support

The platform provides webhook integration capabilities with comprehensive error handling:

Sources: packages/ai-workspace-common/src/components/canvas/integration-docs/components/webhook-docs-tab.tsx

CLI Tool

The Refly CLI provides command-line access to workflow management:

Installation

npm install -g @refly/cli

Configuration

Configuration is stored in ~/.refly/config.json:

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Environment Variables

Key Commands

Sources: packages/cli/README.md

State Management

The application uses Zustand for state management across the workspace:

Import Resource Store: Manages modal visibility, file lists, image lists, and waiting list items.

interface ImportResourceState {
  importResourceModalVisible: boolean;
  extensionModalVisible: boolean;
  fileList: FileItem[];
  imageList: ImageItem[];
  selectedMenuItem: ImportResourceMenuItem;
  waitingList: WaitingListItem[];
  scrapeLinks: LinkMeta[];
}

Sources: packages/stores/src/stores/import-resource.ts

API Endpoint

The platform exposes a REST API at:

https://api.refly.ai

Public file access:

https://api.refly.ai/v1/drive/file/public/{fileId}

Sources: apps/api/src/modules/voucher/voucher-email-templates.ts

Internationalization

The platform supports multiple locales including:

• English (en)
• Chinese Simplified (zh-CN)
• Chinese Traditional (zh-TW, zh-HK)
• And other locales detected via browser settings

Language detection is used for:

• Email template selection
• UI text rendering
• User-facing notifications

Sources: apps/api/src/modules/voucher/voucher-email-templates.ts

Related Pages

Related topics: Project Introduction

Quick Start Guide

Overview

The Quick Start Guide provides developers and users with the essential steps to begin using Refly, an AI-powered workflow automation platform. This guide covers CLI installation, authentication, workflow creation using Builder mode, workflow execution, and core concepts necessary to start building automated workflows.

Refly's architecture consists of three primary layers: a Command Line Interface (CLI) for local development, a web-based workspace for visual workflow design, and a cloud API for execution and scheduling. The CLI enables developers to build workflows incrementally with local state management, while the web interface provides a graphical canvas for complex workflow design.

Sources: packages/cli/README.md:1-20

Prerequisites

Before starting with Refly, ensure the following requirements are met:

Sources: scripts/cli-deploy/README.md:1-30

Installation

Installing the CLI

The Refly CLI can be installed via npm or pnpm. After installation, initialize the CLI to set up configuration files and install skill files for Claude Code integration.

npm install -g @refly/cli
# or
pnpm add -g @refly/cli

Initializing the CLI

Run the initialization command to set up the CLI and install skill files:

refly init

This command performs the following actions:

1. Creates the configuration directory at ~/.refly/
2. Generates the initial config.json file
3. Installs skill files to ~/.claude/skills/refly/
4. Sets up command shortcuts if the commands directory exists

Sources: packages/cli/README.md:1-15

Authentication

Logging In

Authenticate with the Refly API using your API key:

refly login

This command stores your credentials in ~/.refly/config.json:

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Checking Authentication Status

Verify your authentication status and view current user information:

refly status
refly whoami

Environment Variables

Override default configuration using environment variables:

Sources: packages/cli/README.md:25-45

Core Concepts

Builder Mode

Builder mode enables incremental workflow construction with local state management. It uses a deterministic state machine to track workflow progress through defined stages.

graph TD
    IDLE["IDLE"] --> DRAFT["DRAFT"]
    DRAFT --> VALIDATED["VALIDATED"]
    VALIDATED --> COMMITTED["COMMITTED"]
    COMMITTED --> IDLE
    DRAFT --> IDLE
    
    style IDLE fill:#e1f5fe
    style DRAFT fill:#fff3e0
    style VALIDATED fill:#e8f5e9
    style COMMITTED fill:#c8e6c9

Workflow States

Sources: packages/cli/README.md:48-65

Workflow Components

Refly workflows consist of nodes and connections:

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:1-30

Building a Workflow

Starting a Builder Session

Begin a new workflow or edit an existing one:

refly builder start --name "my-workflow"

Adding Nodes

Add nodes to define workflow steps:

refly builder add-node --node '<json>'

Node JSON structure:

{
  "id": "node-001",
  "type": "agent",
  "config": {
    "model": "gpt-4",
    "prompt": "Analyze the input document"
  }
}

Connecting Nodes

Establish data flow between nodes:

refly builder connect --from "node-001" --to "node-002"

Viewing the Graph

Visualize the current workflow structure:

refly builder graph
refly builder graph --ascii

Validating the Workflow

Before committing, validate the workflow's DAG structure:

refly builder validate

This checks for:

• Circular dependencies
• Missing required inputs
• Invalid node configurations
• Orphan nodes without connections

Committing the Workflow

Save the validated workflow to the server:

refly builder commit

Aborting Changes

Discard all changes and return to IDLE state:

refly builder abort

Sources: packages/cli/README.md:47-80

Workflow Management

Creating Workflows

Create a workflow using the CLI:

refly workflow create --name "<name>" --spec '<json>'

Listing Workflows

View all available workflows:

refly workflow list [--limit N]

Retrieving Workflow Details

Get detailed information about a specific workflow:

refly workflow get <workflowId>

Editing Workflows

Modify an existing workflow:

refly workflow edit <workflowId> --ops '<json>'

Deleting Workflows

Remove a workflow from the system:

refly workflow delete <workflowId>

Sources: packages/cli/src/commands/workflow/index.ts:1-50

Workflow Execution

Running a Workflow

Execute a workflow with optional input data:

refly workflow run <workflowId> [--input '<json>']

Example with input:

refly workflow run wf-abc123 --input '{"documentUrl": "https://example.com/doc.pdf"}'

Monitoring Execution Status

Track the progress of a running workflow:

refly workflow run-status <runId>

Aborting Execution

Stop a running workflow:

refly workflow abort <runId>

Node Debugging

Test individual node types independently:

refly node types [--category <category>]
refly node run --type "<nodeType>" --input '<json>'

Sources: packages/cli/README.md:82-100

Scheduling Workflows

Workflows can be scheduled for automated execution using cron-based triggers.

Schedule Limits

Different plans have varying limits on scheduled workflows:

Managing Schedules

When scheduling limits are reached, users can:

1. View existing schedules
2. Disable unused schedules
3. Upgrade to a higher plan

The schedule management interface provides modals for viewing and deactivating schedules.

Sources: packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60

Local Development Setup

Quick Start Deployment

For developers with an existing repository clone:

./scripts/cli-deploy/quick-start.sh

This script performs:

1. Building the CLI package
2. Starting Docker services (PostgreSQL, Redis)
3. Running database migrations
4. Seeding global tools data
5. Starting the API server
6. Guiding through OAuth login
7. Generating an API key

Full Deployment

For a complete fresh deployment:

./scripts/cli-deploy/deploy-cli.sh

Deployment Options

Sources: scripts/cli-deploy/README.md:10-50

Error Handling

Common Error Codes

Builder State Transitions

The builder enforces strict state transitions:

graph LR
    A[IDLE] -->|start| B[DRAFT]
    B -->|validate| C[VALIDATED]
    C -->|commit| D[COMMITTED]
    B -->|abort| A
    C -->|abort| A
    D -->|start| B

Sources: packages/cli/README.md:100-120

Next Steps

After completing this quick start guide, explore the following topics:

1. Advanced Workflows - Implement conditional logic, loops, and parallel execution
2. Custom Nodes - Create reusable node types for specialized tasks
3. Integration APIs - Connect external services and APIs
4. Team Collaboration - Share workflows and manage permissions
5. Monitoring & Analytics - Track workflow performance and costs

Additional Resources

Related Pages

Related topics: Project Structure, API Modules

System Architecture

Overview

Refly is a modular AI workspace platform built with a distributed architecture that separates concerns across multiple packages. The system comprises a monorepo structure using pnpm workspaces, organized into application layers (API, web-core) and shared package libraries (canvas-common, stores, skill-template, ai-workspace-common, layout).

The architecture follows a modular design pattern where each package encapsulates specific functionality, enabling loose coupling between components while maintaining type-safe inter-package communication.

Package Architecture

The repository is organized into the following main packages:

Sources: packages/stores/src/stores/import-resource.ts:1-50

State Management Architecture

Global Store Structure

The application uses Zustand for centralized state management through the packages/stores package. The store is organized into functional slices with clear action boundaries.

graph TD
    A[Root Store] --> B[Import Resource Store]
    A --> C[Canvas Store]
    A --> D[User Store]
    A --> E[UI Store]
    
    B --> B1[importResourceModalVisible]
    B --> B2[extensionModalVisible]
    B --> B3[scrapeLinks]
    B --> B4[waitingList]
    B --> B5[fileList / imageList]
    
    C --> C1[selectedMenuItem]
    C --> C2[insertNodePosition]

Store Actions Pattern

State updates follow a consistent pattern using Zustand's set function with immutable state updates:

setFileList: (fileList: FileItem[]) => set((state) => ({ ...state, fileList })),
setImageList: (imageList: ImageItem[]) => set((state) => ({ ...state, imageList })),
setSelectedMenuItem: (menuItem: ImportResourceMenuItem) =>
  set((state) => ({ ...state, selectedMenuItem: menuItem })),
setInsertNodePosition: (position: XYPosition) =>
  set((state) => ({ ...state, insertNodePosition: position })),

Sources: packages/stores/src/stores/import-resource.ts:1-30

Waiting List Management

The store implements a waiting list feature for handling pending operations:

addToWaitingList: (item: WaitingListItem) =>
  set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),
removeFromWaitingList: (id: string) =>
  set((state) => ({
    ...state,
    waitingList: state.waitingList.filter((item) => item.id !== id),
  })),
updateWaitingListItem: (id: string, updates: Partial<WaitingListItem>) =>
  set((state) => ({
    ...state,
    waitingList: state.waitingList.map((item) =>
      item.id === id ? { ...item, ...updates } : item
    ),
  })),

Sources: packages/stores/src/stores/import-resource.ts:30-45

Canvas System Architecture

Canvas Overview

The canvas is the central workspace component where users build workflows by connecting nodes. It supports multiple node types including skills, webhooks, documents, and integrations.

Node Types

Sources: packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:1-60

Artifact Rendering System

The ArtifactRenderer component handles rendering different content types within the canvas:

const ArtifactRenderer = memo(
  ({ node, type, content, title, language, status }) => {
    // Renders based on rendererType: 'document' or other
    // Supports purePreview mode for clean rendering
    // Implements custom width/height scaling
  },
  (prevProps, nextProps) => {
    // Custom comparison for memo optimization
    const prevMetadata = prevProps.node.nodeData?.metadata || {};
    const nextMetadata = nextProps.node.nodeData?.metadata || {};
    
    return (
      prevProps.type === nextProps.type &&
      prevProps.node.entityId === nextProps.node.entityId &&
      prevMetadata.content === nextMetadata.content &&
      prevMetadata.status === nextMetadata.status
    );
  }
);

Sources: packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:1-120

Action Step Execution Flow

Skills execute through a structured action step system:

graph TD
    A[Skill Node] --> B[ActionStep Component]
    B --> C{Status Check}
    C -->|executing| D[Show Progress Logs]
    C -->|waiting| E[Show Pending Indicator]
    C -->|finish| F[Show Results]
    C -->|failed| G[Show Error Logs]
    
    D --> H[ReasoningContent]
    E --> H
    F --> I[Collapsed View]
    G --> J[Error Details]

The component manages status transitions automatically:

useEffect(() => {
  if (['executing', 'waiting'].includes(status)) {
    setCollapsed(false);
  } else {
    setCollapsed(true);
  }
}, [status]);

Sources: packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx:50-80

Integration System Architecture

Integration Docs Modal

The integration system provides a unified interface for configuring external services:

case 'webhook':
  return (
    <WebhookDocsTab
      canvasId={canvasId}
      webhookConfig={webhookConfig}
      toggling={webhookToggling}
      onWebhookReset={fetchWebhookConfig}
      onNavigateToApiSection={handleNavigateToIntegrationSection}
    />
  );
case 'api':
  return <ApiDocsTab canvasId={canvasId} />;
case 'skill':
  return <SkillDocsTab />;

Sources: packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx:1-80

Webhook Documentation Tab

The webhook documentation provides usage instructions and error handling guidance:

<section id="webhook-instructions" className="space-y-2 scroll-mt-4">
  <Text strong>{t('webhook.instructions')}</Text>
  <ul className="list-disc list-inside space-y-1 text-sm text-gray-600">
    <li>{t('webhook.instruction1')}</li>
    <li>{t('webhook.instruction2')}</li>
    <li>{t('webhook.instruction3')}</li>
  </ul>
</section>

Sources: packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx:1-30

Webhook Error Codes

Skill Template System

Context Management

The skill template system uses a context-based architecture for passing data between skill execution steps:

export interface ContextFile {
  name: string;
  fileId: string;
  type: string;
  summary: string;
  content: string;
  variableId?: string;
  variableName?: string;
}

export interface ContextFileMeta {
  // Metadata-only version (without content)
  name: string;
  fileId: string;
  type: string;
  summary: string;
  variableId?: string;
  variableName?: string;
}

Sources: packages/skill-template/src/scheduler/utils/context.ts:1-50

Tool Use Pattern

Skills use a standardized tool calling format:

// Matches markdown code block format
const TOOL_USE_BLOCK_REGEX = /\n*```tool_use(?:_result)?[^\n]*\n[\s\S]*?```\n*/g;

// Matches standalone XML tags
const TOOL_USE_TAG_REGEX = /<tool_use[\s\S]*?<\/tool_use>/g;

Agent Result Structure

export interface AgentResult {
  resultId: string;
  title: string;
  content: string;
  outputFiles: ContextFileMeta[];
}

export interface ToolCallMeta {
  callId: string;      // For retrieval via read_tool_result
  toolName: string;    // Tool that was called
}

Sources: packages/skill-template/src/scheduler/utils/context.ts:40-80

Copilot Integration

Pure Copilot Component

The copilot provides an AI-powered interface for interacting with the workspace:

const PureCopilot = ({
  source,
  canvasId,
  onQueryChange,
}: {
  source: 'frontPage' | 'onboarding';
  canvasId?: string;
  onQueryChange?: (query: string) => void;
}) => {
  // Supports drag-and-drop file handling
  // Integrates with ChatInput component
  // Manages file uploads and context items
};

Sources: packages/ai-workspace-common/src/components/pure-copilot/index.tsx:1-50

Drag and Drop Support

<div
  className="w-full relative"
  onDragEnter={handleDragEnter}
  onDragLeave={handleDragLeave}
  onDragOver={handleDragOver}
  onDrop={handleDrop}
>

The copilot glow effect varies based on source location:

source === 'frontPage'
  ? cn('border-refly-primary-default my-2')
  : 'border-transparent pure-copilot-glow-effect'

Modal Architecture

Modal Container Pattern

The application uses a centralized modal container with lazy loading:

<LazyModal
  visible={importResourceModalVisible}
  loader={() =>
    import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({
      default: m.ImportResourceModal,
    }))
  }
/>

Sources: packages/web-core/src/components/layout/ModalContainer.tsx:1-80

Modal Types

Schedule System

Schedule Button Component

The schedule system manages automated workflow execution:

<Popover content={scheduleContent} trigger="click" placement="bottomRight">
  <Button className="schedule-toolbar-btn">
    {/* Loading state with skeleton */}
    {/* Schedule title display */}
  </Button>
</Popover>

<Modal
  title={t('schedule.limitReached.title')}
  footer={[
    <Button key="cancel">{t('common.cancel')}</Button>,
    <Button key="view-schedules" type="primary">{t('schedule.viewSchedules')}</Button>,
  ]}
>
  {/* Limit reached message */}
</Modal>

Sources: packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx:1-60

Schedule Modal Features

Page Layout System

Layout Components

The layout system provides consistent page structures:

// PrimaryPageLayout - Main application pages
<PrimaryPageLayout>
  {({ context, onContextChange }) => (
    <>
      <PrimaryPageLayoutContextUpdater
        title="Page Title"
        actions={<Button>Action</Button>}
      />
      <div>Content</div>
    </>
  )}
</PrimaryPageLayout>

// SecondaryPageLayout - Detail/sub-pages
<SecondaryPageLayout>
  {({ context, onContextChange }) => (
    <>
      <SecondaryPageLayoutContextUpdater
        title="Detail Title"
        desc="Description"
        onBack={() => history.back()}
      />
      <div>Content</div>
    </>
  )}
</SecondaryPageLayout>

Layout Configuration Options

Wide Mode Feature

The page share feature includes a wide mode for expanded content viewing:

{wideMode.isActive && (
  <Modal
    open={wideMode.isActive}
    footer={null}
    onCancel={handleCloseWideMode}
    width="85%"
    className="wide-mode-modal"
  >
    <div className="bg-white h-full w-full flex flex-col rounded-lg overflow-hidden">
      {wideMode.nodeId && nodes.find((n) => n.nodeId === wideMode.nodeId)}
    </div>
  </Modal>
)}

Sources: packages/web-core/src/pages/page-share/index.tsx:1-80

Component Rendering Optimization

Memo Strategy

Components use React's memo with custom comparison functions to optimize re-renders:

export const ArtifactRenderer = memo(
  Component,
  (prevProps, nextProps) => {
    const prevMetadata = prevProps.node.nodeData?.metadata || {};
    const nextMetadata = nextProps.node.nodeData?.metadata || {};

    return (
      prevProps.type === nextProps.type &&
      prevProps.node.entityId === nextProps.node.entityId &&
      prevMetadata.content === nextMetadata.content &&
      prevMetadata.status === nextMetadata.status &&
      prevMetadata.type === nextMetadata.type
    );
  }
);

Sources: packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx:100-120

API Error Handling

Error Response Structure

The API returns structured error responses:

{
  code: string;        // Error code (e.g., "AUTH_REQUIRED")
  httpStatus: number;  // HTTP status code
  message: string;    // Error message
  description: string // Detailed description
}

Common Error Codes

Conclusion

The Refly system architecture demonstrates a well-structured monorepo design with clear separation of concerns across multiple packages. The architecture supports:

• Scalable State Management: Centralized Zustand stores with typed actions
• Modular UI Components: Reusable components in ai-workspace-common
• Flexible Integration System: Extensible webhook and API integrations
• Optimized Rendering: Strategic use of React.memo for performance
• Type-Safe Communication: Consistent TypeScript interfaces across packages

Related Pages

Related topics: System Architecture, API Modules

Project Structure

Overview

Refly is a modern monorepo built with pnpm workspaces and Turborepo for optimized build performance. The repository follows a structured approach to organize code across multiple packages and applications, enabling shared dependencies and consistent development practices across the entire codebase.

The project architecture separates concerns into discrete packages under the packages/ directory and applications under the apps/ directory, with each package serving a specific domain of functionality.

High-Level Architecture

graph TD
    subgraph "Apps Layer"
        API[apps/api<br/>Backend API Service]
        WEB[apps/web-core<br/>Web Application]
    end

    subgraph "Packages Layer"
        STORES[packages/stores<br/>Zustand State Management]
        LAYOUT[packages/layout<br/>Layout Components]
        WORKSPACE[packages/ai-workspace-common<br/>Workspace Components]
        CLI[packages/cli<br/>Command Line Interface]
    end

    API --> STORES
    WEB --> STORES
    WEB --> LAYOUT
    WEB --> WORKSPACE
    CLI --> API

Directory Structure

refly/
├── apps/
│   ├── api/                    # Backend API application
│   │   └── src/
│   │       └── modules/        # API modules (voucher, workflows, etc.)
│   └── web/                    # Web application entry
├── packages/
│   ├── stores/                 # State management with Zustand
│   ├── ai-workspace-common/    # Shared AI workspace components
│   ├── layout/                 # Page layout components
│   ├── web-core/               # Core web components
│   └── cli/                    # CLI tool
├── pnpm-workspace.yaml         # pnpm workspace configuration
└── turbo.json                 # Turborepo configuration

Applications

apps/api

The backend API service built with Node.js. The API module structure follows a modular pattern:

apps/api/src/modules/
├── voucher/                   # Voucher/coupon management
│   └── voucher-email-templates.ts
└── ... (additional modules)

Key Characteristics:

• Handles business logic and data persistence
• Provides REST API endpoints for the frontend
• Contains email template logic for notifications
• Manages voucher rewards and creator incentives

Sources: apps/api/src/modules

apps/web-core

The main web application entry point, responsible for rendering the user interface and handling client-side routing.

Packages

packages/stores

State management layer using Zustand. Provides centralized state stores for various application features.

Primary Store Files:

Key Store Patterns:

// Store action pattern
setImportResourceModalVisible: (visible: boolean) =>
  set((state) => ({ ...state, importResourceModalVisible: visible })),

// Waiting list operations
addToWaitingList: (item: WaitingListItem) =>
  set((state) => ({ ...state, waitingList: [...state.waitingList, item] })),

removeFromWaitingList: (id: string) =>
  set((state) => ({
    ...state,
    waitingList: state.waitingList.filter((item) => item.id !== id),
  })),

Sources: packages/stores/src/stores/import-resource.ts

packages/ai-workspace-common

The core component library for the AI workspace functionality. This package contains the majority of UI components and business logic for the application.

#### Component Organization

packages/ai-workspace-common/src/components/
├── canvas/                    # Canvas-based workflow components
│   ├── nodes/                 # Custom node types
│   ├── top-toolbar/          # Toolbar components
│   ├── node-preview/         # Node preview panels
│   ├── integration-docs/    # Integration documentation
│   ├── webhook/              # Webhook configuration
│   └── launchpad/           # Launchpad interface
├── resource-view/            # Resource display components
├── pure-copilot/             # Copilot chat interface
├── slideshow/                # Presentation/slideshow components
└── markdown/                 # Markdown rendering plugins

#### Canvas Components

The canvas system is a node-based workflow editor:

Canvas Node Rendering:

// packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx
export const CodeArtifactNode = memo(
  ({ id, data, isPreview, selected, hideHandles, onNodeClick }: CodeArtifactNodeProps) => {
    const [isHovered, setIsHovered] = useState(false);
    const { edges } = useCanvasData();
    const { getNode } = useReactFlow();
    // ... node rendering logic
  },
  (prevProps, nextProps) =>
    prevProps.entityId === nextProps.entityId &&
    prevProps?.status === nextProps?.status &&
    prevProps.legacyData?.content === nextProps.legacyData?.content
);

Sources: packages/ai-workspace-common/src/components/canvas/nodes/code-artifact.tsx

#### Skill Response & Action Steps

The skill response system displays AI agent execution logs:

// packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx
const ReasoningContent = memo(
  ({
    resultId,
    reasoningContent,
    sources,
    step,
    status,
  }: {
    resultId: string;
    reasoningContent: string;
    sources: Source[];
    step: ActionStep;
    status: ActionStatus;
  }) => {
    const [collapsed, setCollapsed] = useState(status !== 'executing');
    
    // Auto-collapse when step status changes from executing to finish
    useEffect(() => {
      if (['executing', 'waiting'].includes(status)) {
        setCollapsed(false);
      } else {
        setCollapsed(true);
      }
    }, [status]);
    // ...
  }
);

Sources: packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx

#### Resource View System

Displays resource metadata and details:

// packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx
{resourceDetail?.data?.url && (
  <a
    className="site-intro-site-url no-underline text-[#0E9F77]"
    href={resourceDetail?.data?.url}
    target="_blank"
    rel="noreferrer"
  >
    {resourceDetail?.data?.url}
  </a>
)}
{resourceDetail?.createdAt && (
  <p className="text-gray-400">
    {time(resourceDetail?.createdAt, language as LOCALE)
      .utc()
      .fromNow()}
  </p>
)}

Sources: packages/ai-workspace-common/src/components/resource-view/resource-meta.tsx

#### Integration Documentation

Web-based documentation and configuration interfaces:

// packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx
<Button
  type="primary"
  className="view-schedules-btn"
  onClick={handleViewSchedulesClick}
>
  {t('schedule.viewSchedules') || 'View Schedules'}
</Button>

<Modal
  title={t('schedule.limitReached.title') || 'Schedule Limit Reached'}
  open={scheduleLimitModalVisible}
  footer={[
    <Button key="cancel" onClick={() => setScheduleLimitModalVisible(false)}>
      {t('common.cancel') || 'Cancel'}
    </Button>,
    // ...
  ]}
>

Sources: packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx

#### Artifact Rendering

Supports multiple artifact types with preview capabilities:

// packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx
<div className="transform scale-[0.5] origin-top-left w-[200%] h-[200%] overflow-hidden bg-white dark:bg-gray-900 rounded shadow-sm">
  <Renderer
    purePreview
    content={content}
    type={currentType}
    title={title}
    language={artifactData?.language || language}
    readonly
    onRequestFix={handleRequestFix}
    width="100%"
    height="100%"
  />
</div>

Sources: packages/ai-workspace-common/src/components/slideshow/components/ArtifactRenderer.tsx

#### Markdown Link Rendering

Custom markdown plugin for rendering links with preview functionality:

// packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx
<img
  className="w-3 h-3"
  alt={source?.url}
  src={`https://www.google.com/s2/favicons?domain=${source?.url}&sz=${16}`}
/>

Sources: packages/ai-workspace-common/src/components/markdown/plugins/link/render.tsx

packages/web-core

Core web components including modal management and page layouts.

#### Modal Container

Centralized modal management system:

// packages/web-core/src/components/layout/ModalContainer.tsx
<LazyModal
  visible={importResourceModalVisible}
  loader={() =>
    import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({
      default: m.ImportResourceModal,
    }))
  }
/>

<LazyModal
  visible={isCanvasRenameShown}
  loader={() =>
    import('@refly-packages/ai-workspace-common/components/canvas/modals/canvas-rename').then(
      (m) => ({ default: m.CanvasRenameModal }),
    )
  }
/>

Sources: packages/web-core/src/components/layout/ModalContainer.tsx

#### Page Share Module

Handles public page sharing functionality:

// packages/web-core/src/pages/page-share/index.tsx
{wideMode.isActive && (
  <Modal
    open={wideMode.isActive}
    footer={null}
    onCancel={handleCloseWideMode}
    width="85%"
    className="wide-mode-modal"
  >
    <div className="bg-white h-full w-full flex flex-col rounded-lg overflow-hidden">
      {/* Wide mode content */}
    </div>
  </Modal>
)}

Sources: packages/web-core/src/pages/page-share/index.tsx

packages/layout

Page layout component library providing consistent layout patterns.

#### Layout Components

Primary Layout Usage:

import { PrimaryPageLayout, PrimaryPageLayoutContextUpdater } from '@refly/layout';

function MainPage() {
  return (
    <PrimaryPageLayout>
      {({ context, onContextChange }) => (
        <>
          <PrimaryPageLayoutContextUpdater
            title="Page Title"
            actions={<Button>Action Button</Button>}
            extra={<div>Extra Content</div>}
            deps={[]}
          />
          <div>Page Content</div>
        </>
      )}
    </PrimaryPageLayout>
  );
}

Configuration Options:

Sources: packages/layout/README.md

packages/cli

Command-line interface for Refly operations.

#### CLI Features

Configuration Storage:

Configuration is stored in ~/.refly/config.json:

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Environment Variables:

#### Claude Code Integration

After refly init, skill files are installed to:

• ~/.claude/skills/refly/SKILL.md
• ~/.claude/skills/refly/references/
• ~/.claude/commands/refly-*.md

#### Error Codes

Sources: packages/cli/README.md

Build System

pnpm Workspaces

The project uses pnpm workspaces for monorepo management:

# pnpm-workspace.yaml
packages:
  - 'apps/*'
  - 'packages/*'

Turborepo

Build orchestration with Turborepo:

// turbo.json (inferred from usage)
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**"]
    }
  }
}

Component Communication Flow

graph LR
    subgraph "State Layer"
        STORES[packages/stores<br/>Zustand Stores]
    end

    subgraph "UI Layer"
        WEB_CORE[packages/web-core<br/>Modal Container]
        WORKSPACE[packages/ai-workspace-common<br/>Components]
    end

    subgraph "Layout Layer"
        LAYOUT[packages/layout<br/>Page Layouts]
    end

    STORES -->|State Updates| WEB_CORE
    STORES -->|State Updates| WORKSPACE
    WORKSPACE -->|Lazy Loaded| WEB_CORE
    LAYOUT -->|Wraps| WEB_CORE

Internationalization

The project uses i18n for translations with namespace support:

const { t } = useTranslation();

{t('schedule.title') || 'Schedule'}
{t('schedule.limitReached.title', { ns: 'schedule' })}

Translation namespaces include:

• common - Common UI strings
• schedule - Schedule-related strings
• skillLog - Skill execution logs
• webhook - Webhook configuration
• integration - Integration documentation

Key Development Patterns

Lazy Loading

Components are lazy-loaded for performance:

<LazyModal
  visible={importResourceModalVisible}
  loader={() =>
    import('@refly-packages/ai-workspace-common/components/import-resource').then((m) => ({
      default: m.ImportResourceModal,
    }))
  }
/>

Memoization

Heavy components use React.memo for optimization:

export const CodeArtifactNode = memo(
  ({ id, data, isPreview, selected }: CodeArtifactNodeProps) => {
    // component logic
  },
  (prevProps, nextProps) =>
    prevProps.entityId === nextProps.entityId &&
    prevProps?.status === nextProps?.status
);

Custom Hooks

Domain-specific hooks encapsulate business logic:

• useCanvasData() - Canvas state access
• useAgentNodeManagement() - Agent node operations
• useVariablesManagement() - Workflow variables
• useFetchDriveFiles() - File fetching

Development Commands

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Watch mode for development
pnpm dev

# Run API locally
node dist/bin/refly.js

Related Pages

Related topics: Skill Management, API Modules

Workflow Engine

Overview

The Workflow Engine is the core execution runtime of the refly platform. It orchestrates the execution of workflow graphs composed of interconnected nodes, where each node represents a discrete unit of work executed by specialized agents. The engine handles workflow lifecycle management, from creation through execution, monitoring, and completion.

The Workflow Engine serves as the backbone for:

• Workflow Graph Execution: Parsing and executing directed acyclic graphs (DAGs) of workflow tasks
• Node Agent Orchestration: Invoking skill agents for individual task execution
• Variable Management: Managing workflow-level and node-level variables
• Execution State Tracking: Tracking node status, handling retries, and managing abort signals
• Scheduled Execution: Supporting time-based workflow triggers

Architecture

The Workflow Engine follows a layered architecture with clear separation of concerns:

graph TD
    subgraph "API Layer"
        WS[Workflow Service]
        SS[Schedule Service]
    end
    
    subgraph "Core Engine"
        WP[Workflow Processor]
        SI[Skill Invoker]
    end
    
    subgraph "Execution Layer"
        NA[Node Agents]
        ST[Skill Templates]
    end
    
    subgraph "State Management"
        DB[(Database)]
        EV[Event Bus]
    end
    
    WS --> WP
    SS --> WP
    WP --> SI
    SI --> NA
    NA --> ST
    WP <--> DB
    WP <--> EV

Key Components

Data Models

Workflow Graph Structure

The workflow is defined as a graph with nodes and edges:

interface WorkflowSpec {
  nodes?: Array<Record<string, unknown>>;
  edges?: Array<Record<string, unknown>>;
}

Sources: apps/api/src/modules/skill-package/skill-package.dto.ts:26

Node Types

Workflows support multiple node types:

Sources: packages/web-core/src/pages/workflow-app/index.tsx:142

Task Structure

Tasks represent individual units of work within a workflow:

Sources: packages/skill-template/src/prompts/templates/copilot-agent-system.md:67

Context Files

Context files provide input/output data flow between workflow nodes:

export interface ContextFile {
  name: string;
  fileId: string;
  type: string;
  summary: string;
  content: string;
  variableId?: string;
  variableName?: string;
}

Sources: packages/skill-template/src/scheduler/utils/context.ts:14

Agent Results

Agent results encapsulate task execution outcomes:

export interface AgentResult {
  resultId: string;
  title: string;
  content: string;
  outputFiles: ContextFileMeta[];
}

Sources: packages/skill-template/src/scheduler/utils/context.ts:27

Workflow Lifecycle

stateDiagram-v2
    [*] --> Created: workflow.create
    Created --> Running: workflow.run
    Running --> Completed: all nodes finish
    Running --> Failed: unhandled error
    Running --> Aborted: user abort
    Failed --> Running: retry
    Aborted --> [*]
    Completed --> [*]

Execution States

Each node in a workflow can be in one of the following states:

Sources: packages/ai-workspace-common/src/components/workflow-app/run-logs.tsx:78

Workflow Execution Flow

sequenceDiagram
    participant User
    participant API
    participant Processor
    participant Invoker
    participant Agent
    
    User->>API: workflow.run(workflowId, input)
    API->>Processor: processWorkflowExecution()
    Processor->>Processor: Initialize execution context
    Processor->>Processor: Resolve task dependencies (DAG)
    
    loop For each ready node
        Processor->>Invoker: invokeSkillNode(node)
        Invoker->>Agent: Execute skill agent
        Agent-->>Invoker: AgentResult
        Invoker-->>Processor: NodeExecutionResult
        Processor->>Processor: Update execution state
    end
    
    Processor-->>API: WorkflowExecutionResult
    API-->>User: Execution ID + status

Variable Management

Workflow variables enable data passing between nodes and external input:

Variable Input Schema

interface WorkflowVariable {
  id: string;
  name: string;
  type: string;
  required: boolean;
  defaultValue?: unknown;
}

Variables can be defined at the workflow level and referenced in node prompts using the format @{type=variable,id=<id>,name=<Name>}.

Sources: packages/skill-template/src/prompts/templates/copilot-agent-system.md:73

Scheduled Execution

The Workflow Engine supports time-based triggers through the Schedule Service:

graph LR
    S[Schedule] -->|trigger| WP[Workflow Processor]
    WP -->|execute| W[Workflow]
    S -->|email| U[User Notification]

Schedule Configuration

Skill Invocation

The Skill Invoker Service handles the execution of skill agents within workflow nodes:

Invocation Flow

1. Skill Node Triggered: Processor identifies ready skill node
2. Input Preparation: Gather context files and variables
3. Agent Invocation: Call skill agent with prepared context
4. Result Processing: Parse agent output, extract files and results
5. State Update: Update node execution status

Abort Handling

The engine supports graceful abort of executing nodes:

// Abort signal propagation
const abortSignal = new AbortController();
skillInvoker.invokeSkill({
  executionId,
  nodeId,
  signal: abortSignal.signal,
});

Sources: apps/api/src/modules/skill/skill-invoker.service.ts:1

Error Handling

Retry Mechanism

Failed nodes can be retried using the retry handler:

const handleRetry = createRetryHandler(node, resultId);

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:52

Error Display

Execution errors are displayed with appropriate styling:

<span className="text-sm font-semibold text-refly-func-danger-default">
  {t('canvas.workflow.run.executionFailed')}
</span>

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx:32

Workflow Generation

The copilot agent can generate workflows dynamically using the generate_workflow and patch_workflow tools:

Sources: packages/skill-template/src/prompts/templates/copilot-agent-system.md:49

Workflow Plan Structure

interface WorkflowPlanRecord {
  tasks: Array<{
    id: string;
    title: string;
    prompt: string;
    dependentTasks: string[];
    toolsets: string[];
  }>;
  // ...
}

CLI Integration

The refly CLI provides workflow management commands:

# Create workflow
refly workflow create --name "<name>" --spec '<json>'

# Run workflow
refly workflow run <workflowId> [--input '<json>']

# Check status
refly workflow run-status <runId>

# Abort execution
refly workflow abort <runId>

Sources: packages/cli/README.md:1

Credit Usage Tracking

The engine tracks credit consumption during workflow execution:

creditUsage={
  isCreditUsageLoading || hasIncompleteNodes
    ? null
    : (creditUsageData?.data?.total ?? 0)
}

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/preview.tsx:45

Webhook Integration

Workflows can trigger external webhooks:

graph LR
    W[Workflow Complete] -->|POST| H[Webhook Endpoint]
    H -->|Response| W

Webhook configuration includes error codes and status mappings for reliable integration.

Public Workflow Pages

The workflow engine powers multiple page types exported from the web-core package:

Sources: packages/web-core/src/index.ts:1

Summary

The Workflow Engine is the central orchestration layer that transforms workflow specifications into executable task graphs. It leverages the skill system for node execution, manages complex variable dependencies, and provides comprehensive execution tracking with support for real-time monitoring, scheduled runs, and graceful error handling. The engine's design emphasizes extensibility through toolsets, reliability through retry mechanisms, and observability through detailed execution logging.

Related Pages

Related topics: Workflow Engine

Skill Management

Overview

The Skill Management system in Refly provides a modular, extensible framework for creating, installing, updating, and uninstalling reusable workflow snippets called "Skills." Skills enable users to package and share reusable automation logic across the Refly ecosystem, including integration with various IDE environments such as Claude Code, Cursor, VS Code, and others.

Skills are defined using markdown files with frontmatter metadata and can be loaded, validated, and executed through the CLI or API components. The system supports a registry-based distribution model where skills are hosted in the refly-skills GitHub repository and can be installed to local IDE environments.

Sources: skill-docs-tab.tsx:1-150

Architecture

The Skill Management system is composed of three primary layers:

graph TD
    A[User] --> B[CLI Command<br/>refly skill install]
    A --> C[Web UI<br/>Integration Docs Tab]
    B --> D[Skill Loader<br/>packages/cli/src/skill/loader.ts]
    C --> E[Skill Registry<br/>github.com/refly-ai/refly-skills]
    E --> D
    D --> F[Local Skill Storage<br/>~/.{ide}/skills/]
    D --> G[Symlink Validation]
    G --> H[SKILL.md Loading]
    H --> I[Metadata Extraction]
    I --> J[LoadedSkill Object]

Sources: loader.ts:1-60

Skill File Structure

Each skill consists of a standardized directory structure with a mandatory SKILL.md file at its root. The skill directory is installed to environment-specific locations based on the target IDE.

Directory Layout

Sources: skill-docs-tab.tsx:150-200

Supported IDE Installation Paths

Skills are installed to the following locations based on the target IDE:

Sources: skill-docs-tab.tsx:200-230

Skill Loading

The Loader Module

The skill loader (packages/cli/src/skill/loader.ts) provides core functionality for loading and validating skills from the local filesystem.

export function loadSkill(name: string): LoadedSkill {
  // Loads skill with symlink validation
  // Returns LoadedSkill object with metadata
}

Sources: loader.ts:20-40

Loading Process

graph TD
    A[loadSkill name] --> B{Check Symlink Status}
    B -->|Symlink Invalid| C[Error: Symlink Broken]
    B -->|Symlink Valid| D{Skill Directory Exists?}
    D -->|No| E[Error: SKILL_DIR_NOT_FOUND]
    D -->|Yes| F{SKILL.md Exists?}
    F -->|No| G[Error: SKILL_NOT_FOUND]
    F -->|Yes| H[Load Skill Metadata]
    H --> I[Extract Frontmatter]
    I --> J[Validate Frontmatter]
    J --> K[Return LoadedSkill]

Safe Loading with tryLoadSkill

The tryLoadSkill function provides a safe loading mechanism that returns null instead of throwing errors when a skill is not found:

export function tryLoadSkill(name: string): LoadedSkill | null {
  try {
    return loadSkill(name);
  } catch (err) {
    if (
      (err as { code?: string }).code === SkillErrorCode.SKILL_DIR_NOT_FOUND ||
      (err as { code?: string }).code === SkillErrorCode.SKILL_NOT_FOUND
    ) {
      return null;
    }
    throw err;
  }
}

Sources: loader.ts:70-90

Metadata Extraction

Frontmatter Parsing

The extractSkillMetadata function allows extraction of skill metadata without fully loading from disk, which is useful for validation and preview operations:

export function extractSkillMetadata(content: string): {
  frontmatter: SkillFrontmatter | null;
  issues: ValidationIssue[];
  content: string;
}

The function performs the following steps:

1. Parses frontmatter from markdown content
2. Validates frontmatter against schema
3. Returns extracted metadata and any validation issues

Sources: loader.ts:100-120

Validation Issues

When frontmatter validation fails, the system returns an array of ValidationIssue objects describing each problem. This ensures skills meet the required schema before installation.

Skill Operations

Installation from Repository

The installation process follows these steps:

1. Downloads the skill from the registry repository
2. Creates the skill directory structure
3. Validates and installs symlinks to IDE-specific locations

refly skill install <skill-name>

Sources: skill-docs-tab.tsx:250-280

Uninstallation

Uninstallation removes the skill directory and cleans up all symlinks:

1. Removes skill files from the local directory
2. Cleans up environment-specific symlinks
3. Updates skill registry

refly skill uninstall <skill-name>

Sources: skill-docs-tab.tsx:100-150

Updating Skills

Update operations fetch the latest version from the registry and replace existing files while preserving local customizations.

Creating New Skills

The refly skill create command initializes a new skill with the standard directory structure:

refly skill create <skill-name>

Sources: skill-docs-tab.tsx:300-350

CLI Integration

Configuration Storage

The Refly CLI stores configuration at ~/.refly/config.json:

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Sources: packages/cli/README.md:20-40

Environment Variables

Claude Code Integration

After running refly init, skill files are automatically installed to Claude Code locations:

• ~/.claude/skills/refly/SKILL.md
• ~/.claude/skills/refly/references/
• ~/.claude/commands/refly-*.md (if commands directory exists)

This integration enables Claude Code to:

• Understand Refly workflow concepts
• Use builder mode correctly
• Handle state transitions
• Output deterministic results

Sources: packages/cli/README.md:45-60

Error Handling

Error Codes

Sources: packages/cli/README.md:65-75

Error Recovery Suggestions

The loader provides contextual suggestions for error recovery:

throw createSkillError(
  SkillErrorCode.SKILL_DIR_NOT_FOUND,
  `Skill '${name}' symlink exists but SKILL.md file is missing`,
  {
    suggestions: [
      'The skill directory may be corrupted',
      'Try reinstalling the skill with `refly skill install`',
    ],
  }
);

Sources: loader.ts:30-50

Skill Registry

The official skill registry is hosted at github.com/refly-ai/refly-skills. Users can browse available skills at:

https://github.com/refly-ai/refly-skills/tree/main/skills

Sources: skill-docs-tab.tsx:20-30

Summary

The Skill Management system provides a complete lifecycle for reusable automation snippets:

• Creation: Scaffold new skills with standard structure
• Installation: Fetch from registry and install to IDE environments
• Loading: Validate and parse skill metadata
• Execution: Integrate with Claude Code and other IDEs
• Updates: Fetch latest versions from registry
• Uninstallation: Clean removal with symlink cleanup

The modular architecture separates concerns between the CLI loader, UI documentation components, and the registry, enabling maintainable and extensible skill management across the Refly ecosystem.

Related Pages

Related topics: Copilot Integration, System Architecture

Canvas Component

Overview

The Canvas Component is the core visual workspace system in the Refly AI platform. It provides an interactive, node-based environment for building and executing AI-powered workflows. The Canvas enables users to create, configure, and orchestrate complex AI workflows through a visual interface that combines drag-and-drop node composition with real-time execution monitoring.

The Canvas system supports multiple node types including agent nodes, tool nodes, document renderers, and webhook integrations. It serves as the primary workspace where users define workflow logic, manage context items, connect to upstream agents, and execute AI-driven processes.

Sources: packages/ai-workspace-common/src/components/canvas/index.tsx

Architecture

Component Hierarchy

The Canvas architecture follows a modular composition pattern with multiple layered components working together to provide the complete workspace experience.

graph TD
    A[Canvas Workspace] --> B[Canvas Container]
    A --> C[Top Toolbar]
    A --> D[Side Panel]
    B --> E[Rich Chat Input]
    B --> F[Node System]
    B --> G[Workflow Runner]
    C --> H[Schedule Button]
    C --> I[Integration Docs]
    D --> J[Resource Library]
    D --> K[Sider Store]
    F --> L[Agent Nodes]
    F --> M[Tool Nodes]
    G --> N[Workflow Node Panel]
    G --> O[Action Steps]

Directory Structure

The Canvas components are organized in the following structure within packages/ai-workspace-common/src/components/canvas/:

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx

Core Components

Canvas Context

The Canvas uses React Context to provide global state and utilities across all child components. The context exposes canvas-specific operations including context item management, toolset selection, and agent connections.

const { canvasId } = useCanvasContext();

The Canvas context is consumed by multiple sub-components to access shared state such as the current canvas identifier and related workflow metadata. This enables components throughout the canvas tree to access and modify workflow state without prop drilling.

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx

Rich Chat Input

The Rich Chat Input component provides the primary user interaction mechanism for communicating with AI agents within the Canvas. It supports advanced features including file attachments, @mentions, and real-time message composition.

export interface RichChatInputRef {
  focus: () => void;
  insertAtSymbol?: () => void;
}

Key Features:

The component integrates with the useAgentNodeManagement hook to manage query state, context items, and selected toolsets. It also connects to useAgentConnections for upstream agent communication.

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx

Mention List

The mention system provides context-aware suggestions when users type @ symbols in the chat input. It supports multiple mention types with distinct rendering behaviors.

Mention Types:

agents: {
  nodeIconProps: (item: MentionItem) => {
    if (item.source === 'agents') {
      return {
        type: 'skillResponse' as CanvasNodeType,
        small: true,
      };
    } else {
      return {
        type: item.variableType as CanvasNodeType,
        small: true,
        url: item.variableType === 'image' ? item.metadata?.imageUrl : undefined,
      };
    }
  },
  emptyStateKey: 'noAgents',
},

The mention list automatically formats variable values for display, truncating long text values to 20 characters with an ellipsis indicator.

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx

Node System

Workflow Node Panel

The Workflow Node Panel provides the execution interface for individual nodes within a workflow. It displays node status, results, and allows users to interact with running workflows.

<LastRunTab
  location="runlog"
  loading={loading}
  isStreaming={isStreaming}
  resultId={resultId}
  result={result}
  outputStep={outputStep}
  query={query}
  title={title}
  nodeId={node.id}
  selectedToolsets={selectedToolsets}
  handleRetry={createRetryHandler(node, resultId)}
/>

Panel States:

The panel automatically logs events when users expand agent nodes, tracking canvas and node identifiers for analytics purposes:

logEvent('runlog_agent_expand', null, {
  canvasId,
  nodeId: node.id,
  resultId,
});

Sources: packages/ai-workspace-common/src/components/canvas/workflow-run/workflow-node-panel.tsx

Action Steps

Action Steps display individual execution steps within skill responses. They render logs with titles and descriptions, supporting status indicators for execution progress.

items={logs.map((log) => ({
  title: t(`${log.key}.title`, {
    ...log.titleArgs,
    ns: 'skillLog',
    defaultValue: log.key,
  }),
  description: t(`${log.key}.description`, {
    ...log.descriptionArgs,
    ns: 'skillLog',
    defaultValue: '',
  }),
  status: log.status === 'error' ? 'error' : 'finish',
}))}

Status Types:

Action steps automatically collapse when execution status changes from executing or waiting to a terminal state.

Sources: packages/ai-workspace-common/src/components/canvas/node-preview/skill-response/action-step.tsx

Integration System

Integration Docs Modal

The Integration Docs Modal provides a comprehensive interface for viewing and managing canvas integrations. It includes API key management, webhook configuration, and documentation display.

<IntegrationDocsModal open={open} onClose={onClose} canvasId={canvasId} />
<ApiKeyModal open={apiKeyModalOpen} onClose={() => setApiKeyModalOpen(false)} />
<ApiOutputModal
  open={outputModalOpen}
  onClose={() => setOutputModalOpen(false)}
  canvasId={canvasId}
/>

Modal Components:

Sources: packages/ai-workspace-common/src/components/canvas/integration-docs/integration-docs-modal.tsx

Webhook Configuration

The Webhook Configuration system enables external systems to trigger canvas workflows. It provides a structured interface for managing webhook endpoints and payloads.

<section id="webhook-instructions" className="space-y-2 scroll-mt-4">
  <Text strong>{t('webhook.instructions')}</Text>
  <ul className="list-disc list-inside space-y-1 text-sm text-gray-600">
    <li>{t('webhook.instruction1')}</li>
    <li>{t('webhook.instruction2')}</li>
    <li>{t('webhook.instruction3')}</li>
  </ul>
</section>

Webhook Features:

• Request body schema definition
• Parameter documentation with types and descriptions
• Required field indicators
• Markdown-formatted descriptions

The webhook documentation tab renders request body fields in a structured table format with columns for name, type, requirement status, and description.

Sources: packages/ai-workspace-common/src/components/canvas/webhook/webhook-config-tab.tsx

Scheduling System

The Schedule Button enables users to configure automated workflow execution at specified intervals. It provides a popover interface for schedule management with modal dialogs for limit warnings.

const handleViewSchedulesClick = () => {
  // Navigate to schedule management
};

<Modal
  title={t('schedule.limitReached.title')}
  open={scheduleLimitModalVisible}
  footer={[
    <Button key="cancel" onClick={() => setScheduleLimitModalVisible(false)}>
      {t('common.cancel')}
    </Button>,
    <Button key="view-schedules" type="primary" onClick={handleViewSchedulesClick}>
      {t('schedule.viewSchedules')}
    </Button>,
  ]}
>
  <p>{t('schedule.limitReached.message')}</p>
</Modal>

Schedule Features:

Sources: packages/ai-workspace-common/src/components/canvas/top-toolbar/schedule-button.tsx

Resource Management

File Overview

The File Overview component provides a grid-based interface for managing canvas resources. It includes search functionality and supports both empty and populated states.

<div className="flex-grow overflow-y-auto min-h-0">
  <FileList files={files} searchKeyword={searchKeyword} />
</div>

Features:

• Searchable file list with keyword filtering
• Empty state with "new resource" call-to-action
• Read-only mode support for shared canvases
• Border-styled input with filled variant

The component displays a search input field above the file list, allowing users to filter resources by name or metadata.

Sources: packages/ai-workspace-common/src/components/canvas/canvas-resources/share/file-overview.tsx

Recent Workflows

The Recent Workflow component displays a grid of recently accessed workflows on the canvas front page. Each workflow card shows the workflow name, used toolsets, and last update timestamp.

<div key={canvas.id} onClick={() => handleEditCanvas(canvas.id)}>
  <div className="h-[120px] flex flex-col justify-between p-4 pb-2">
    <div>
      <div className="text-sm leading-5 font-semibold text-refly-text-0 line-clamp-1">
        {canvas.name || t('common.untitled')}
      </div>
      <UsedToolsets toolsets={canvas.usedToolsets} />
    </div>
    <ActionDropdown canvasId={canvas.id} canvasName={canvas.name} />
  </div>
</div>

Card Display:

Sources: packages/ai-workspace-common/src/components/canvas/front-page/recent-workflow.tsx

State Management

Sider Store

The Canvas state is partially managed through the global Sider Store, which maintains UI state for sidebars, modals, and canvas lists.

export const useSiderStore = create<SiderState>()(
  devtools((set) => ({
    collapse: false,
    collapseState: 'expanded',
    isManualCollapse: false,
    showSiderDrawer: false,
    canvasList: [],
    projectsList: [],
    sourceList: [],
    showLibraryModal: false,
    showCanvasListModal: false,
    showSettingModal: false,
    showInvitationModal: false,
    settingsModalActiveTab: null,
  }))
);

Store Actions:

Sources: packages/stores/src/stores/sider.ts

Workflow Execution Flow

sequenceDiagram
    participant User
    participant RichChatInput
    participant AgentNode
    participant WorkflowPanel
    participant ActionStep
    
    User->>RichChatInput: Submit query with context
    RichChatInput->>AgentNode: Execute agent with toolsets
    AgentNode->>WorkflowPanel: Stream execution status
    WorkflowPanel->>ActionStep: Render logs and progress
    ActionStep-->>User: Display execution steps
    AgentNode-->>RichChatInput: Return result
    WorkflowPanel->>User: Show final output and metrics

Component Configuration Reference

Primary Configuration Options

Secondary Layout Configuration

Best Practices

Node Implementation

1. Always provide unique node identifiers for event tracking
2. Use the logEvent function for analytics when nodes expand or collapse
3. Implement proper cleanup in useEffect return functions
4. Handle all execution states including idle, running, finished, and failed

State Management

1. Use Canvas Context for shared state across components
2. Leverage Sider Store for global UI state
3. Implement proper lazy loading for performance optimization
4. Use dependency arrays (deps) to trigger context updates when needed

Integration Development

1. Define clear API schemas for webhook request bodies
2. Provide localized strings for all user-facing text
3. Implement proper error handling and user feedback
4. Support both read-only and editable modes for shared canvases

Related Pages

Related topics: Canvas Component, API Modules

Copilot Integration

Overview

The Copilot Integration in Refly represents the core conversational AI interface that enables users to interact with Refly's agentic workflow capabilities. It provides a natural language interface where users can describe intent, attach files, mention workflow variables, and send messages to trigger agent actions within canvas workflows.

The integration spans both frontend UI components and backend services, creating a bidirectional communication channel between the user interface and the agent execution engine.

Architecture Overview

graph TD
    subgraph Frontend
        PC[PureCopilot Component]
        CO[Canvas Copilot]
        RCI[RichChatInput]
        ML[MentionList]
    end
    
    subgraph Hooks
        ANM[useAgentNodeManagement]
        AC[useAgentConnections]
        VM[useVariablesManagement]
    end
    
    subgraph Backend
        CS[Copilot Service]
        CAS[CopilotAutogen Service]
    end
    
    subgraph Data Layer
        CF[Context Files]
        AR[Agent Results]
        TC[Tool Calls]
    end
    
    PC --> RCI
    CO --> RCI
    RCI --> ML
    RCI --> ANM
    RCI --> AC
    RCI --> VM
    ANM --> CS
    AC --> CS
    CS --> CAS
    CAS --> CF
    CAS --> AR
    AR --> TC

Core Components

PureCopilot Component

The PureCopilot component (packages/ai-workspace-common/src/components/pure-copilot/index.tsx) serves as the standalone chat interface for copilot interactions. It handles file attachments, drag-and-drop uploads, and message composition.

Key Features:

• File upload and management via FileList component
• Drag-and-drop support with visual feedback (handleDragEnter, handleDragLeave, handleDragOver, handleDrop)
• Context item management for attached files
• Source-aware styling (supports frontPage and onboarding modes)

Component Props:

Sources: packages/ai-workspace-common/src/components/pure-copilot/index.tsx()

RichChatInput Component

The RichChatInput component (packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx) provides the primary input interface within canvas workflows. It extends basic chat input with advanced features like variable mentions, tool references, and OAuth integrations.

Component Interface:

export interface RichChatInputProps {
  readonly?: boolean;
  handleSendMessage: (message: string) => void;
  onUploadImage?: (file: File) => Promise<void>;
  onUploadMultipleImages?: (files: File[]) => Promise<void>;
  onFocus?: () => void;
  placeholder?: string;
  mentionPosition?: MentionPosition;
  nodeId?: string;
}

export interface RichChatInputRef {
  focus: () => void;
  insertAtSymbol?: () => void;
}

Internal State Management:

• isDragging: Tracks drag-over state for file drops
• isFocused: Tracks focus state for UI styling
• isLogin: Authentication state from useUserStoreShallow
• isMentionListVisible: Controls mention dropdown visibility

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx()

MentionList Component

The MentionList component (packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx) provides context-aware suggestions for variables, tools, and other workflow entities during chat composition.

Mention Types:

Keyboard Navigation States:

type FocusLevel = 'first' | 'second';
const [focusLevel, setFocusLevel] = useState<FocusLevel>('first');
const [firstLevelIndex, setFirstLevelIndex] = useState<number>(0);
const [secondLevelIndex, setSecondLevelIndex] = useState<number>(0);

Height Tracking: The component tracks nested list heights for keyboard navigation:

const [firstLevelHeight, setFirstLevelHeight] = useState<number>(0);
const [secondLevelHeight, setSecondLevelHeight] = useState<number>(0);

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/mentionList.tsx()

Context Management System

ContextFile Model

The copilot system uses structured context files to manage files and data passed to agents:

export interface ContextFile {
  name: string;
  fileId: string;
  type: string;
  summary: string;
  content: string;
  variableId?: string;
  variableName?: string;
}

/**
 * Metadata-only version of ContextFile (without content)
 * Used in ContextBlock to reduce token usage - LLM should use read_file to get full content
 */
export interface ContextFileMeta {
  name: string;
  fileId: string;
  type: string;
  summary: string;
  variableId?: string;
  variableName?: string;
}

Agent Results

Agent execution produces structured results:

export interface AgentResult {
  resultId: string;
  title: string;
  content: string;
  outputFiles: ContextFileMeta[];
}

Tool Call Metadata

Tool calls within agent results are tracked for retrieval:

export interface ToolCallMeta {
  callId: string;
  toolName: string;
}

Sources: packages/skill-template/src/scheduler/utils/context.ts()

Backend Services

Copilot Service

The backend copilot service handles message processing, agent dispatch, and response streaming.

Service Location: apps/api/src/modules/copilot/copilot.service.ts

Copilot Autogen Service

The CopilotAutogen service (apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts) manages automatic skill generation and agent orchestration.

Key Responsibilities:

• Generate skills based on user intent
• Manage skill lifecycle (create, update, delete)
• Handle skill installation to Claude Code environments

Skill Installation Path:

~/.claude/skills/refly/SKILL.md
~/.claude/skills/refly/references/
~/.claude/commands/refly-*.md

Sources: apps/api/src/modules/copilot-autogen/copilot-autogen.service.ts() Sources: packages/cli/README.md()

Integration Hooks

useAgentNodeManagement

Manages the agent node state and message handling for a specific node:

const { query, setQuery, setContextItems, setSelectedToolsets } =
  useAgentNodeManagement(nodeId);

useAgentConnections

Manages connections between agents:

const { connectToUpstreamAgent } = useAgentConnections();

useVariablesManagement

Manages workflow variables for the current canvas:

const { data: workflowVariables } = useVariablesManagement(canvasId);

useVariableView

Provides variable viewing functionality:

const { handleVariableView } = useVariableView(canvasId);

Sources: packages/ai-workspace-common/src/components/canvas/launchpad/rich-chat-input/index.tsx()

User Interaction Flow

sequenceDiagram
    participant User
    participant RCI as RichChatInput
    participant ML as MentionList
    participant ANM as useAgentNodeManagement
    participant CS as Copilot Service
    
    User->>RCI: Type message
    RCI->>ML: Check for @ trigger
    ML-->>RCI: Show suggestion dropdown
    User->>ML: Select mention
    ML-->>RCI: Insert mention into query
    User->>RCI: Send message
    RCI->>ANM: handleSendMessage(query)
    ANM->>CS: Process message
    CS-->>ANM: Agent result
    ANM-->>RCI: Update state
    RCI-->>User: Display result

Configuration Options

ChatInput Configuration

Mention Configuration

Styling and Theming

The copilot components use CSS custom properties for theming:

/* Primary copilot styling */
.pure-copilot-glow-effect {
  box-shadow: var(--copilot-glow-color);
}

/* Input area */
.bg-refly-bg-content-z2 {
  background-color: var(--refly-bg-content);
}

/* Text hierarchy */
.text-refly-text-0 { color: var(--refly-text-primary); }
.text-refly-text-1 { color: var(--refly-text-secondary); }

Source-Specific Styling

className={cn(
  'w-full px-4 py-3 rounded-[12px] border-[1px] border-solid bg-refly-bg-content-z2 transition-all duration-300 relative z-20',
  source === 'frontPage'
    ? cn('border-refly-primary-default my-2')
    : 'border-transparent pure-copilot-glow-effect',
)}

Internationalization

The copilot interface supports i18n with namespace-based translations:

Example Translation Keys:

t('copilot.greeting.title')
t('copilot.pureCopilotPlaceholder')
t('skillLog.error.title')

Error Handling

File Upload Errors

Files can fail upload with retry capability:

const { onRemove, onRetry } = useFileUpload({
  uploads: relevantUploads,
  canvasId: currentCanvasId,
});

OAuth Popup Handling

The mention list supports OAuth integration:

openOAuthPopup?: (toolsetKey: string) => Promise<any>;

Related Documentation

• Canvas Integration - Workflow canvas features
• Skills System - Agent skill management
• API Documentation - Backend service APIs
• CLI Integration - Claude Code skill installation

Related Pages

Related topics: System Architecture, Authentication and Authorization

API Modules

The Refly API Modules form the backend service layer that handles tool execution, webhook integration, OpenAPI specification management, and skill orchestration. These modules operate within the apps/api/src/modules/ directory and expose functionality through REST endpoints consumed by the frontend workspace components.

Overview

The API modules provide a structured backend architecture for the Refly platform's core capabilities:

Tool Module

The Tool module manages the lifecycle of tools and tool execution within the Refly workspace. Tools are reusable components that can be invoked by agents during workflow execution.

Tool Service

The ToolService handles tool registration, retrieval, and metadata management. Tools in Refly can belong to toolsets, which group related functionality together.

Tool Execution Service (PTC)

The Prompt-Tool-Calling (PTC) execution service manages the runtime execution of tools during agent reasoning. This service:

• Coordinates tool invocation based on agent decisions
• Manages input/output schemas for tools
• Handles tool result serialization and context injection

Webhook Module

The Webhook module enables event-driven integrations by allowing external services to receive notifications when specific events occur in Refly workflows.

Webhook Configuration

Webhook configuration includes:

• Endpoint URL: The target URL for webhook delivery
• Event Types: Specific events to subscribe to
• Authentication: Headers and secrets for security
• Retry Policy: Configuration for failed delivery attempts

Webhook Event Delivery

graph TD
    A[Workflow Event] --> B[WebhookService]
    B --> C{Event Type Match?}
    C -->|Yes| D[Prepare Payload]
    C -->|No| E[Skip Delivery]
    D --> F{HTTP POST}
    F --> G{Response 2xx?}
    G -->|Success| H[Log Success]
    G -->|Failure| I{Retry Count?}
    I -->|< Max| J[Retry with Backoff]
    J --> F
    I -->|>= Max| K[Mark Failed]

Webhook Error Codes

OpenAPI Module

The OpenAPI module provides integration with OpenAPI specifications, enabling Refly to:

• Parse and validate OpenAPI documents
• Generate tool definitions from specifications
• Support API schema introspection

Request Body Schema

OpenAPI integration follows standard OpenAPI 3.x conventions for request body definitions:

interface RequestBodySchema {
  description?: string;
  descriptionKey?: string; // i18n key for localization
  required?: boolean;
  schema: {
    type: string;
    properties: Record<string, SchemaProperty>;
  };
}

Integration with Frontend Components

The API modules communicate with frontend components through:

1. Context Files (packages/skill-template/src/scheduler/utils/context.ts): Define data structures for tool and result metadata
2. UI Components: Consume API responses for display in the workspace interface

Data Flow

graph LR
    A[Frontend UI] -->|API Request| B[API Module]
    B --> C[Service Logic]
    C --> D[External Service/Tool]
    D --> E[Response]
    C --> F[Context Metadata]
    F --> G[Frontend Render]

Module Configuration

API modules are configured through:

Skill Module Integration

Skills extend the API module functionality by providing pre-built integrations. The skill system references external skill repositories at https://github.com/refly-ai/refly-skills for community-contributed tools and workflows.

Error Handling

Standard error codes returned by API modules:

Related Pages

Related topics: API Modules

Authentication and Authorization

Overview

The Refly platform implements a comprehensive authentication and authorization system that supports multiple authentication methods across both CLI and web interfaces. The system provides secure access control through OAuth 2.0 flows, API key authentication, and email/password credentials.

Architecture Overview

The authentication system is designed with two primary entry points:

• CLI Authentication: Device-based OAuth authorization with optional API key authentication
• Web Authentication: OAuth providers (GitHub, Google) combined with email/password registration and login

graph TD
    subgraph "CLI Authentication"
        CLI[refly CLI] --> LOGIN[refly login]
        LOGIN --> DEVICE[Device Authorization]
        DEVICE --> POLL[Polling for Auth]
        POLL --> SUCCESS{Authorized?}
        SUCCESS -->|Yes| TOKEN[Access Token]
        SUCCESS -->|No| POLL
    end
    
    subgraph "Web Authentication"
        WEB[Web App] --> OAUTH[OAuth Providers]
        WEB --> EMAIL[Email/Password]
        OAUTH --> GH[GitHub]
        OAUTH --> GGL[Google]
    end
    
    subgraph "API Layer"
        TOKEN --> API[API Request]
        API --> GUARD[Auth Guard]
        APIKEY[API Key] --> GUARD
    end

CLI Authentication

Device Authorization Flow

The CLI implements a device authorization flow for OAuth authentication. When a user runs refly login, the CLI initiates a device authorization request and displays a verification URL for the user to complete authentication in a browser.

Flow Steps:

1. CLI generates a unique device ID
2. CLI polls the authorization server at regular intervals (2 seconds)
3. User completes authorization in browser
4. CLI receives access token upon successful authorization

sequenceDiagram
    participant CLI
    participant Browser
    participant Server
    
    CLI->>Server: Request device code
    Server-->>CLI: Device code, user code, verification URL
    CLI->>Browser: Open verification URL
    CLI->>Server: Poll for authorization status
    Browser->>Server: User authenticates
    Server-->>CLI: Authorization granted
    CLI->>Server: Exchange for access token
    Server-->>CLI: Access token + refresh token

Key Implementation Details:

Sources: packages/cli/src/commands/login.ts:1-100

API Key Authentication

For programmatic access, the CLI supports API key authentication. Users can authenticate by setting their API key through environment variables or configuration files.

Environment Variable:

REFLY_API_KEY=<your-api-key>

Configuration File: ~/.refly/config.json

{
  "version": 1,
  "auth": {
    "apiKey": "...",
    "expiresAt": "..."
  },
  "api": {
    "endpoint": "https://api.refly.ai"
  }
}

Sources: packages/cli/README.md

Token Management

The CLI manages OAuth tokens with automatic refresh capability. When an access token expires, the system automatically attempts to refresh it before making API requests.

Token Storage Components:

Refresh Logic:

if (expiresAt && new Date(expiresAt) < new Date()) {
  logger.debug('Access token expired, refreshing...');
  try {
    accessToken = await refreshAccessToken();
  } catch (error) {
    throw new AuthError('Session expired, please login again');
  }
}

Sources: packages/cli/src/api/client.ts:1-80

CLI Status Command

The refly status command provides comprehensive authentication status information including:

Sources: packages/cli/src/commands/status.ts:1-90

Web Authentication

Supported Authentication Methods

The web interface supports multiple authentication providers configured at the server level:

Fallback Behavior: Email authentication is always enabled as a fallback, regardless of server configuration.

Sources: packages/web-core/src/pages/login/index.tsx:1-80

OAuth Flow Implementation

graph LR
    A[Login Page] --> B{Check Provider Enabled}
    B -->|GitHub| C[GitHub OAuth]
    B -->|Google| D[Google OAuth]
    B -->|Email| E[Email Form]
    C --> F[Redirect to /v1/auth/provider]
    D --> F
    E --> G[Form Validation]
    G --> H[Email Signup/Login API]

OAuth URL Construction:

window.location.href = `${serverOrigin}/v1/auth/${provider}`;

Login Handler:

const handleLogin = useCallback((provider: 'github' | 'google') => {
  logEvent('auth::oauth_login_click', provider);
  authStore.setLoginInProgress(true);
  authStore.setLoginProvider(provider);
  storePendingRedirect();
  window.location.href = `${serverOrigin}/v1/auth/${provider}`;
}, [authStore]);

Sources: packages/web-core/src/pages/login/index.tsx:80-120

Email/Password Authentication

Email authentication includes comprehensive validation rules:

Password Validation Implementation:

rules={[
  {
    required: true,
    message: t('verifyRules.passwordRequired'),
  },
  ...(authStore.isSignUpMode
    ? [
        {
          min: 8,
          message: t('verifyRules.passwordMin'),
        },
      ]
    : []),
]}

Sources: packages/web-core/src/components/login-modal/login-content.tsx:1-100

Authentication State Management

The authentication system maintains state through an auth store that tracks:

Email Signup Request:

const { data } = await getClient().emailSignup({
  body: {
    email: values.email,
    password: values.password,
  },
});

Sources: packages/web-core/src/pages/login/index.tsx:120-180

Server-Side Configuration

Application Auth Config

The API server provides configurable authentication options through environment variables:

Sources: apps/api/src/modules/config/app.config.ts:1-50

OAuth Provider Configuration

OAuth providers are configured with client credentials:

twitter: {
  enabled: process.env.TWITTER_AUTH_ENABLED === 'true' || false,
  clientId: process.env.TWITTER_CLIENT_ID || 'test',
  clientSecret: process.env.TWITTER_CLIENT_SECRET || 'test',
  callbackUrl: process.env.TWITTER_CALLBACK_URL || 'test',
},
notion: {
  enabled: process.env.NOTION_AUTH_ENABLED === 'true' || false,
  clientId: process.env.NOTION_CLIENT_ID || 'test',
  clientSecret: process.env.NOTION_CLIENT_SECRET || 'test',
  callbackUrl: process.env.NOTION_CALLBACK_URL || 'test',
},

Sources: apps/api/src/modules/config/app.config.ts:50-80

Authentication Methods Summary

Error Handling

CLI Error Codes

Web Error Handling

The web interface implements form validation with user-friendly error messages and loading states:

const handleEmailAuth = useCallback(async () => {
  let values: FormValues;
  try {
    values = await form.validateFields();
  } catch (error) {
    console.error('Error validating form fields', error);
    return;
  }
  
  authStore.setLoginProvider('email');
  authStore.setLoginInProgress(true);
  // ... authentication logic
}, []);

Best Practices

1. CLI Authentication: Use refly login for interactive sessions; use API keys for automated workflows
2. Token Refresh: The CLI automatically handles token refresh; ensure network connectivity for re-authentication
3. Security: Never commit API keys to version control; use environment variables
4. Session Management: Use refly logout to clear stored credentials when done

Related Commands

refly login        # Authenticate with OAuth or API key
refly logout       # Remove stored credentials
refly status       # Check authentication status
refly whoami       # Display current user information

Sources: packages/cli/README.md

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Security or permission risk: [Question] Sandbox deployment fails with "AggregateError: All promises were rejected" - Scalebox template and setup inq…

• Severity: high
• Finding: Security or permission risk is backed by a source signal: [Question] Sandbox deployment fails with "AggregateError: All promises were rejected" - Scalebox template and setup inq…. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/issues/2088

2. Installation risk: v0.5.0

• Severity: medium
• Finding: Installation risk is backed by a source signal: v0.5.0. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/releases/tag/v0.5.0

3. Installation risk: v0.7.0

• Severity: medium
• Finding: Installation risk is backed by a source signal: v0.7.0. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/releases/tag/v0.7.0

4. Installation risk: v0.8.0

• Severity: medium
• Finding: Installation risk is backed by a source signal: v0.8.0. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/releases/tag/v0.8.0

5. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | github_repo:759799529 | https://github.com/refly-ai/refly | host_targets=claude, claude_code, cursor

6. Configuration risk: translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds

• Severity: medium
• Finding: Configuration risk is backed by a source signal: translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry budget exhausted in 7 seconds. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/issues/2278

7. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | github_repo:759799529 | https://github.com/refly-ai/refly | README/documentation is current enough for a first validation pass.

8. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | github_repo:759799529 | https://github.com/refly-ai/refly | last_activity_observed missing

9. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium

10. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | github_repo:759799529 | https://github.com/refly-ai/refly | no_demo; severity=medium

11. Security or permission risk: Security findings in executable artifacts

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: Security findings in executable artifacts. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/issues/2276

12. Security or permission risk: v0.10.0

• Severity: medium
• Finding: Security or permission risk is backed by a source signal: v0.10.0. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/refly-ai/refly/releases/tag/v0.10.0

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using refly with real data or production workflows.

• translate/index.ts — 429 retries at 1s, 2s, 4s ignore Retry-After, retry - github / github_issue
• Security findings in executable artifacts - github / github_issue
• [[Question] Sandbox deployment fails with "AggregateError: All promises w](https://github.com/refly-ai/refly/issues/2088) - github / github_issue
• 🤖 Connect your agent to MEEET STATE — earn $MEEET on Solana - github / github_issue
• v1.1.0 - github / github_release
• v0.10.0 - github / github_release
• v0.9.1 - github / github_release
• v0.9.0 - github / github_release
• v0.8.0 - github / github_release
• v0.7.1 - github / github_release
• v0.7.0 - github / github_release
• v0.6.0 - github / github_release