# qingyingx-bot/speaker-statistics-plugin architecture

> Architecture diagram of the GitHub repository qingyingx-bot/speaker-statistics-plugin, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/qingyingx-bot/speaker-statistics-plugin
- Repository: https://github.com/qingyingx-bot/speaker-statistics-plugin

## Overview

This is a Yunzai-Bot group-chat statistics plugin. Its main workflow records messages, persists hourly and aggregate statistics, answers ranking and personal-stat queries, and renders results for users. Separate capabilities cover group analysis and word clouds, Web administration and ranking backgrounds, and configuration management. The README documents these product branches; sampled source confirms database aggregation, configuration, plugin startup, and background administration, but not every command-to-service call, so uncertain wiring is omitted.

Main entry points: [`core/database/DatabaseService.js`](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/DatabaseService.js) (Statistics database), [`index.js`](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/index.js) (Plugin startup), [`core/web/WebServer.js`](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/web/WebServer.js) (Web administration), [`apps/speaker.js`](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/speaker.js) (Message listener)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Message collection"]
  node_speaker["Message listener<br/>[speaker.js]"]
  node_recorder["Message recorder<br/>[MessageRecorder.js]"]
  node_collector["Message collector"]
end

subgraph group_stats["Statistics and rendering"]
  node_commands["User commands<br/>[UserCommands.js]"]
  node_rankcmds["Ranking commands<br/>[RankCommands.js]"]
  node_data["Statistics access<br/>[DataService.js]"]
  node_database[("Statistics database<br/>[DatabaseService.js]")]
  node_pg["PostgreSQL adapter"]
  node_sqlite["SQLite adapter<br/>[SQLiteAdapter.js]"]
  node_render["Result rendering<br/>[TemplateManager.js]"]
end

subgraph group_analysis["Analysis features"]
  node_reportcmds["Report commands<br/>[ReportCommands.js]"]
  node_cloudcmds["Word-cloud commands"]
  node_statistics["Report statistics"]
  node_analyzers["AI analyzers<br/>[BaseAnalyzer.js]"]
  node_wordcloud["Word-cloud generation"]
end

subgraph group_admin["Administration"]
  node_web["Web administration<br/>[WebServer.js]"]
  node_background["Background management"]
  node_backgroundservice["Background storage"]
end

subgraph group_platform["Integration and configuration"]
  node_plugin["Plugin startup<br/>[index.js]"]
  node_guoba["Guoba configuration<br/>[guoba.support.js]"]
  node_config["Configuration manager<br/>[ConfigManager.js]"]
end

node_members(("Group members"))
node_redis[("Yunzai Redis")]
node_user(("Plugin user"))

node_members -->|"send messages"| node_speaker
node_speaker -->|"records messages"| node_recorder
node_recorder -->|"writes statistics"| node_database
node_collector -->|"collects messages"| node_database
node_plugin -->|"initializes"| node_database
node_plugin -->|"starts"| node_web
node_plugin -->|"starts"| node_collector
node_database -->|"uses when configured"| node_pg
node_database -->|"uses when configured"| node_sqlite
node_user -->|"requests statistics"| node_commands
node_user -->|"requests rankings"| node_rankcmds
node_commands -->|"queries statistics"| node_data
node_rankcmds -->|"queries rankings"| node_data
node_data -->|"reads statistics"| node_database
node_commands -->|"renders results"| node_render
node_rankcmds -->|"renders rankings"| node_render
node_reportcmds -->|"analyzes messages"| node_statistics
node_reportcmds -.->|"requests AI analysis"| node_analyzers
node_cloudcmds -->|"generates word clouds"| node_wordcloud
node_user -->|"requests analysis"| node_reportcmds
node_user -->|"requests word clouds"| node_cloudcmds
node_web -->|"queries statistics"| node_database
node_web -->|"registers routes"| node_background
node_background -->|"lists and changes backgrounds"| node_backgroundservice
node_user -->|"opens administration"| node_web
node_guoba -->|"manages configuration"| node_config
node_plugin -->|"loads configuration"| node_config
node_speaker -.->|"uses Redis statistics"| node_redis

