# napneko/napcatqq architecture

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

- Interactive diagram: https://gitdiagram.com/napneko/napcatqq
- Repository: https://github.com/napneko/napcatqq

## Overview

##### & Define Major Components

- Launcher & Bootstrapping
- The “launcher” directory holds executables, BAT files, and scripts for initializing and launching the bot. This is where the execution starts.

- Backend Core (Bot Logic)
- The “core” folder implements adapters, packet handling, event listeners, and API calls for managing incoming/outgoing messages, protocol events, and conversions.
- The “onebot” submodule specifically deals with the OneBot actions, events, and protocol integrations. This is where the bot’s behavior (listening to messages, responding to events, executing commands) is defined.

- Web UI / Frontend
- The “napcat.webui” directory provides the web-based user interface. It is built using modern frontend technologies (note the presence of React components, a Vite config, ESLint, Tailwind, etc.) that create dashboards, settings pages, and interactive views for bot management.
- Additionally, there is a “src/webui” folder under “src” that appears to provide API routers, middleware, and client-side helper functions, thus connecting the Web UI with backend processing.

- Native Modules & Plugin System
- The “native” directories (including “src/native” and “src/pty”) contain platform-specific binaries and connections that support system-level integration (for instance, pty components for terminal emulation and native packet handlers).
- The existence of “src/plugin” indicates support for extensibility through plugins.

- External Dependencies & Supporting Scripts
- The “external” folder (with .zip of LiteLoaderWrapper) and “script” directory (with utility scripts) allow further integration or automation.

##### Relationships & Data Flow

- The Launcher initiates the entire system and may directly call preparatory scripts (like loadNapCat.js) that in turn boot up backend services.
- The Bot Core acts as the engine where:
- The adapters and packet submodules interface with remote QQ networks by handling protocol messages.
- Listeners and event mechanisms (found under “core/listeners” and “onebot/event”) capture and dispatch events to appropriate service modules.
- A rich API layer (located in “core/apis” and “onebot/api”) facilitates external interactions.
- The Web UI component communicates with the backend—likely through API endpoints defined in “src/webui/src/router” and middleware—to both display real-time status information and allow configuration.
- The native modules provide system-level functionality (such as managing terminal sessions or handling operations that require native performance).

##### Architectural Patterns & Principles to Highlight

- Modular Design & Separation of Concerns:
- Each major functionality is separated into its own directory (Launcher, Core, Web UI, OneBot, Plugins). This modular structure supports maintainability and extensibility.
- Layered Architecture:
- Presentation Layer: Web UI (napcat.webui)
- Application Layer: Bot Core & OneBot Actions (src/core, src/onebot)
- Infrastructure Layer: Native modules, adapters, and system-level components (src/native, src/pty, and external scripts)
- Adapter and Plugin Patterns:
- The adapters in “src/core/adapters” abstract platform-specific details.
- The plugin system (under “src/plugin”) allows extending the system’s capabilities without modifying core logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Launcher/Bootstrapping"
        launcher["Launcher & Bootstrapping"]:::launcher
    end

    subgraph "Backend Core"
        botCore["Bot Core"]:::backend
        adapters["Adapters & Packet Handling"]:::backend
        listeners["Event Listeners"]:::backend
        apis["APIs & Services"]:::backend
    end

    subgraph "OneBot Module"
        onebot["OneBot Integration"]:::onebot
    end

    subgraph "Web UI / Frontend"
        webUI["Web UI (React)"]:::frontend
        webAPIRouter["API Routers & Middleware"]:::frontend
    end

    subgraph "Native Modules & Plugin System"
        nativeModules["Native Modules"]:::native
        pty["Terminal Emulation (PTY)"]:::native
        plugins["Plugin System"]:::native
    end

    subgraph "External Dependencies & Supporting Scripts"
        externalDeps["External Dependencies"]:::external
        scripts["Supporting Scripts"]:::external
    end

    launcher -->|"init"| botCore
    botCore -->|"protocol_handling"| onebot
    botCore -->|"sends_API_calls"| webUI
    webUI -->|"receives_updates"| botCore
    botCore -->|"uses_native"| nativeModules
    botCore -->|"uses_scripts"| scripts
    botCore -->|"integrates_external"| externalDeps

    classDef launcher fill:#F4A261,stroke:#000,stroke-width:2px;
    classDef backend fill:#2A9D8F,stroke:#000,stroke-width:2px;
    classDef onebot fill:#E9C46A,stroke:#000,stroke-width:2px;
    classDef frontend fill:#264653,stroke:#fff,stroke-width:2px,color:#fff;
    classDef native fill:#E76F51,stroke:#000,stroke-width:2px;
    classDef external fill:#8a8a8a,stroke:#000,stroke-width:2px;

    click launcher "https://github.com/napneko/napcatqq/tree/main/launcher/"
    click botCore "https://github.com/napneko/napcatqq/tree/main/src/core/"
    click onebot "https://github.com/napneko/napcatqq/tree/main/src/onebot/"
    click webUI "https://github.com/napneko/napcatqq/tree/main/napcat.webui/"
    click webAPIRouter "https://github.com/napneko/napcatqq/tree/main/src/webui/"
    click nativeModules "https://github.com/napneko/napcatqq/tree/main/src/native/"
    click pty "https://github.com/napneko/napcatqq/tree/main/src/pty/"
    click plugins "https://github.com/napneko/napcatqq/tree/main/src/plugin/"
    click externalDeps "https://github.com/napneko/napcatqq/tree/main/external/"
    click scripts "https://github.com/napneko/napcatqq/tree/main/script/"
```
