# shakib-zeydi/raayanchat-widget architecture

> Architecture diagram of the GitHub repository shakib-zeydi/raayanchat-widget, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shakib-zeydi/raayanchat-widget
- Repository: https://github.com/shakib-zeydi/raayanchat-widget

## Overview

Rayan Chat Widget is an embeddable React chat interface. A host page mounts the widget; visitors register or resume a session, choose AI or human support, then send messages and view history or live operator updates. The graph separates the widget’s user-facing flows, conversation state, network adapters, and browser persistence. Several connections are supported by the source index or README rather than full excerpts; those limits are reflected by omitting uncertain links.

Main entry points: [`src/components/widget.tsx`](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/widget.tsx) (Widget shell), [`src/components/human-chat.tsx`](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/human-chat.tsx) (Human chat), [`src/components/ai-chat.tsx`](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/ai-chat.tsx) (AI chat), [`src/services/http.ts`](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/http.ts) (HTTP client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_embed["Embed and widget"]
  node_mount["Widget mount<br/>[main.tsx]"]
  node_widget["Widget shell<br/>[widget.tsx]"]
  node_mode["Mode selector"]
  node_header["Chat header<br/>[chat-header.tsx]"]
end

subgraph group_conversation["Conversation experiences"]
  node_aichat["AI chat<br/>[ai-chat.tsx]"]
  node_aihook["AI conversation"]
  node_humanchat["Human chat<br/>[human-chat.tsx]"]
  node_humanhook["Human conversation"]
  node_historyread["Human read tracking"]
  node_notifications["Human notifications"]
  node_messages["Message list<br/>[message-list.tsx]"]
  node_input["Message input<br/>[message-input.tsx]"]
end

subgraph group_state["Session and state"]
  node_visitorform["Visitor form<br/>[visitor-form.tsx]"]
  node_sessionhook["Visitor session"]
  node_storage[("Widget storage<br/>[widget-storage.ts]")]
end

subgraph group_connectivity["Service connectivity"]
  node_aiapi["AI API adapter"]
  node_visitorapi["Visitor API adapter<br/>[visitor-api.ts]"]
  node_humanapi["Notification API"]
  node_http["HTTP client<br/>[http.ts]"]
  node_echo["Realtime client<br/>[echo.ts]"]
end

node_host(("Host website"))
node_backend["Chat backend"]
node_realtime["WebSocket service"]

node_host -->|"mounts"| node_mount
node_mount -->|"renders"| node_widget
node_widget -->|"creates session"| node_sessionhook
node_widget -->|"checks unread"| node_notifications
node_widget -->|"renders"| node_visitorform
node_widget -->|"offers modes"| node_mode
node_widget -->|"renders"| node_header
node_widget -->|"renders"| node_aichat
node_widget -->|"renders"| node_humanchat
node_aichat -->|"uses"| node_aihook
node_aichat -->|"renders"| node_messages
node_aichat -->|"renders"| node_input
node_humanchat -->|"uses"| node_humanhook
node_humanchat -->|"uses"| node_historyread
node_humanchat -->|"renders"| node_messages
node_humanchat -->|"renders"| node_input
node_sessionhook -->|"registers visitor"| node_visitorapi
node_sessionhook -->|"reads and saves"| node_storage
node_aihook -->|"loads and sends"| node_aiapi
node_aihook -->|"persists conversation"| node_storage
node_humanhook -->|"persists conversation"| node_storage
node_humanhook -->|"subscribes"| node_echo
node_notifications -->|"loads status"| node_humanapi
node_notifications -->|"subscribes"| node_echo
node_aiapi -->|"requests"| node_http
node_visitorapi -->|"requests"| node_http
node_humanapi -->|"requests"| node_http
node_http -->|"sends HTTP"| node_backend
node_echo -->|"connects"| node_realtime

click node_mount "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/main.tsx"
click node_widget "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/widget.tsx"
click node_mode "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/conversation-mode-selector.tsx"
click node_header "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/chat-header.tsx"
click node_visitorform "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/visitor-form.tsx"
click node_sessionhook "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-visitor-session.ts"
click node_storage "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/storage/widget-storage.ts"
click node_aichat "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/ai-chat.tsx"
click node_aihook "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-ai-conversation.ts"
click node_humanchat "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/human-chat.tsx"
click node_humanhook "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-conversation.ts"
click node_historyread "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-conversation-read.ts"
click node_notifications "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-notifications.ts"
click node_messages "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/message-list.tsx"
click node_input "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/message-input.tsx"
click node_aiapi "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/ai-conversation-api.ts"
click node_visitorapi "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/visitor-api.ts"
click node_humanapi "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/human-notifications.ts"
click node_http "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/http.ts"
click node_echo "https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/lib/echo.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mount,node_widget,node_mode,node_header toneBlue
class node_aichat,node_aihook,node_humanchat,node_humanhook,node_historyread,node_notifications,node_messages,node_input toneAmber
class node_visitorform,node_sessionhook,node_storage toneMint
class node_aiapi,node_visitorapi,node_humanapi,node_http,node_echo toneRose
class node_host,node_backend,node_realtime toneIndigo
```

## Components

### Embed and widget

- [Widget mount](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/main.tsx): `src/main.tsx`
- [Widget shell](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/widget.tsx): `src/components/widget.tsx`
- [Mode selector](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/conversation-mode-selector.tsx): `src/components/conversation-mode-selector.tsx`
- [Chat header](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/chat-header.tsx): `src/components/chat-header.tsx`

### Conversation experiences

- [AI chat](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/ai-chat.tsx): `src/components/ai-chat.tsx`
- [AI conversation](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-ai-conversation.ts): `src/hooks/use-ai-conversation.ts`
- [Human chat](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/human-chat.tsx): `src/components/human-chat.tsx`
- [Human conversation](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-conversation.ts): `src/hooks/use-human-conversation.ts`
- [Human read tracking](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-conversation-read.ts): `src/hooks/use-human-conversation-read.ts`
- [Human notifications](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-human-notifications.ts): `src/hooks/use-human-notifications.ts`
- [Message list](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/message-list.tsx): `src/components/message-list.tsx`
- [Message input](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/message-input.tsx): `src/components/message-input.tsx`

### Session and state

- [Visitor form](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/components/visitor-form.tsx): `src/components/visitor-form.tsx`
- [Visitor session](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/hooks/use-visitor-session.ts): `src/hooks/use-visitor-session.ts`
- [Widget storage](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/storage/widget-storage.ts): `src/storage/widget-storage.ts`

### Service connectivity

- [AI API adapter](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/ai-conversation-api.ts): `src/services/ai-conversation-api.ts`
- [Visitor API adapter](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/visitor-api.ts): `src/services/visitor-api.ts`
- [Notification API](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/human-notifications.ts): `src/services/human-notifications.ts`
- [HTTP client](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/services/http.ts): `src/services/http.ts`
- [Realtime client](https://github.com/shakib-zeydi/raayanchat-widget/blob/main/src/lib/echo.ts): `src/lib/echo.ts`

### Other components

- **Host website**
- **Chat backend**
- **WebSocket service**

## Connections

- Host website → Widget mount: mounts (evidence: `src/main.tsx`)
- Widget mount → Widget shell: renders (evidence: `src/main.tsx`)
- Widget shell → Visitor session: creates session (evidence: `src/components/widget.tsx`)
- Widget shell → Human notifications: checks unread (evidence: `src/components/widget.tsx`)
- Widget shell → Visitor form: renders (evidence: `src/components/widget.tsx`)
- Widget shell → Mode selector: offers modes (evidence: `src/components/widget.tsx`)
- Widget shell → Chat header: renders (evidence: `src/components/widget.tsx`)
- Widget shell → AI chat: renders (evidence: `src/components/widget.tsx`)
- Widget shell → Human chat: renders (evidence: `src/components/widget.tsx`)
- AI chat → AI conversation: uses (evidence: `src/components/ai-chat.tsx`)
- AI chat → Message list: renders (evidence: `src/components/ai-chat.tsx`)
- AI chat → Message input: renders (evidence: `src/components/ai-chat.tsx`)
- Human chat → Human conversation: uses (evidence: `src/components/human-chat.tsx`)
- Human chat → Human read tracking: uses (evidence: `src/components/human-chat.tsx`)
- Human chat → Message list: renders (evidence: `src/components/human-chat.tsx`)
- Human chat → Message input: renders (evidence: `src/components/human-chat.tsx`)
- Visitor session → Visitor API adapter: registers visitor (evidence: `src/hooks/use-visitor-session.ts`)
- Visitor session → Widget storage: reads and saves (evidence: `src/hooks/use-visitor-session.ts`)
- AI conversation → AI API adapter: loads and sends (evidence: `src/hooks/use-ai-conversation.ts`)
- AI conversation → Widget storage: persists conversation (evidence: `src/hooks/use-ai-conversation.ts`)
- Human conversation → Widget storage: persists conversation (evidence: `src/hooks/use-human-conversation.ts`)
- Human conversation → Realtime client: subscribes (evidence: `src/hooks/use-human-conversation.ts`)
- Human notifications → Notification API: loads status (evidence: `src/hooks/use-human-notifications.ts`)
- Human notifications → Realtime client: subscribes (evidence: `src/hooks/use-human-notifications.ts`)
- AI API adapter → HTTP client: requests (evidence: `src/services/ai-conversation-api.ts`)
- Visitor API adapter → HTTP client: requests (evidence: `src/services/visitor-api.ts`)
- Notification API → HTTP client: requests (evidence: `src/services/human-notifications.ts`)
- HTTP client → Chat backend: sends HTTP (evidence: `src/services/http.ts`)
- Realtime client → WebSocket service: connects (evidence: `src/lib/echo.ts`)
