# chathub-dev/chathub architecture

> Architecture diagram of the GitHub repository chathub-dev/chathub, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/chathub-dev/chathub
- Repository: https://github.com/chathub-dev/chathub

## Overview

#### Purpose and delivery model
ChatHub is a Chromium browser extension that provides one chat workspace for multiple AI providers, including concurrent answer comparison, local history, prompts, exports, web access, and premium features. Extension packaging is defined by `manifest.config.ts`; Vite application entry HTML files are `app.html` and `sidepanel.html`.

#### Extension entry points and execution contexts
The primary React UI starts at `src/app/main.tsx`, routing through `src/app/router.tsx` into single- and multi-bot chat, settings, and premium pages. A dedicated browser side-panel runtime starts at `src/app/sidepanel.tsx` and renders `src/app/pages/SidePanelPage.tsx`. Background extension logic resides in `src/background/index.ts`; page-context bridging for ChatGPT is in `src/content-script/chatgpt-inpage-proxy.ts`.

#### Chat orchestration and UI
`src/app/pages/SingleBotChatPanel.tsx` and `src/app/pages/MultiBotChatPanel.tsx` are the primary interaction surfaces. `src/app/hooks/use-chat.ts` coordinates user messages, selected bots, streamed responses, and UI state, while `src/app/components/Chat/ConversationPanel.tsx` and `src/app/components/Chat/ChatMessageList.tsx` render conversations. This separates provider execution from presentation and enables a single prompt to fan out to several adapters.

#### Provider adapter boundary
`src/app/bots/abstract-bot.ts` defines the common bot abstraction, and `src/app/bots/index.ts` aggregates supported implementations. Provider-specific adapters encapsulate authentication and protocol differences, e.g. `src/app/bots/chatgpt-api/index.ts`, `src/app/bots/bing/index.ts`, and `src/app/bots/poe/index.ts`. Integrations span direct APIs, provider web apps, GraphQL (Poe), Azure/OpenRouter-compatible endpoints, and open-model/Gradio services.

#### Services, persistence, and streaming
Application services own durable and remote-facing concerns: `src/services/chat-history.ts` handles local conversation persistence, `src/services/user-config.ts` handles user/provider configuration, and `src/services/proxy-fetch.ts` centralizes proxied network requests. Streaming transport utilities in `src/utils/sse.ts` and `src/utils/stream-async-iterable.ts` convert provider output into incrementally rendered responses. User data remains primarily extension-local, with import/export support surfaced by `src/app/utils/export.ts`.

#### Agent and web-search pipeline
Optional web-enabled assistance is organized under `src/services/agent/index.ts`, with prompt construction in `src/services/agent/prompts.ts`. Search providers implement a shared boundary under `src/services/agent/web-search/base.ts`; current backends include DuckDuckGo and Bing News at `src/services/agent/web-search/duckduckgo.ts` and `src/services/agent/web-search/bing-news.ts`. Site-specific rules in `src/rules/bing.json` and peers support browser-based/provider interactions.

#### Monetization, telemetry, and platform dependencies
Premium entitlement and purchase flow are separated from chat via `src/services/premium.ts`, `src/services/lemonsqueezy.ts`, and premium UI under `src/app/pages/PremiumPage.tsx`. External operational services include Lemon Squeezy payments, Sentry error reporting (`src/services/sentry.ts`), and Plausible analytics (`src/app/plausible.ts`). Chrome extension APIs provide runtime messaging, storage, permissions, shortcuts, and side-panel capability.

#### Localization and presentation state
Chrome extension locale bundles are under `_locales/en/messages.json`; in-app localization is initialized in `src/app/i18n/index.ts`. Shared application state is centralized in `src/app/state/index.ts`, while theme persistence and application are split between `src/services/theme.ts` and `src/app/theme.ts`. This supports consistent settings across the main app and side-panel runtimes.

