# shuakami/qq-chat-exporter architecture

> Architecture diagram of the GitHub repository shuakami/qq-chat-exporter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shuakami/qq-chat-exporter
- Repository: https://github.com/shuakami/qq-chat-exporter

## Overview

1. **Repository shape**
   - This repo is a multi-part QQ chat export system, not a single application.
   - The main production runtime is the **NapCat plugin** under `plugins/qq-chat-exporter`.
   - The user-facing management UI is `qce-v4-tool`.
   - There is also a lightweight legacy/static viewer in `qce-viewer`, plus build/release scripts and docs.

2. **Primary runtime boundary: NapCat plugin**
   - `plugins/qq-chat-exporter` is the core backend plugin that runs inside the NapCatQQ environment.
   - It is responsible for accessing QQ data, orchestrating exports, tracking progress, and serving API endpoints to the UI.
   - The compiled output in `dist/` mirrors this structure and indicates the plugin is the deployable unit.

3. **Data acquisition layer**
   - The core data path begins with chat and metadata retrieval:
     - `core/fetcher/BatchMessageFetcher`
     - `core/chat/ChatSessionManager`
     - `core/chat/FriendInfoManager`
     - `core/chat/GroupInfoManager`
   - These modules gather message history and entity metadata before export.
   - The plugin also includes search and resource indexing services, suggesting read-only traversal over stored QQ content rather than live message interception only.

4. **Export pipeline**
   - The export subsystem converts fetched chat data into multiple output formats:
     - HTML
     - JSON
     - TXT
     - Excel
   - Key exporters live under `core/exporter/`, including `HtmlExporter`, `ModernHtmlExporter`, `JsonExporter`, `TextExporter`, and `ExcelExporter`.
   - Parsing is separated from rendering via `core/parser/MessageParser` and `SimpleMessageParser`, which helps keep message normalization distinct from output formatting.

5. **Media and attachment handling**
   - Export is not just text: the plugin has explicit support for resources and media packaging.
   - Relevant components include:
     - `core/resource/ResourceHandler`
     - `core/merger/ResourceMerger`
     - `utils/ZipExporter` and `utils/StreamingZipExporter`
     - `core/sticker/StickerPackExporter`
     - `core/group/GroupFilesExporter` and `GroupAlbumExporter`
   - This indicates a pipeline that collects chat attachments, stickers, group assets, and bundles them alongside exported transcripts.

6. **Operational services inside the plugin**
   - The plugin includes non-export orchestration services:
     - `core/scheduler/ScheduledExportManager` for recurring backup/export jobs
     - `core/progress/ProgressTracker` for long-running task state
     - `services/StreamSearchService` for searching streamed or indexed data
     - `security/SecurityManager` for access control around the local API surface
   - `storage/ConfigManager` and `DatabaseManager` show the plugin keeps local configuration/state, not just stateless processing.

7. **API and control plane**
   - The plugin exposes an API layer under `lib/api` / `dist/api`.
   - `ApiServer`, `ApiLauncher`, and `StandaloneServer` form the interface between the UI and the export engine.
   - This is the main integration boundary: the dashboard triggers exports, queries status/history, reads config, and receives progress/results through this API rather than directly touching export internals.

8. **Modern management UI**
   - `qce-v4-tool` is the current frontend dashboard, built with Next.js-style structure (`app/`, `components/`, `hooks/`).
   - Its hooks (`use-api`, `use-export-tasks`, `use-scheduled-exports`, `use-search`, `use-system-info`, etc.) show the UI is stateful and API-driven.
   - The UI organizes workflows such as session browsing, export task setup, batch export, scheduled exports, settings, sticker export, file/essence dialogs, and execution history.

9. **UI-to-backend data flow**
   - The typical flow is:
     - user opens the dashboard in the browser
     - dashboard authenticates via token/local auth
     - UI calls the plugin API over HTTP and likely websocket-style updates for live state
     - plugin fetches QQ data, performs export, streams progress, and writes artifacts locally
   - The UI does not appear to own the export logic; it is a control and visualization layer over the plugin runtime.

10. **Legacy viewer / static export browsing**
   - `qce-viewer` is a separate, simpler web app/server used to browse exported content.
   - Its `public/` HTML/JS/CSS assets and `server.js` suggest it serves previously generated export bundles rather than controlling the export engine.
   - This is an important architectural boundary: it consumes export outputs, while `qq-chat-exporter` produces them.

