# prompt-engineering/chat-flow architecture

> Architecture diagram of the GitHub repository prompt-engineering/chat-flow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prompt-engineering/chat-flow
- Repository: https://github.com/prompt-engineering/chat-flow

## Overview

##### Main Components
- Frontend Application (Next.js):
- Pages and Routes: Represented in src/app (e.g. [lang]/chatgpt, click-flow, flow-editor, and error pages).
- I18N: Internationalization support in src/i18n and i18n directories.
- Layout and Navigation: Layout components inside src/layout, NavBar etc.

- API / Backend Services:
- API Routes: Provided in src/api and also under src/pages/api (e.g. chat.ts, conversation.ts, user.ts, and proxy endpoints).
- Serverless functions: Next.js API endpoints that handle chat interactions and possibly middleware (src/middleware.ts).

- Flow Management System:
- Flow Editor: Managed in src/app/[lang]/flow-editor where ReactFlow is used to render the graph data.
- Flows Module: Includes flows/actions, flows/components, flows/functions and react-flow-nodes. These modules use libraries such as dot-parser and dagre for graph layout, and custom modules for handling JSON paths, math expressions, etc.
- Repl Server & UnitMesh: Code in src/flows/unitmesh which handles websocket connections using Rx.js and performs code-as-data handling.

- Data Persistence & External Services:
- Database: Uses a MySQL database that is managed via Prisma (prisma/schema.prisma) and deployed on Planetscale.
- Environment configuration: .env and scripts/scripts (e.g. gen-enc.js) for encryption key generation and environment setups.
- Deployment: Vercel deployment configuration (vercel.json, next.config.js, next-sitemap.config.js) and CI workflows (.github/workflows/ci.yaml).

##### Relationships and Interactions
- The Frontend connects to the backend API routes to perform chat and conversation functionalities.
- The UI directly interacts with the Flow Editor components, which in turn use the flows modules to generate or interpret the workflow graphs.
- The flows system leverages a separation between user interactions (click-flow, flow-editor pages) and the underlying business logic (flow-actions, flow-functions) to convert chat instructions into automated workflows.
- The API layer mediates database interactions through Prisma (see src/storage for Planetscale integration) and exposes endpoints for chat, conversation, and user management.
- There is a clear coordination between internal asynchronous modules (for example, the ReplService for real-time operations) and external services (Planetscale for data persistence, Vercel for hosting).