Main entry points: [`src/app/hooks/use-chat.ts`](https://github.com/chathub-dev/chathub/blob/main/src/app/hooks/use-chat.ts) (Chat orchestration), [`manifest.config.ts`](https://github.com/chathub-dev/chathub/blob/main/manifest.config.ts) (Extension packaging), [`src/app/router.tsx`](https://github.com/chathub-dev/chathub/blob/main/src/app/router.tsx) (App routes), [`src/app/bots/index.ts`](https://github.com/chathub-dev/chathub/blob/main/src/app/bots/index.ts) (Bot registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_extension["Extension runtimes"]
  node_manifest["Extension packaging<br/>Manifest<br/>[manifest.config.ts]"]
  node_background{{"Background runtime<br/>Extension worker<br/>[index.ts]"}}
  node_chatgpt_proxy{{"ChatGPT page bridge<br/>Content script"}}
end

subgraph group_ui["React workspace"]
  node_main_app["Main app runtime<br/>React entry<br/>[main.tsx]"]
  node_router["App routes<br/>Router<br/>[router.tsx]"]
  node_sidepanel["Side panel runtime<br/>React entry<br/>[sidepanel.tsx]"]
  node_sidepanel_page["Side panel page<br/>UI page<br/>[SidePanelPage.tsx]"]
  node_chat_pages["Single and multi-bot chat<br/>UI pages"]
  node_chat_hook{{"Chat orchestration<br/>React hook<br/>[use-chat.ts]"}}
  node_conversation_ui["Conversation renderer<br/>Chat components"]
  node_app_state["Shared app state<br/>State store<br/>[index.ts]"]
end

subgraph group_providers["Provider execution"]
  node_bot_contract{{"Bot abstraction<br/>Adapter contract<br/>[abstract-bot.ts]"}}
  node_bot_registry["Bot registry<br/>Adapter registry<br/>[index.ts]"]
  node_provider_adapters["Provider adapters<br/>Provider clients<br/>[index.ts]"]
end

subgraph group_services["Services and agent"]
  node_streaming["Streaming transport<br/>SSE utilities<br/>[sse.ts]"]
  node_history[("Chat history<br/>Local persistence<br/>[chat-history.ts]")]
  node_user_config[("User configuration<br/>Local persistence<br/>[user-config.ts]")]
  node_agent{{"Web-enabled agent<br/>Agent pipeline<br/>[index.ts]"}}
  node_web_search["Web search backends<br/>Search adapters<br/>[base.ts]"]
  node_premium["Premium service<br/>Entitlements<br/>[premium.ts]"]
end

subgraph group_platform["External platform"]
  node_chrome{{"Chrome extension APIs<br/>Browser platform"}}
  node_provider_network(("AI providers"))
  node_search_network(("Search services<br/>External search"))
  node_payments(("Lemon Squeezy<br/>Payment platform"))
end

node_manifest -->|"packages"| node_background
node_manifest -->|"packages"| node_main_app
node_manifest -->|"packages"| node_sidepanel
node_background -->|"uses"| node_chrome
node_chatgpt_proxy -->|"bridges through"| node_chrome
node_main_app -->|"routes through"| node_router
node_router -->|"renders"| node_chat_pages
node_sidepanel -->|"renders"| node_sidepanel_page
node_chat_pages -->|"drives"| node_chat_hook
node_chat_hook -->|"updates"| node_conversation_ui
node_chat_hook -->|"uses"| node_app_state
node_chat_hook -->|"selects bots"| node_bot_registry
node_bot_registry -->|"implements"| node_bot_contract
node_bot_registry -->|"loads"| node_provider_adapters
node_provider_adapters -->|"streams via"| node_streaming
node_provider_adapters -->|"calls"| node_provider_network
node_chat_hook -->|"persists conversations"| node_history
node_app_state -->|"reads settings"| node_user_config
node_chat_hook -.->|"optionally invokes"| node_agent
node_agent -->|"queries through"| node_web_search
node_web_search -->|"searches"| node_search_network
node_router -.->|"opens premium flow"| node_premium
node_premium -->|"manages purchase"| node_payments
node_history -->|"stores in"| node_chrome
node_user_config -->|"stores in"| node_chrome

click node_manifest "https://github.com/chathub-dev/chathub/blob/main/manifest.config.ts"
click node_background "https://github.com/chathub-dev/chathub/blob/main/src/background/index.ts"
click node_chatgpt_proxy "https://github.com/chathub-dev/chathub/blob/main/src/content-script/chatgpt-inpage-proxy.ts"
click node_main_app "https://github.com/chathub-dev/chathub/blob/main/src/app/main.tsx"
click node_router "https://github.com/chathub-dev/chathub/blob/main/src/app/router.tsx"
click node_sidepanel "https://github.com/chathub-dev/chathub/blob/main/src/app/sidepanel.tsx"
click node_sidepanel_page "https://github.com/chathub-dev/chathub/blob/main/src/app/pages/SidePanelPage.tsx"
click node_chat_pages "https://github.com/chathub-dev/chathub/blob/main/src/app/pages/MultiBotChatPanel.tsx"
click node_chat_hook "https://github.com/chathub-dev/chathub/blob/main/src/app/hooks/use-chat.ts"
click node_conversation_ui "https://github.com/chathub-dev/chathub/blob/main/src/app/components/Chat/ConversationPanel.tsx"
click node_app_state "https://github.com/chathub-dev/chathub/blob/main/src/app/state/index.ts"
click node_bot_contract "https://github.com/chathub-dev/chathub/blob/main/src/app/bots/abstract-bot.ts"
click node_bot_registry "https://github.com/chathub-dev/chathub/blob/main/src/app/bots/index.ts"
click node_provider_adapters "https://github.com/chathub-dev/chathub/blob/main/src/app/bots/chatgpt-api/index.ts"
click node_streaming "https://github.com/chathub-dev/chathub/blob/main/src/utils/sse.ts"
click node_history "https://github.com/chathub-dev/chathub/blob/main/src/services/chat-history.ts"
click node_user_config "https://github.com/chathub-dev/chathub/blob/main/src/services/user-config.ts"
click node_agent "https://github.com/chathub-dev/chathub/blob/main/src/services/agent/index.ts"
click node_web_search "https://github.com/chathub-dev/chathub/blob/main/src/services/agent/web-search/base.ts"
click node_premium "https://github.com/chathub-dev/chathub/blob/main/src/services/premium.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_manifest,node_background,node_chatgpt_proxy toneBlue
class node_main_app,node_router,node_sidepanel,node_sidepanel_page,node_chat_pages,node_chat_hook,node_conversation_ui,node_app_state toneAmber
class node_bot_contract,node_bot_registry,node_provider_adapters toneMint
class node_streaming,node_history,node_user_config,node_agent,node_web_search,node_premium toneRose
class node_chrome,node_provider_network,node_search_network,node_payments toneIndigo
```

## Components

### Extension runtimes

- [Extension packaging](https://github.com/chathub-dev/chathub/blob/main/manifest.config.ts): Manifest · Declares extension entry points and capabilities. · `manifest.config.ts`
- [Background runtime](https://github.com/chathub-dev/chathub/blob/main/src/background/index.ts): Extension worker · `src/background/index.ts`
- [ChatGPT page bridge](https://github.com/chathub-dev/chathub/blob/main/src/content-script/chatgpt-inpage-proxy.ts): Content script · `src/content-script/chatgpt-inpage-proxy.ts`

### React workspace

- [Main app runtime](https://github.com/chathub-dev/chathub/blob/main/src/app/main.tsx): React entry · `src/app/main.tsx`
- [App routes](https://github.com/chathub-dev/chathub/blob/main/src/app/router.tsx): Router · `src/app/router.tsx`
- [Side panel runtime](https://github.com/chathub-dev/chathub/blob/main/src/app/sidepanel.tsx): React entry · `src/app/sidepanel.tsx`
- [Side panel page](https://github.com/chathub-dev/chathub/blob/main/src/app/pages/SidePanelPage.tsx): UI page · `src/app/pages/SidePanelPage.tsx`
- [Single and multi-bot chat](https://github.com/chathub-dev/chathub/blob/main/src/app/pages/MultiBotChatPanel.tsx): UI pages · Primary prompt and concurrent-comparison surfaces. · `src/app/pages/MultiBotChatPanel.tsx`
- [Chat orchestration](https://github.com/chathub-dev/chathub/blob/main/src/app/hooks/use-chat.ts): React hook · Coordinates selected bots, messages, streaming, and UI state. · `src/app/hooks/use-chat.ts`
- [Conversation renderer](https://github.com/chathub-dev/chathub/blob/main/src/app/components/Chat/ConversationPanel.tsx): Chat components · `src/app/components/Chat/ConversationPanel.tsx`
- [Shared app state](https://github.com/chathub-dev/chathub/blob/main/src/app/state/index.ts): State store · `src/app/state/index.ts`

### Provider execution

- [Bot abstraction](https://github.com/chathub-dev/chathub/blob/main/src/app/bots/abstract-bot.ts): Adapter contract · `src/app/bots/abstract-bot.ts`
- [Bot registry](https://github.com/chathub-dev/chathub/blob/main/src/app/bots/index.ts): Adapter registry · `src/app/bots/index.ts`
- [Provider adapters](https://github.com/chathub-dev/chathub/blob/main/src/app/bots/chatgpt-api/index.ts): Provider clients · ChatGPT, Bing, Poe, and other provider protocol integrations. · `src/app/bots/chatgpt-api/index.ts`

### Services and agent

- [Streaming transport](https://github.com/chathub-dev/chathub/blob/main/src/utils/sse.ts): SSE utilities · Turns provider streams into incrementally consumable responses. · `src/utils/sse.ts`
- [Chat history](https://github.com/chathub-dev/chathub/blob/main/src/services/chat-history.ts): Local persistence · `src/services/chat-history.ts`
- [User configuration](https://github.com/chathub-dev/chathub/blob/main/src/services/user-config.ts): Local persistence · Stores user and provider settings. · `src/services/user-config.ts`
- [Web-enabled agent](https://github.com/chathub-dev/chathub/blob/main/src/services/agent/index.ts): Agent pipeline · Builds assisted prompts and invokes web search. · `src/services/agent/index.ts`
- [Web search backends](https://github.com/chathub-dev/chathub/blob/main/src/services/agent/web-search/base.ts): Search adapters · Shared search boundary with DuckDuckGo and Bing News implementations. · `src/services/agent/web-search/base.ts`
- [Premium service](https://github.com/chathub-dev/chathub/blob/main/src/services/premium.ts): Entitlements · `src/services/premium.ts`

### External platform

- **Chrome extension APIs**: Browser platform · Messaging, storage, permissions, shortcuts, and side-panel APIs.
- **AI providers**: External APIs and web apps
- **Search services**: External search
- **Lemon Squeezy**: Payment platform

## Connections

- Extension packaging → Background runtime: packages
- Extension packaging → Main app runtime: packages
- Extension packaging → Side panel runtime: packages
- Background runtime → Chrome extension APIs: uses
- ChatGPT page bridge → Chrome extension APIs: bridges through
- Main app runtime → App routes: routes through
- App routes → Single and multi-bot chat: renders
- Side panel runtime → Side panel page: renders
- Single and multi-bot chat → Chat orchestration: drives
- Chat orchestration → Conversation renderer: updates
- Chat orchestration → Shared app state: uses
- Chat orchestration → Bot registry: selects bots
- Bot registry → Bot abstraction: implements
- Bot registry → Provider adapters: loads
- Provider adapters → Streaming transport: streams via
- Provider adapters → AI providers: calls
- Chat orchestration → Chat history: persists conversations
- Shared app state → User configuration: reads settings
- Chat orchestration → Web-enabled agent: optionally invokes
- Web-enabled agent → Web search backends: queries through
- Web search backends → Search services: searches
- App routes → Premium service: opens premium flow
- Premium service → Lemon Squeezy: manages purchase
- Chat history → Chrome extension APIs: stores in
- User configuration → Chrome extension APIs: stores in