11. **Build, packaging, and deployment**
   - The repo includes release automation in `.github/workflows` for building the plugin, docs, and release artifacts.
   - `scripts/` contains packaging and conversion utilities such as ZIP packaging, Excel conversion, framework plugin building, version sync, and standalone startup helpers.
   - The presence of `public/dist/` and plugin `dist/` indicates prebuilt browser bundles and plugin artifacts are shipped with releases.

12. **Documentation and deployment modes**
   - Documentation in `docs/` covers usage, contributing, Docker NapCat deployment, and guides.
   - The README highlights two deployment styles:
     - desktop/launcher-based usage
     - Docker NapCat shell-mode plugin deployment
   - That means the same export core can run in at least two operational contexts, but the internal architecture stays centered on the NapCat plugin plus the dashboard UI.

13. **Overall architectural picture**
   - The system is best understood as a **local-first export platform**:
     - NapCat plugin = data access, processing, storage, API
     - qce-v4-tool = administrative UI and workflow orchestration
     - qce-viewer = read-only browsing of generated artifacts
   - The key domain objects are chat sessions, messages, resources, and export tasks, with local filesystem/database state used to persist configuration, history, and generated files.

Main entry points: [`plugins/qq-chat-exporter/lib/api/ApiServer.ts`](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/ApiServer.ts) (API server), [`.github/workflows/release-plugin.yml`](https://github.com/shuakami/qq-chat-exporter/blob/master/.github/workflows/release-plugin.yml) (Build & release), [`plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts`](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts) (Exporters), [`plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts`](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts) (Batch fetcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugin["NapCat plugin"]
  node_api_server["API server<br/>plugin api<br/>[ApiServer.ts]"]
  node_api_launcher["API launcher<br/>plugin bootstrap<br/>[ApiLauncher.ts]"]
  node_standalone_server["Standalone server<br/>plugin entry"]
  node_fetcher["Batch fetcher<br/>chat retrieval"]
  node_chat_managers["Chat managers<br/>session metadata"]
  node_parser["Message parser<br/>normalization<br/>[MessageParser.ts]"]
  node_exporters["Exporters<br/>output formats<br/>[HtmlExporter.ts]"]
  node_resource_pipeline["Resources<br/>media handling<br/>[ResourceHandler.ts]"]
  node_group_exports["Group assets<br/>group media"]
  node_sticker_exporter["Sticker export<br/>asset pack"]
  node_scheduler["Scheduled exports<br/>automation"]
  node_progress["Progress tracker<br/>task state<br/>[ProgressTracker.ts]"]
  node_storage["Config & DB<br/>local state<br/>[ConfigManager.ts]"]
  node_security["Security<br/>api guard<br/>[SecurityManager.ts]"]
  node_search_service["Stream search<br/>search service"]
end

subgraph group_ui["Management UI"]
  node_dashboard["QCE dashboard<br/>next ui<br/>[page.tsx]"]
  node_ui_hooks["API hooks<br/>ui data layer<br/>[use-api.ts]"]
  node_ui_modules["Workflow UI<br/>ui workflows<br/>[task-wizard.tsx]"]
end

subgraph group_viewer["Legacy viewer"]
  node_viewer_app["QCE viewer<br/>static viewer<br/>[server.js]"]
  node_viewer_assets["Viewer assets<br/>static frontend<br/>[index.html]"]
end

subgraph group_tooling["Build & release"]
  node_build_release["Build & release<br/>automation<br/>[release-plugin.yml]"]
  node_docs["Docs<br/>documentation<br/>[guide.md]"]
end

node_api_launcher -->|"starts"| node_api_server
node_standalone_server -->|"hosts"| node_api_server
node_api_server -->|"requests data"| node_fetcher
node_fetcher -->|"reads metadata"| node_chat_managers
node_fetcher -->|"normalizes"| node_parser
node_parser -->|"feeds"| node_exporters
node_exporters -->|"bundles media"| node_resource_pipeline
node_resource_pipeline -->|"packages"| node_group_exports
node_resource_pipeline -->|"packages"| node_sticker_exporter
node_exporters -->|"writes state"| node_storage
node_scheduler -->|"triggers"| node_exporters
node_scheduler -->|"updates"| node_progress
node_progress -->|"streams status"| node_api_server
node_security -->|"protects"| node_api_server
node_search_service -->|"indexes"| node_storage
node_dashboard -->|"calls"| node_ui_hooks
node_ui_hooks -->|"requests"| node_api_server
node_ui_modules -->|"renders"| node_dashboard
node_viewer_app -->|"serves"| node_viewer_assets
node_build_release -.->|"packages"| node_api_server
node_build_release -.->|"builds"| node_dashboard
node_build_release -.->|"packages"| node_viewer_app
node_docs -.->|"documents"| node_build_release

click node_api_server "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/ApiServer.ts"
click node_api_launcher "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/ApiLauncher.ts"
click node_standalone_server "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/StandaloneServer.ts"
click node_fetcher "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts"
click node_chat_managers "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/chat/ChatSessionManager.ts"
click node_parser "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/parser/MessageParser.ts"
click node_exporters "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts"
click node_resource_pipeline "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/resource/ResourceHandler.ts"
click node_group_exports "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/group/GroupFilesExporter.ts"
click node_sticker_exporter "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/sticker/StickerPackExporter.ts"
click node_scheduler "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/scheduler/ScheduledExportManager.ts"
click node_progress "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/progress/ProgressTracker.ts"
click node_storage "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/storage/ConfigManager.ts"
click node_security "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/security/SecurityManager.ts"
click node_search_service "https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/services/StreamSearchService.ts"
click node_dashboard "https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/app/page.tsx"
click node_ui_hooks "https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/hooks/use-api.ts"
click node_ui_modules "https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/components/ui/task-wizard.tsx"
click node_viewer_app "https://github.com/shuakami/qq-chat-exporter/blob/master/qce-viewer/server.js"
click node_viewer_assets "https://github.com/shuakami/qq-chat-exporter/blob/master/qce-viewer/public/index.html"
click node_build_release "https://github.com/shuakami/qq-chat-exporter/blob/master/.github/workflows/release-plugin.yml"
click node_docs "https://github.com/shuakami/qq-chat-exporter/blob/master/docs/guide.md"

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_api_server,node_api_launcher,node_standalone_server,node_fetcher,node_chat_managers,node_parser,node_exporters,node_resource_pipeline,node_group_exports,node_sticker_exporter,node_scheduler,node_progress,node_storage,node_security,node_search_service toneBlue
class node_dashboard,node_ui_hooks,node_ui_modules toneAmber
class node_viewer_app,node_viewer_assets toneMint
class node_build_release,node_docs toneRose
```

## Components

### NapCat plugin

Core runtime inside NapCatQQ that fetches QQ data, runs exports, and serves the local API.

- [API server](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/ApiServer.ts): plugin api · HTTP control plane for the dashboard and standalone access. · `plugins/qq-chat-exporter/lib/api/ApiServer.ts`
- [API launcher](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/ApiLauncher.ts): plugin bootstrap · Starts the API runtime in plugin or standalone mode. · `plugins/qq-chat-exporter/lib/api/ApiLauncher.ts`
- [Standalone server](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/api/StandaloneServer.ts): plugin entry · Alternative startup path for running the exporter outside NapCat. · `plugins/qq-chat-exporter/lib/api/StandaloneServer.ts`
- [Batch fetcher](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts): chat retrieval · Pulls message history and drives bulk data acquisition. · `plugins/qq-chat-exporter/lib/core/fetcher/BatchMessageFetcher.ts`
- [Chat managers](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/chat/ChatSessionManager.ts): session metadata · Session, friend, and group metadata coordinators. · `plugins/qq-chat-exporter/lib/core/chat/ChatSessionManager.ts`
- [Message parser](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/parser/MessageParser.ts): normalization · Normalizes raw chat content before export formatting. · `plugins/qq-chat-exporter/lib/core/parser/MessageParser.ts`
- [Exporters](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts): output formats · HTML, modern HTML, JSON, text, and Excel export writers. · `plugins/qq-chat-exporter/lib/core/exporter/HtmlExporter.ts`
- [Resources](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/resource/ResourceHandler.ts): media handling · Collects, merges, and bundles attachments and media assets. · `plugins/qq-chat-exporter/lib/core/resource/ResourceHandler.ts`
- [Group assets](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/group/GroupFilesExporter.ts): group media · Exports group files and albums as part of chat packages. · `plugins/qq-chat-exporter/lib/core/group/GroupFilesExporter.ts`
- [Sticker export](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/sticker/StickerPackExporter.ts): asset pack · Builds sticker-pack outputs for chat archives. · `plugins/qq-chat-exporter/lib/core/sticker/StickerPackExporter.ts`
- [Scheduled exports](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/scheduler/ScheduledExportManager.ts): automation · Recurring export and backup job manager. · `plugins/qq-chat-exporter/lib/core/scheduler/ScheduledExportManager.ts`
- [Progress tracker](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/progress/ProgressTracker.ts): task state · Tracks long-running export status for UI updates. · `plugins/qq-chat-exporter/lib/core/progress/ProgressTracker.ts`
- [Config & DB](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/core/storage/ConfigManager.ts): local state · Persistent config and database layer for runtime state and history. · `plugins/qq-chat-exporter/lib/core/storage/ConfigManager.ts`
- [Security](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/security/SecurityManager.ts): api guard · Access control for the local API surface. · `plugins/qq-chat-exporter/lib/security/SecurityManager.ts`
- [Stream search](https://github.com/shuakami/qq-chat-exporter/blob/master/plugins/qq-chat-exporter/lib/services/StreamSearchService.ts): search service · Searches streamed or indexed QQ content. · `plugins/qq-chat-exporter/lib/services/StreamSearchService.ts`

### Management UI

Browser dashboard for configuring sessions, exports, schedules, search, and settings.

- [QCE dashboard](https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/app/page.tsx): next ui · Primary web interface for managing exports and settings. · `qce-v4-tool/app/page.tsx`
- [API hooks](https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/hooks/use-api.ts): ui data layer · Client hooks for exports, schedule, search, config, and websocket state. · `qce-v4-tool/hooks/use-api.ts`
- [Workflow UI](https://github.com/shuakami/qq-chat-exporter/blob/master/qce-v4-tool/components/ui/task-wizard.tsx): ui workflows · Session browsing, task wizard, scheduled exports, history, and dialogs. · `qce-v4-tool/components/ui/task-wizard.tsx`

### Legacy viewer

Static/read-only app for browsing previously generated export bundles.

- [QCE viewer](https://github.com/shuakami/qq-chat-exporter/blob/master/qce-viewer/server.js): static viewer · Legacy server that browses exported bundles and resources. · `qce-viewer/server.js`
- [Viewer assets](https://github.com/shuakami/qq-chat-exporter/blob/master/qce-viewer/public/index.html): static frontend · HTML, JS, and CSS for read-only archive browsing. · `qce-viewer/public/index.html`

### Build & release

Packaging, release, and documentation automation for plugin and UI artifacts.

- [Build & release](https://github.com/shuakami/qq-chat-exporter/blob/master/.github/workflows/release-plugin.yml): automation · GitHub workflows and scripts for packaging, conversion, and publishing. · `.github/workflows/release-plugin.yml`
- [Docs](https://github.com/shuakami/qq-chat-exporter/blob/master/docs/guide.md): documentation · Usage, deployment, and contribution guides. · `docs/guide.md`

## Connections

- API launcher → API server: starts · Bootstraps the API runtime.
- Standalone server → API server: hosts · Alternative standalone entrypoint for the same control plane.
- API server → Batch fetcher: requests data · Initiates bulk chat history retrieval.
- Batch fetcher → Chat managers: reads metadata · Uses session and entity managers to resolve conversations.
- Batch fetcher → Message parser: normalizes · Converts raw messages into export-ready records.
- Message parser → Exporters: feeds · Supplies normalized message content to format-specific writers.
- Exporters → Resources: bundles media · Includes attachments and generated assets with transcripts.
- Resources → Group assets: packages · Collects group files and album content.
- Resources → Sticker export: packages · Adds sticker packs to export output.
- Exporters → Config & DB: writes state · Persists export history, config, and runtime metadata.
- Scheduled exports → Exporters: triggers · Starts recurring export jobs.
- Scheduled exports → Progress tracker: updates · Publishes task progress for live monitoring.
- Progress tracker → API server: streams status · Exposes long-running job state to clients.
- Security → API server: protects · Constrains local API access.
- Stream search → Config & DB: indexes · Uses local persistence for searchable content.
- QCE dashboard → API hooks: calls · UI components consume API and websocket hooks.
- API hooks → API server: requests · Primary browser-to-plugin control flow over HTTP and live updates.
- Workflow UI → QCE dashboard: renders · Composes the management workflows inside the app shell.
- QCE viewer → Viewer assets: serves · Hosts the legacy static archive browser.
- Build & release → API server: packages · Builds plugin artifacts for release.
- Build & release → QCE dashboard: builds · Produces the management UI bundles.
- Build & release → QCE viewer: packages · Creates viewer and release artifacts.
- Docs → Build & release: documents · Explains deployment and packaging flows.
