# qiannqq/napcat-adapter architecture

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

- Interactive diagram: https://gitdiagram.com/qiannqq/napcat-adapter
- Repository: https://github.com/qiannqq/napcat-adapter

## Overview

NapCat-Adapter bridges Miao-Yunzai plugins to a NapCat OneBot connection. Startup loads configuration and initializes adapter instances; the adapter exchanges events and message/API operations with NapCat while exposing Yunzai-compatible bot behavior. Message normalization, media handling, and the Guoba settings interface are distinct capabilities. The adapter source is only excerpted, so some detailed routing and conversion links are supported by README claims rather than inspected call sites.

Main entry points: [`index.js`](https://github.com/qiannqq/napcat-adapter/blob/master/index.js) (Plugin entry), [`adapter/index.js`](https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js) (Adapter lifecycle), [`lib/utils/common.js`](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js) (Message conversion), [`lib/utils/cfg.js`](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/cfg.js) (Config loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_startup["Startup and config"]
  node_entry["Plugin entry<br/>[index.js]"]
  node_settings["Config loader<br/>[cfg.js]"]
  node_configfiles["Config files"]
end

subgraph group_bridge["Protocol bridge"]
  node_adapter["Adapter lifecycle<br/>[index.js]"]
  node_client["NapCat client<br/>[index.js]"]
  node_eventbridge["Event translation<br/>[index.js]"]
  node_messagecodec["Message conversion<br/>[common.js]"]
  node_mediafiles["Media handling<br/>[common.js]"]
  node_faces["Face dictionaries<br/>[face.js]"]
  node_protobuf["Protobuf support<br/>[protobuf.js]"]
  node_botapi["Bot operations<br/>[index.js]"]
end

subgraph group_compat["Yunzai compatibility"]
  node_botproxy["Bot compatibility<br/>[bot.js]"]
  node_uin["UIN adaptation<br/>[uin.js]"]
  node_common["Bridge utilities<br/>[common.js]"]
end

subgraph group_admin["Configuration UI"]
  node_guoba["Guoba settings<br/>[guoba.support.js]"]
  node_update["Update command<br/>[u.js]"]
end

node_yunzai(("Yunzai host"))
node_napcat{{"NapCat OneBot"}}

node_yunzai -->|"loads plugin"| node_entry
node_entry -->|"loads config"| node_settings
node_settings -->|"reads defaults"| node_configfiles
node_entry -->|"creates and initializes"| node_adapter
node_adapter -->|"constructs"| node_client
node_client -.->|"connects"| node_napcat
node_adapter -->|"translates events"| node_eventbridge
node_napcat -.->|"sends events"| node_eventbridge
node_eventbridge -.->|"dispatches events"| node_yunzai
node_adapter -->|"uses utilities"| node_common
node_common -->|"converts messages"| node_messagecodec
node_messagecodec -->|"resolves media"| node_mediafiles
node_messagecodec -->|"uses dictionaries"| node_faces
node_adapter -->|"exposes operations"| node_botapi
node_botapi -.->|"invokes OneBot APIs"| node_napcat
node_entry -->|"loads compatibility layer"| node_botproxy
node_botproxy -->|"delegates bot calls"| node_botapi
node_entry -.->|"adapts account identity"| node_uin
node_yunzai -->|"configures adapter"| node_guoba
node_guoba -->|"reads and writes"| node_configfiles
node_yunzai -.->|"invokes update command"| node_update

click node_entry "https://github.com/qiannqq/napcat-adapter/blob/master/index.js"
click node_settings "https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/cfg.js"
click node_configfiles "https://github.com/qiannqq/napcat-adapter/tree/master/config"
click node_adapter "https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js"
click node_client "https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js"
click node_eventbridge "https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js"
click node_messagecodec "https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js"
click node_mediafiles "https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js"
click node_faces "https://github.com/qiannqq/napcat-adapter/blob/master/lib/face.js"
click node_protobuf "https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/protobuf.js"
click node_botapi "https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js"
click node_botproxy "https://github.com/qiannqq/napcat-adapter/blob/master/lib/bot.js"
click node_uin "https://github.com/qiannqq/napcat-adapter/blob/master/lib/uin.js"
click node_common "https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js"
click node_guoba "https://github.com/qiannqq/napcat-adapter/blob/master/guoba.support.js"
click node_update "https://github.com/qiannqq/napcat-adapter/blob/master/other/u.js"

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_entry,node_settings,node_configfiles toneBlue
class node_adapter,node_client,node_eventbridge,node_messagecodec,node_mediafiles,node_faces,node_protobuf,node_botapi toneAmber
class node_botproxy,node_uin,node_common toneMint
class node_guoba,node_update toneRose
class node_yunzai,node_napcat toneIndigo
```

## Components

### Startup and config

- [Plugin entry](https://github.com/qiannqq/napcat-adapter/blob/master/index.js): `index.js`
- [Config loader](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/cfg.js): `lib/utils/cfg.js`
- [Config files](https://github.com/qiannqq/napcat-adapter/tree/master/config): `config`

### Protocol bridge

- [Adapter lifecycle](https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js): `adapter/index.js`
- [NapCat client](https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js): `adapter/index.js`
- [Event translation](https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js): `adapter/index.js`
- [Message conversion](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js): `lib/utils/common.js`
- [Media handling](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js): `lib/utils/common.js`
- [Face dictionaries](https://github.com/qiannqq/napcat-adapter/blob/master/lib/face.js): `lib/face.js`
- [Protobuf support](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/protobuf.js): `lib/utils/protobuf.js`
- [Bot operations](https://github.com/qiannqq/napcat-adapter/blob/master/adapter/index.js): `adapter/index.js`

### Yunzai compatibility

- [Bot compatibility](https://github.com/qiannqq/napcat-adapter/blob/master/lib/bot.js): `lib/bot.js`
- [UIN adaptation](https://github.com/qiannqq/napcat-adapter/blob/master/lib/uin.js): `lib/uin.js`
- [Bridge utilities](https://github.com/qiannqq/napcat-adapter/blob/master/lib/utils/common.js): `lib/utils/common.js`

### Configuration UI

- [Guoba settings](https://github.com/qiannqq/napcat-adapter/blob/master/guoba.support.js): `guoba.support.js`
- [Update command](https://github.com/qiannqq/napcat-adapter/blob/master/other/u.js): `other/u.js`

### Other components

- **Yunzai host**
- **NapCat OneBot**

## Connections

- Yunzai host → Plugin entry: loads plugin (evidence: `README.md`)
- Plugin entry → Config loader: loads config (evidence: `index.js`)
- Config loader → Config files: reads defaults (evidence: `lib/utils/cfg.js`)
- Plugin entry → Adapter lifecycle: creates and initializes (evidence: `index.js`)
- Adapter lifecycle → NapCat client: constructs (evidence: `adapter/index.js`)
- NapCat client → NapCat OneBot: connects (evidence: `README.md`)
- Adapter lifecycle → Event translation: translates events (evidence: `adapter/index.js`)
- NapCat OneBot → Event translation: sends events (evidence: `README.md`)
- Event translation → Yunzai host: dispatches events (evidence: `README.md`)
- Adapter lifecycle → Bridge utilities: uses utilities (evidence: `adapter/index.js`)
- Bridge utilities → Message conversion: converts messages (evidence: `lib/utils/common.js`)
- Message conversion → Media handling: resolves media (evidence: `lib/utils/common.js`)
- Message conversion → Face dictionaries: uses dictionaries (evidence: `lib/index.js`)
- Adapter lifecycle → Bot operations: exposes operations (evidence: `README.md`)
- Bot operations → NapCat OneBot: invokes OneBot APIs (evidence: `README.md`)
- Plugin entry → Bot compatibility: loads compatibility layer
- Bot compatibility → Bot operations: delegates bot calls (evidence: `lib/bot.js`)
- Plugin entry → UIN adaptation: adapts account identity
- Yunzai host → Guoba settings: configures adapter (evidence: `guoba.support.js`)
- Guoba settings → Config files: reads and writes (evidence: `guoba.support.js`)
- Yunzai host → Update command: invokes update command