click node_plugin "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/index.js"
click node_speaker "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/speaker.js"
click node_recorder "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/MessageRecorder.js"
click node_collector "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/messageCollector.js"
click node_commands "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/UserCommands.js"
click node_rankcmds "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/RankCommands.js"
click node_reportcmds "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/ReportCommands.js"
click node_cloudcmds "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/WordCloudCommands.js"
click node_data "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/DataService.js"
click node_database "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/DatabaseService.js"
click node_pg "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/adapters/PostgreSQLAdapter.js"
click node_sqlite "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/adapters/SQLiteAdapter.js"
click node_render "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/render/TemplateManager.js"
click node_statistics "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/StatisticsService.js"
click node_analyzers "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/analyzers/BaseAnalyzer.js"
click node_wordcloud "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/wordCloudGenerator.js"
click node_web "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/web/WebServer.js"
click node_background "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/web/BackgroundAdminController.js"
click node_backgroundservice "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/BackgroundService.js"
click node_guoba "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/guoba.support.js"
click node_config "https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/ConfigManager.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_speaker,node_recorder,node_collector,node_user toneBlue
class node_commands,node_rankcmds,node_data,node_database,node_pg,node_sqlite,node_render,node_redis toneAmber
class node_reportcmds,node_cloudcmds,node_statistics,node_analyzers,node_wordcloud toneMint
class node_web,node_background,node_backgroundservice toneRose
class node_plugin,node_guoba,node_config,node_members toneIndigo
```

## Components

### Message collection

- [Message listener](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/speaker.js): `apps/speaker.js`
- [Message recorder](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/MessageRecorder.js): `core/MessageRecorder.js`
- [Message collector](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/messageCollector.js): `core/services/messageCollector.js`

### Statistics and rendering

- [User commands](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/UserCommands.js): `apps/commands/UserCommands.js`
- [Ranking commands](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/RankCommands.js): `apps/commands/RankCommands.js`
- [Statistics access](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/DataService.js): `core/DataService.js`
- [Statistics database](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/DatabaseService.js): `core/database/DatabaseService.js`
- [PostgreSQL adapter](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/adapters/PostgreSQLAdapter.js): `core/database/adapters/PostgreSQLAdapter.js`
- [SQLite adapter](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/database/adapters/SQLiteAdapter.js): `core/database/adapters/SQLiteAdapter.js`
- [Result rendering](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/render/TemplateManager.js): `core/render/TemplateManager.js`

### Analysis features

- [Report commands](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/ReportCommands.js): `apps/commands/ReportCommands.js`
- [Word-cloud commands](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/apps/commands/WordCloudCommands.js): `apps/commands/WordCloudCommands.js`
- [Report statistics](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/StatisticsService.js): `core/services/StatisticsService.js`
- [AI analyzers](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/analyzers/BaseAnalyzer.js): `core/services/analyzers/BaseAnalyzer.js`
- [Word-cloud generation](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/wordCloudGenerator.js): `core/services/wordCloudGenerator.js`

### Administration

- [Web administration](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/web/WebServer.js): `core/web/WebServer.js`
- [Background management](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/web/BackgroundAdminController.js): `core/web/BackgroundAdminController.js`
- [Background storage](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/services/BackgroundService.js): `core/services/BackgroundService.js`

### Integration and configuration

- [Plugin startup](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/index.js): `index.js`
- [Guoba configuration](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/guoba.support.js): `guoba.support.js`
- [Configuration manager](https://github.com/qingyingx-bot/speaker-statistics-plugin/blob/master/core/ConfigManager.js): `core/ConfigManager.js`

### Other components

- **Group members**
- **Yunzai Redis**
- **Plugin user**

## Connections

- Group members → Message listener: send messages
- Message listener → Message recorder: records messages
- Message recorder → Statistics database: writes statistics
- Message collector → Statistics database: collects messages
- Plugin startup → Statistics database: initializes
- Plugin startup → Web administration: starts
- Plugin startup → Message collector: starts
- Statistics database → PostgreSQL adapter: uses when configured
- Statistics database → SQLite adapter: uses when configured
- Plugin user → User commands: requests statistics
- Plugin user → Ranking commands: requests rankings
- User commands → Statistics access: queries statistics
- Ranking commands → Statistics access: queries rankings
- Statistics access → Statistics database: reads statistics
- User commands → Result rendering: renders results
- Ranking commands → Result rendering: renders rankings
- Report commands → Report statistics: analyzes messages
- Report commands → AI analyzers: requests AI analysis
- Word-cloud commands → Word-cloud generation: generates word clouds
- Plugin user → Report commands: requests analysis
- Plugin user → Word-cloud commands: requests word clouds
- Web administration → Statistics database: queries statistics
- Web administration → Background management: registers routes
- Background management → Background storage: lists and changes backgrounds
- Plugin user → Web administration: opens administration
- Guoba configuration → Configuration manager: manages configuration
- Plugin startup → Configuration manager: loads configuration
- Message listener → Yunzai Redis: uses Redis statistics