# appflowy-io/appflowy-chat architecture

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

- Interactive diagram: https://gitdiagram.com/appflowy-io/appflowy-chat
- Repository: https://github.com/appflowy-io/appflowy-chat

## Overview

##### Project type and purpose
- This is a TypeScript/React component library (npm package) named “AppFlowy Web Chat.”
- Purpose: provide a fully-featured, themeable chat UI (with AI-writing helpers) that integrates with an AppFlowy Cloud backend.

##### File structure
- Top-level build & config: vite.config.ts, tsconfig.json, postcss.config.ts, tailwind.config.ts, jest.config.js, eslint.config.js, GitHub workflows.
- Core source (`src/`):
- UI components (`src/components/*`, `src/chat/*`, `src/writer/*`, `src/ui/*`)
- State & context providers (`src/provider/*`)
- Hooks & utilities (`src/hooks/*`, `src/lib/*`)
- API clients (`src/request/*.ts`)
- i18n (`src/i18n/*`), assets & styles
- Demo app (`src/dev/*`) to preview and test locally.

##### README for additional insights
- Public API: `<Chat {...ChatProps} />` plus `ChatRequest` and optional callbacks (onOpenView, onCloseSelectionMode, etc.).
- Dependencies: expects an AppFlowy Cloud instance for persisting messages and AI-writing tokens.

##### Main components & their relationships
a. UI Layer
- Chat container (`src/chat/index.tsx`, `src/chat/main.tsx`)
- Message list & input (`src/components/chat-messages/*`, `src/components/chat-input/*`)
- AI-writer module (`src/components/ai-writer/*`, `src/writer/*`)
b. State & Context Providers
- ChatSessionProvider, MessagesProvider, AIWriterProvider, SelectionModeProvider, etc.
c. Data/API Layer
- `ChatRequest` → AppFlowy Cloud chat REST endpoints
- `WriterRequest` → AI-service backend for writing enhancements
d. Utility Layer
- Hooks (`use-chat-settings-loader`, `use-views-loader`, etc.)
- Helpers (`animations.ts`, `copy.ts`, `requets.ts`, `utils.ts`)
e. External Services
- AppFlowy Cloud API
- (Optional) AI service endpoint
f. Dev & Build Tooling
- Vite dev server, bundling, testing, linting, CI workflows

##### Architectural patterns & design principles
- Component-driven UI with clear separation of presentation and logic
- Context-based state management for global concerns (messages stream, theming, selection mode)
- API abstraction layers to decouple HTTP from components
- Hook-driven data fetching for side-effects and caching
- Theming via CSS variables and darkMode dataset attribute
- i18n integration at the root