##### Architectural Patterns and Design Principles
- Separation of concerns: Frontend (UI components, pages) is clearly separated from backend API logic and flow processing.
- Modular design: The project is partitioned into small, domain-specific modules (flows, components, API, storage, configurations).
- React and Next.js conventions: Utilizing Next.js routing, serverless functions, and built-in middleware for better scalability.
- Graph-based workflow design: Using flowchart layout libraries (ReactFlow, dagre) and node-based architectures to visually construct chat automation.
- Internationalization (i18n): Language assets and README guidance (README.zh-CN.md, i18n directory) point to a design that supports multi-language deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Frontend (Next.js UI)
    subgraph "Frontend (Next.js UI)"
        FP1["Pages: ChatGPT"]
        FP2["Pages: Click-Flow"]
        FP3["Pages: Flow Editor"]
        FC1["UI Components: ChatGPT"]
        FC2["UI Components: ClickPrompt"]
        FC3["UI Components: Markdown Viewer"]
        FI1["I18N: src/i18n"]
        FI2["I18N: i18n"]
        FL1["Layout: src/app/[lang]/layout.tsx"]
        FL2["NavBar: src/layout/NavBar.tsx"]
    end
    class FP1,FP2,FP3,FC1,FC2,FC3,FI1,FI2,FL1,FL2 front

    %% Flow Management System
    subgraph "Flow Management System"
        FE1["Flow Editor: src/app/[lang]/flow-editor"]
        FM1["Flows: Actions (src/flows/actions)"]
        FM2["Flows: Components (src/flows/components)"]
        FM3["Flows: Functions (src/flows/flow-functions)"]
        FM4["Flows: React-Flow Nodes (src/flows/react-flow-nodes)"]
        FRS["Repl Server & UnitMesh: src/flows/unitmesh/ReplService.ts"]
    end
    class FE1,FM1,FM2,FM3,FM4,FRS flow

    %% API / Backend Services
    subgraph "API Layer (Backend Services)"
        AR1["API: src/api/chat.ts"]
        AR2["API: src/api/conversation.ts"]
        AR3["API: src/api/user.ts"]
        AR4["API: src/pages/api/chatgpt/chat.ts"]
        AR5["API: src/pages/api/chatgpt/conversation.ts"]
        AR6["API: src/pages/api/chatgpt/user.ts"]
        AM["Middleware: src/middleware.ts"]
    end
    class AR1,AR2,AR3,AR4,AR5,AR6,AM backend

    %% Data Persistence & External Services
    subgraph "Data Persistence & External Services"
        DP1["Database: Prisma (prisma/schema.prisma)"]
        DP2["Database: Planetscale (src/storage/planetscale.ts)"]
        EC1["Env Config: .env.example"]
        EC2["Encryption Script: scripts/gen-enc.js"]
        DC1["Deployment: vercel.json"]
        DC2["Deployment: next.config.js"]
        DC3["Deployment: next-sitemap.config.js"]
        DC4["CI: .github/workflows/ci.yaml"]
    end
    class DP1,DP2,EC1,EC2,DC1,DC2,DC3,DC4 persistence

    %% Relationships
    FP1 -->|"calls"| AR1
    FP3 -->|"interacts"| FE1
    FE1 -->|"triggers"| FM1
    AR1 -->|"queries"| DP1
    AM -->|"secures"| DP1

    %% Additional connections within Frontend (internal composition)
    FC1 --- FP1
    FC2 --- FP2
    FC3 --- FP1
    FI1 --- FP1
    FI2 --- FP1
    FL1 --- FP1
    FL2 --- FP1

    %% Connections within Flow Management System
    FE1 -->|"integrates"| FM2
    FE1 -->|"calculates"| FM3
    FE1 -->|"displays"| FM4
    FM3 --- FRS

    %% Connections from API Layer to Data Persistence
    AR4 -->|"queries"| DP2
    AR5 -->|"queries"| DP2
    AR6 -->|"queries"| DP2

    %% Deployment and Environment Configuration connections
    EC1 -->|"configures"| DC1
    EC2 -->|"supports"| DC1

    %% Click Events for Frontend Application
    click FP1 "https://github.com/prompt-engineering/chat-flow/tree/master/src/app/[lang]/chatgpt"
    click FP2 "https://github.com/prompt-engineering/chat-flow/tree/master/src/app/[lang]/click-flow"
    click FP3 "https://github.com/prompt-engineering/chat-flow/tree/master/src/app/[lang]/flow-editor"
    click FC1 "https://github.com/prompt-engineering/chat-flow/tree/master/src/components/chatgpt"
    click FC2 "https://github.com/prompt-engineering/chat-flow/tree/master/src/components/ClickPrompt"
    click FC3 "https://github.com/prompt-engineering/chat-flow/tree/master/src/components/markdown"
    click FI1 "https://github.com/prompt-engineering/chat-flow/tree/master/src/i18n"
    click FI2 "https://github.com/prompt-engineering/chat-flow/tree/master/i18n"
    click FL1 "https://github.com/prompt-engineering/chat-flow/blob/master/src/app/[lang]/layout.tsx"
    click FL2 "https://github.com/prompt-engineering/chat-flow/blob/master/src/layout/NavBar.tsx"

    %% Click Events for API / Backend Services
    click AR1 "https://github.com/prompt-engineering/chat-flow/blob/master/src/api/chat.ts"
    click AR2 "https://github.com/prompt-engineering/chat-flow/blob/master/src/api/conversation.ts"
    click AR3 "https://github.com/prompt-engineering/chat-flow/blob/master/src/api/user.ts"
    click AR4 "https://github.com/prompt-engineering/chat-flow/blob/master/src/pages/api/chatgpt/chat.ts"
    click AR5 "https://github.com/prompt-engineering/chat-flow/blob/master/src/pages/api/chatgpt/conversation.ts"
    click AR6 "https://github.com/prompt-engineering/chat-flow/blob/master/src/pages/api/chatgpt/user.ts"
    click AM "https://github.com/prompt-engineering/chat-flow/blob/master/src/middleware.ts"

    %% Click Events for Flow Management System
    click FE1 "https://github.com/prompt-engineering/chat-flow/tree/master/src/app/[lang]/flow-editor"
    click FM1 "https://github.com/prompt-engineering/chat-flow/tree/master/src/flows/actions"
    click FM2 "https://github.com/prompt-engineering/chat-flow/tree/master/src/flows/components"
    click FM3 "https://github.com/prompt-engineering/chat-flow/tree/master/src/flows/flow-functions"
    click FM4 "https://github.com/prompt-engineering/chat-flow/tree/master/src/flows/react-flow-nodes"
    click FRS "https://github.com/prompt-engineering/chat-flow/blob/master/src/flows/unitmesh/ReplService.ts"

    %% Click Events for Data Persistence & External Services
    click DP1 "https://github.com/prompt-engineering/chat-flow/blob/master/prisma/schema.prisma"
    click DP2 "https://github.com/prompt-engineering/chat-flow/blob/master/src/storage/planetscale.ts"
    click EC1 "https://github.com/prompt-engineering/chat-flow/blob/master/.env.example"
    click EC2 "https://github.com/prompt-engineering/chat-flow/blob/master/scripts/gen-enc.js"
    click DC1 "https://github.com/prompt-engineering/chat-flow/blob/master/vercel.json"
    click DC2 "https://github.com/prompt-engineering/chat-flow/blob/master/next.config.js"
    click DC3 "https://github.com/prompt-engineering/chat-flow/blob/master/next-sitemap.config.js"
    click DC4 "https://github.com/prompt-engineering/chat-flow/blob/master/.github/workflows/ci.yaml"

    %% Styles
    classDef front fill:#aee1ff,stroke:#333,stroke-width:1px,color:#000
    classDef backend fill:#b7e1cd,stroke:#333,stroke-width:1px,color:#000
    classDef flow fill:#dab6fc,stroke:#333,stroke-width:1px,color:#000
    classDef persistence fill:#ffe699,stroke:#333,stroke-width:1px,color:#000
```
