# 102300671/grouphub architecture

> Architecture diagram of the GitHub repository 102300671/grouphub, 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/102300671/grouphub
- Repository: https://github.com/102300671/grouphub

## Overview

Grouphub is a private QQ-group resource-sharing site with a Vue web client, FastAPI backend, and nonebot2 QQ bot. Members browse and contribute works, read or watch files, discuss and review works, and publish fanworks; membership and administrator controls gate access. The bot supports binding and member synchronization, work submission, and AI commands. The graph follows documented capabilities and sampled router wiring; some frontend-to-API and unsampled domain links are shown as unverified rather than asserted.

Main entry points: [`backend/app/main.py`](https://github.com/102300671/grouphub/blob/main/backend/app/main.py) (API routing), [`backend/app/models.py`](https://github.com/102300671/grouphub/blob/main/backend/app/models.py) (Domain records), [`qqbot/plugins/cli_router.py`](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/cli_router.py) (Command router), [`backend/app/storage.py`](https://github.com/102300671/grouphub/blob/main/backend/app/storage.py) (Storage failover)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web client"]
  node_webapp["Site interface<br/>[App.vue]"]
  node_webapi["Web API client<br/>[index.ts]"]
  node_workviews["Works and reader<br/>[WorksView.vue]"]
  node_communityviews["Forum and fanworks<br/>[ForumView.vue]"]
  node_adminviews["Admin console<br/>[SettingsView.vue]"]
end

subgraph group_backend["Backend services"]
  node_api_entry["API routing<br/>[main.py]"]
  node_auth["Registration and auth<br/>[auth.py]"]
  node_admin_api["Admin API<br/>[admin.py]"]
  node_ai_api["AI assistant API<br/>[ai.py]"]
  node_ai_service["AI service<br/>[ai_service.py]"]
  node_db[("Database session<br/>[db.py]")]
  node_models["Domain records<br/>[models.py]"]
  node_security["Access control<br/>[security.py]"]
end

subgraph group_content["Community content"]
  node_works_api["Works and reading API<br/>[works.py]"]
  node_reviews_api["Reviews API<br/>[reviews.py]"]
  node_forum_api["Forum API<br/>[forum.py]"]
  node_fanworks_api["Fanworks API<br/>[fanworks.py]"]
end

subgraph group_storage["File storage"]
  node_storage["Storage failover<br/>[storage.py]"]
  node_zfile["Zfile adapter<br/>[zfile_client.py]"]
  node_alist["Alist adapter<br/>[alist_client.py]"]
  node_file_services["File services"]
end

subgraph group_bot["QQ bot"]
  node_bot_entry["Bot entry<br/>[bot.py]"]
  node_bot_router["Command router<br/>[cli_router.py]"]
  node_bot_cli["Command parser<br/>[cli.py]"]
  node_bot_auth["Binding commands<br/>[auth.py]"]
  node_bot_work["Work commands<br/>[work.py]"]
  node_bot_ai["AI commands<br/>[ai.py]"]
  node_bot_tools["AI tools<br/>[aitools.py]"]
  node_bot_client["Backend HTTP client<br/>[client.py]"]
  node_bot_members["Member sync"]
  node_bot_adapter["QQ adapters<br/>[bots.py]"]
end

node_member(("Group member"))
node_bot_actor(("QQ group"))

node_member -.->|"uses"| node_webapp
node_webapp -.->|"requests"| node_webapi
node_webapp -.->|"presents"| node_workviews
node_webapp -.->|"presents"| node_communityviews
node_webapp -.->|"presents"| node_adminviews
node_webapi -.->|"calls"| node_api_entry
node_api_entry -->|"registers"| node_auth
node_api_entry -->|"registers"| node_works_api
node_api_entry -->|"registers"| node_reviews_api
node_api_entry -->|"registers"| node_forum_api
node_api_entry -->|"registers"| node_fanworks_api
node_api_entry -->|"registers"| node_admin_api
node_api_entry -->|"registers"| node_ai_api
node_api_entry -->|"initializes"| node_db
node_auth -->|"queries"| node_models
node_auth -->|"uses session"| node_db
node_auth -->|"authenticates"| node_security
node_works_api -.->|"queries"| node_models
node_works_api -.->|"uses session"| node_db
node_reviews_api -->|"queries"| node_models
node_reviews_api -->|"uses session"| node_db
node_reviews_api -->|"checks access"| node_security
node_forum_api -.->|"queries"| node_models
node_fanworks_api -.->|"queries"| node_models
node_admin_api -->|"queries"| node_models
node_admin_api -->|"uses session"| node_db
node_admin_api -->|"checks access"| node_security
node_ai_api -->|"delegates"| node_ai_service
node_ai_api -->|"queries"| node_models
node_storage -->|"uses adapter"| node_zfile
node_storage -->|"uses adapter"| node_alist
node_works_api -.->|"stores files"| node_storage
node_fanworks_api -.->|"stores attachments"| node_storage
node_reviews_api -.->|"stores attachments"| node_storage
node_file_services -.->|"primary and fallback"| node_storage
node_bot_entry -.->|"loads plugins"| node_bot_router
node_bot_actor -.->|"sends commands"| node_bot_router
node_bot_router -->|"parses"| node_bot_cli
node_bot_router -->|"dispatches"| node_bot_auth
node_bot_router -->|"dispatches"| node_bot_work
node_bot_router -->|"dispatches"| node_bot_ai
node_bot_work -->|"calls backend"| node_bot_client
node_bot_auth -->|"calls backend"| node_bot_client
node_bot_members -->|"calls backend"| node_bot_client
node_bot_ai -->|"uses tools"| node_bot_tools
node_bot_ai -.->|"calls backend"| node_bot_client
node_bot_client -.->|"HTTP requests"| node_auth
node_bot_client -.->|"HTTP requests"| node_works_api

click node_webapp "https://github.com/102300671/grouphub/blob/main/frontend/src/App.vue"
click node_webapi "https://github.com/102300671/grouphub/blob/main/frontend/src/api/index.ts"
click node_workviews "https://github.com/102300671/grouphub/blob/main/frontend/src/views/WorksView.vue"
click node_communityviews "https://github.com/102300671/grouphub/blob/main/frontend/src/views/ForumView.vue"
click node_adminviews "https://github.com/102300671/grouphub/blob/main/frontend/src/views/admin/SettingsView.vue"
click node_api_entry "https://github.com/102300671/grouphub/blob/main/backend/app/main.py"
click node_auth "https://github.com/102300671/grouphub/blob/main/backend/app/api/auth.py"
click node_works_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/works.py"
click node_reviews_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/reviews.py"
click node_forum_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/forum.py"
click node_fanworks_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/fanworks.py"
click node_admin_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/admin.py"
click node_ai_api "https://github.com/102300671/grouphub/blob/main/backend/app/api/ai.py"
click node_ai_service "https://github.com/102300671/grouphub/blob/main/backend/app/ai_service.py"
click node_db "https://github.com/102300671/grouphub/blob/main/backend/app/db.py"
click node_models "https://github.com/102300671/grouphub/blob/main/backend/app/models.py"
click node_security "https://github.com/102300671/grouphub/blob/main/backend/app/security.py"
click node_storage "https://github.com/102300671/grouphub/blob/main/backend/app/storage.py"
click node_zfile "https://github.com/102300671/grouphub/blob/main/backend/app/zfile_client.py"
click node_alist "https://github.com/102300671/grouphub/blob/main/backend/app/alist_client.py"
click node_bot_entry "https://github.com/102300671/grouphub/blob/main/qqbot/bot.py"
click node_bot_router "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/cli_router.py"
click node_bot_cli "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/cli.py"
click node_bot_auth "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/auth.py"
click node_bot_work "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/work.py"
click node_bot_ai "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/ai.py"
click node_bot_tools "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/aitools.py"
click node_bot_client "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/client.py"
click node_bot_members "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/group_member_sync.py"
click node_bot_adapter "https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/bots.py"

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_webapp,node_webapi,node_workviews,node_communityviews,node_adminviews toneBlue
class node_api_entry,node_auth,node_admin_api,node_ai_api,node_ai_service,node_db,node_models,node_security toneAmber
class node_works_api,node_reviews_api,node_forum_api,node_fanworks_api toneMint
class node_storage,node_zfile,node_alist,node_file_services toneRose
class node_bot_entry,node_bot_router,node_bot_cli,node_bot_auth,node_bot_work,node_bot_ai,node_bot_tools,node_bot_client,node_bot_members,node_bot_adapter,node_member,node_bot_actor toneIndigo
```

## Components

### Web client

- [Site interface](https://github.com/102300671/grouphub/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Web API client](https://github.com/102300671/grouphub/blob/main/frontend/src/api/index.ts): `frontend/src/api/index.ts`
- [Works and reader](https://github.com/102300671/grouphub/blob/main/frontend/src/views/WorksView.vue): `frontend/src/views/WorksView.vue`
- [Forum and fanworks](https://github.com/102300671/grouphub/blob/main/frontend/src/views/ForumView.vue): `frontend/src/views/ForumView.vue`
- [Admin console](https://github.com/102300671/grouphub/blob/main/frontend/src/views/admin/SettingsView.vue): `frontend/src/views/admin/SettingsView.vue`

### Backend services

- [API routing](https://github.com/102300671/grouphub/blob/main/backend/app/main.py): `backend/app/main.py`
- [Registration and auth](https://github.com/102300671/grouphub/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Admin API](https://github.com/102300671/grouphub/blob/main/backend/app/api/admin.py): `backend/app/api/admin.py`
- [AI assistant API](https://github.com/102300671/grouphub/blob/main/backend/app/api/ai.py): `backend/app/api/ai.py`
- [AI service](https://github.com/102300671/grouphub/blob/main/backend/app/ai_service.py): `backend/app/ai_service.py`
- [Database session](https://github.com/102300671/grouphub/blob/main/backend/app/db.py): `backend/app/db.py`
- [Domain records](https://github.com/102300671/grouphub/blob/main/backend/app/models.py): `backend/app/models.py`
- [Access control](https://github.com/102300671/grouphub/blob/main/backend/app/security.py): `backend/app/security.py`

### Community content

- [Works and reading API](https://github.com/102300671/grouphub/blob/main/backend/app/api/works.py): `backend/app/api/works.py`
- [Reviews API](https://github.com/102300671/grouphub/blob/main/backend/app/api/reviews.py): `backend/app/api/reviews.py`
- [Forum API](https://github.com/102300671/grouphub/blob/main/backend/app/api/forum.py): `backend/app/api/forum.py`
- [Fanworks API](https://github.com/102300671/grouphub/blob/main/backend/app/api/fanworks.py): `backend/app/api/fanworks.py`

### File storage

- [Storage failover](https://github.com/102300671/grouphub/blob/main/backend/app/storage.py): `backend/app/storage.py`
- [Zfile adapter](https://github.com/102300671/grouphub/blob/main/backend/app/zfile_client.py): `backend/app/zfile_client.py`
- [Alist adapter](https://github.com/102300671/grouphub/blob/main/backend/app/alist_client.py): `backend/app/alist_client.py`
- **File services**

### QQ bot

- [Bot entry](https://github.com/102300671/grouphub/blob/main/qqbot/bot.py): `qqbot/bot.py`
- [Command router](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/cli_router.py): `qqbot/plugins/cli_router.py`
- [Command parser](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/cli.py): `qqbot/plugins/_lib/cli.py`
- [Binding commands](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/auth.py): `qqbot/plugins/commands/auth.py`
- [Work commands](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/work.py): `qqbot/plugins/commands/work.py`
- [AI commands](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/commands/ai.py): `qqbot/plugins/commands/ai.py`
- [AI tools](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/aitools.py): `qqbot/plugins/_lib/aitools.py`
- [Backend HTTP client](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/client.py): `qqbot/plugins/_lib/client.py`
- [Member sync](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/group_member_sync.py): `qqbot/plugins/group_member_sync.py`
- [QQ adapters](https://github.com/102300671/grouphub/blob/main/qqbot/plugins/_lib/bots.py): `qqbot/plugins/_lib/bots.py`

### Other components

- **Group member**
- **QQ group**

## Connections

- Group member → Site interface: uses
- Site interface → Web API client: requests
- Site interface → Works and reader: presents
- Site interface → Forum and fanworks: presents
- Site interface → Admin console: presents
- Web API client → API routing: calls
- API routing → Registration and auth: registers (evidence: `backend/app/main.py`)
- API routing → Works and reading API: registers (evidence: `backend/app/main.py`)
- API routing → Reviews API: registers (evidence: `backend/app/main.py`)
- API routing → Forum API: registers (evidence: `backend/app/main.py`)
- API routing → Fanworks API: registers (evidence: `backend/app/main.py`)
- API routing → Admin API: registers (evidence: `backend/app/main.py`)
- API routing → AI assistant API: registers (evidence: `backend/app/main.py`)
- API routing → Database session: initializes (evidence: `backend/app/main.py`)
- Registration and auth → Domain records: queries (evidence: `backend/app/api/auth.py`)
- Registration and auth → Database session: uses session (evidence: `backend/app/api/auth.py`)
- Registration and auth → Access control: authenticates (evidence: `backend/app/api/auth.py`)
- Works and reading API → Domain records: queries
- Works and reading API → Database session: uses session
- Reviews API → Domain records: queries (evidence: `backend/app/api/reviews.py`)
- Reviews API → Database session: uses session (evidence: `backend/app/api/reviews.py`)
- Reviews API → Access control: checks access (evidence: `backend/app/api/reviews.py`)
- Forum API → Domain records: queries
- Fanworks API → Domain records: queries (evidence: `backend/app/api/fanworks.py`)
- Admin API → Domain records: queries (evidence: `backend/app/api/admin.py`)
- Admin API → Database session: uses session (evidence: `backend/app/api/admin.py`)
- Admin API → Access control: checks access (evidence: `backend/app/api/admin.py`)
- AI assistant API → AI service: delegates (evidence: `backend/app/api/ai.py`)
- AI assistant API → Domain records: queries (evidence: `backend/app/api/ai.py`)
- Storage failover → Zfile adapter: uses adapter (evidence: `backend/app/storage.py`)
- Storage failover → Alist adapter: uses adapter (evidence: `backend/app/storage.py`)
- Works and reading API → Storage failover: stores files
- Fanworks API → Storage failover: stores attachments (evidence: `backend/app/api/fanworks.py`)
- Reviews API → Storage failover: stores attachments (evidence: `backend/app/api/reviews.py`)
- File services → Storage failover: primary and fallback
- Bot entry → Command router: loads plugins
- QQ group → Command router: sends commands
- Command router → Command parser: parses (evidence: `qqbot/plugins/cli_router.py`)
- Command router → Binding commands: dispatches (evidence: `qqbot/plugins/cli_router.py`)
- Command router → Work commands: dispatches (evidence: `qqbot/plugins/cli_router.py`)
- Command router → AI commands: dispatches (evidence: `qqbot/plugins/cli_router.py`)
- Work commands → Backend HTTP client: calls backend (evidence: `qqbot/plugins/commands/work.py`)
- Binding commands → Backend HTTP client: calls backend (evidence: `qqbot/plugins/commands/auth.py`)
- Member sync → Backend HTTP client: calls backend (evidence: `qqbot/plugins/group_member_sync.py`)
- AI commands → AI tools: uses tools (evidence: `qqbot/plugins/commands/ai.py`)
- AI commands → Backend HTTP client: calls backend
- Backend HTTP client → Registration and auth: HTTP requests
- Backend HTTP client → Works and reading API: HTTP requests