- UI Components
- Context Providers
- Hooks & Utils
- API Clients
- External Services
- Dev/Demo/Build
- UI → Providers (consumes context)
- Providers → Hooks/Utils (for data loading)
- Hooks → API Clients (invoke HTTP requests)
- API Clients → AppFlowy Cloud / AI Service (external)
- Build tool → Demo App and Library output
c. Patterns:
- Context boundary
- Hook-based side-effects
- API request flow
d. Technologies:
- React/TSX
- Vite, TailwindCSS, PostCSS
- pnpm, Jest, ESLint
- i18next for localization

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% UI Layer
  subgraph "UI Components"
    direction TB
    ChatContainer["Chat Container\nsrc/chat/index.tsx"]:::ui
    ChatMain["Chat Main\nsrc/chat/main.tsx"]:::ui
    subgraph "Message List Components"
      direction TB
      MsgIndex["Index\nsrc/components/chat-messages/index.tsx"]:::ui
      AssistantMsg["Assistant Message\nsrc/components/chat-messages/assistant-message.tsx"]:::ui
      HumanQ["Human Question\nsrc/components/chat-messages/human-question.tsx"]:::ui
      Message["Message\nsrc/components/chat-messages/message.tsx"]:::ui
      MsgActions["Message Actions\nsrc/components/chat-messages/message-actions.tsx"]:::ui
      MsgSuggestions["Message Suggestions\nsrc/components/chat-messages/message-suggestions.tsx"]:::ui
    end
    subgraph "Chat Input Components"
      direction TB
      ChatInput["Input\nsrc/components/chat-input/index.tsx"]:::ui
      RelatedViews["Related Views\nsrc/components/chat-input/related-views/index.tsx"]:::ui
    end
    subgraph "AI Writer Module"
      direction TB
      AIWriterIndex["AI Writer\nsrc/components/ai-writer/index.tsx"]:::ui
      AIWriterMenu["Menu Content\nsrc/components/ai-writer/ai-writer-menu-content.tsx"]:::ui
      RenderEditor["Render Editor\nsrc/components/ai-writer/render-editor.tsx"]:::ui
      Tools["Tools Folder\nsrc/components/ai-writer/tools"]:::ui
      WriterIndex["Writer Core\nsrc/writer/index.ts"]:::ui
      UseAIWriter["useAIWriter\nsrc/writer/use-ai-writer.tsx"]:::ui
    end
  end

  %% State & Context Layer
  subgraph "State & Context Providers"
    direction TB
    MsgProvider["Messages Provider\nsrc/provider/messages-provider.tsx"]:::state
    HandlerProvider["Messages Handler\nsrc/provider/messages-handler-provider.tsx"]:::state
    SelectionProvider["Selection Mode\nsrc/provider/selection-mode-provider.tsx"]:::state
    SuggestionsProvider["Suggestions\nsrc/provider/suggestions-provider.tsx"]:::state
    AIAssistProvider["AI Assistant\nsrc/provider/ai-assistant-provider.tsx"]:::state
    ResponseFormat["Response Format\nsrc/provider/response-format-provider.tsx"]:::state
    MsgAnimProvider["Message Animation\nsrc/provider/message-animation-provider.tsx"]:::state
    EditorProvider["Editor Provider\nsrc/provider/editor-provider.tsx"]:::state
  end

  %% Hooks & Utils Layer
  subgraph "Hooks"
    direction TB
    ChatSettings["useChatSettingsLoader\nsrc/hooks/use-chat-settings-loader.ts"]:::hook
    ViewsLoader["useViewsLoader\nsrc/hooks/use-views-loader.ts"]:::hook
    UserLoader["useUserLoader\nsrc/hooks/use-user-loader.ts"]:::hook
    ToastHook["useToast\nsrc/hooks/use-toast.ts"]:::hook
    CheckboxTree["useCheckboxTree\nsrc/hooks/use-checkbox-tree.ts"]:::hook
  end
  subgraph "Utility Functions"
    direction TB
    Animations["animations.ts\nsrc/lib/animations.ts"]:::util
    CopyUtil["copy.ts\nsrc/lib/copy.ts"]:::util
    RequestsUtil["requets.ts\nsrc/lib/requets.ts"]:::util
    Utils["utils.ts\nsrc/lib/utils.ts"]:::util
    ViewsUtil["views.ts\nsrc/lib/views.ts"]:::util
  end

  %% API Clients Layer
  subgraph "API Clients"
    direction TB
    ChatRequest["Chat Request\nsrc/request/chat-request.ts"]:::api
    WriterRequest["Writer Request\nsrc/request/writer-request.ts"]:::api
    RequestIndex["Index\nsrc/request/index.ts"]:::api
  end

  %% External Services
  subgraph "External Services"
    direction TB
    AppFlowyCloud["AppFlowy Cloud API"]:::ext
    AIService["AI Service Endpoint"]:::ext
  end

  %% Dev & Build Tooling
  subgraph "Dev & Build"
    direction TB
    DemoApp["Demo App\nsrc/dev/main.tsx"]:::dev
    DevApp["App\nsrc/dev/app.tsx"]:::dev
    DevChat["Chat Preview\nsrc/dev/chat.tsx"]:::dev
    DevWriter["Writer Preview\nsrc/dev/writer.tsx"]:::dev
    DevIndex["Index HTML\nsrc/dev/index.html"]:::dev
    Vite["Vite Config\nvite.config.ts"]:::dev
    TSConfig["tsconfig.json"]:::dev
    PostCSS["postcss.config.ts"]:::dev
    Tailwind["tailwind.config.ts"]:::dev
    JestConfig["jest.config.js"]:::dev
    ESLint["eslint.config.js"]:::dev
  end

  %% Connections
  ChatContainer -->|consumes| MsgProvider
  ChatMain -->|consumes| MsgProvider
  MsgIndex -->|renders| MsgProvider
  ChatInput -->|dispatches| MsgProvider
  AIWriterIndex -->|uses| AIAssistProvider

  MsgProvider -->|uses| ChatSettings
  MsgProvider -->|uses| ViewsLoader
  AIAssistProvider -->|uses| UseAIWriter
  SelectionProvider -->|uses| CheckboxTree

  ChatSettings -->|calls| ChatRequest
  ViewsLoader -->|calls| RequestIndex
  UseAIWriter -->|calls| WriterRequest

  ChatRequest -->|HTTP| AppFlowyCloud
  WriterRequest -->|HTTP| AIService

  DemoApp -->|builds| ChatContainer
  Vite -->|bundles| DemoApp
  Vite -->|bundles| ChatContainer

  %% Click Events
  click ChatContainer "https://github.com/appflowy-io/appflowy-chat/blob/main/src/chat/index.tsx"
  click ChatMain "https://github.com/appflowy-io/appflowy-chat/blob/main/src/chat/main.tsx"
  click MsgIndex "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/index.tsx"
  click AssistantMsg "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/assistant-message.tsx"
  click HumanQ "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/human-question.tsx"
  click Message "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/message.tsx"
  click MsgActions "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/message-actions.tsx"
  click MsgSuggestions "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-messages/message-suggestions.tsx"
  click ChatInput "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-input/index.tsx"
  click RelatedViews "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/chat-input/related-views/index.tsx"
  click AIWriterIndex "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/ai-writer/index.tsx"
  click AIWriterMenu "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/ai-writer/ai-writer-menu-content.tsx"
  click RenderEditor "https://github.com/appflowy-io/appflowy-chat/blob/main/src/components/ai-writer/render-editor.tsx"
  click Tools "https://github.com/appflowy-io/appflowy-chat/tree/main/src/components/ai-writer/tools"
  click WriterIndex "https://github.com/appflowy-io/appflowy-chat/blob/main/src/writer/index.ts"
  click UseAIWriter "https://github.com/appflowy-io/appflowy-chat/blob/main/src/writer/use-ai-writer.tsx"
  click MsgProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/messages-provider.tsx"
  click HandlerProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/messages-handler-provider.tsx"
  click SelectionProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/selection-mode-provider.tsx"
  click SuggestionsProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/suggestions-provider.tsx"
  click AIAssistProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/ai-assistant-provider.tsx"
  click ResponseFormat "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/response-format-provider.tsx"
  click MsgAnimProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/message-animation-provider.tsx"
  click EditorProvider "https://github.com/appflowy-io/appflowy-chat/blob/main/src/provider/editor-provider.tsx"
  click ChatSettings "https://github.com/appflowy-io/appflowy-chat/blob/main/src/hooks/use-chat-settings-loader.ts"
  click ViewsLoader "https://github.com/appflowy-io/appflowy-chat/blob/main/src/hooks/use-views-loader.ts"
  click UserLoader "https://github.com/appflowy-io/appflowy-chat/blob/main/src/hooks/use-user-loader.ts"
  click ToastHook "https://github.com/appflowy-io/appflowy-chat/blob/main/src/hooks/use-toast.ts"
  click CheckboxTree "https://github.com/appflowy-io/appflowy-chat/blob/main/src/hooks/use-checkbox-tree.ts"
  click Animations "https://github.com/appflowy-io/appflowy-chat/blob/main/src/lib/animations.ts"
  click CopyUtil "https://github.com/appflowy-io/appflowy-chat/blob/main/src/lib/copy.ts"
  click RequestsUtil "https://github.com/appflowy-io/appflowy-chat/blob/main/src/lib/requets.ts"
  click Utils "https://github.com/appflowy-io/appflowy-chat/blob/main/src/lib/utils.ts"
  click ViewsUtil "https://github.com/appflowy-io/appflowy-chat/blob/main/src/lib/views.ts"
  click ChatRequest "https://github.com/appflowy-io/appflowy-chat/blob/main/src/request/chat-request.ts"
  click WriterRequest "https://github.com/appflowy-io/appflowy-chat/blob/main/src/request/writer-request.ts"
  click RequestIndex "https://github.com/appflowy-io/appflowy-chat/blob/main/src/request/index.ts"
  click DemoApp "https://github.com/appflowy-io/appflowy-chat/blob/main/src/dev/main.tsx"
  click DevApp "https://github.com/appflowy-io/appflowy-chat/blob/main/src/dev/app.tsx"
  click DevChat "https://github.com/appflowy-io/appflowy-chat/blob/main/src/dev/chat.tsx"
  click DevWriter "https://github.com/appflowy-io/appflowy-chat/blob/main/src/dev/writer.tsx"
  click DevIndex "https://github.com/appflowy-io/appflowy-chat/blob/main/src/dev/index.html"

  %% Styles
  classDef ui fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
  classDef state fill:#c8e6c9,stroke:#388e3c,color:#1b5e20
  classDef hook fill:#d1c4e9,stroke:#7e57c2,color:#4a148c
  classDef util fill:#f0f4c3,stroke:#c0ca33,color:#827717
  classDef api fill:#ffe0b2,stroke:#fb8c00,color:#e65100
  classDef ext fill:#eeeeee,stroke:#9e9e9e,color:#424242
  classDef dev fill:#fff9c4,stroke:#fdd835,color:#f57f17
```
