# trytodupe/ttd-bot architecture

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

- Interactive diagram: https://gitdiagram.com/trytodupe/ttd-bot
- Repository: https://github.com/trytodupe/ttd-bot

## Overview

ttd-bot is a NoneBot/OneBot chat bot with a broad plugin suite, plus a disabled-by-default isolated QQ development agent. The development workflow accepts routed chat events over a local socket, applies access/admin and session handling, runs agent work in isolated guest slots, and can stage changes or create draft pull requests. The plugin tree also covers subscriptions, statistics, access requests, game/server queries, and Youmind agent interactions. Some plugin implementations and the separate dev-agent documentation were not sampled, so those capability nodes are directory-level and their internal links are omitted.

Main entry points: [`dev-agent/src/agent-runtime.ts`](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/agent-runtime.ts) (Agent runtime), [`dev-agent/src/controller.ts`](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/controller.ts) (Event controller), [`src/plugins/youmind_agent/service.py`](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/service.py) (Youmind agent), [`dev-agent/src/index.ts`](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/index.ts) (Agent launcher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_plugins["Bot capabilities"]
  node_help["Command help<br/>[registry.py]"]
  node_access_requests["Access requests<br/>[service.py]"]
  node_bilibili["Bilibili subscriptions<br/>[service.py]"]
  node_statistics["Chat statistics<br/>[statistics.py]"]
  node_queries["Game and score queries<br/>[__init__.py]"]
  node_server_checks["Server checks<br/>[__init__.py]"]
  node_youmind["Youmind agent<br/>[service.py]"]
  node_youmind_client["Youmind client<br/>[client.py]"]
  node_forward_bundle["Forward bundles<br/>[forward_bundle.py]"]
  node_agent_results["Agent results<br/>[results.py]"]
end

subgraph group_dev_control["Dev control"]
  node_controller["Event controller<br/>[controller.ts]"]
  node_socket["Socket ingress<br/>[socket-server.ts]"]
  node_access_admin["Access and admin<br/>[access.ts]"]
  node_session_service["Session service<br/>[session-service.ts]"]
  node_launcher["Agent launcher<br/>[index.ts]"]
end

subgraph group_execution["Isolated execution"]
  node_runtime["Agent runtime<br/>[agent-runtime.ts]"]
  node_activation["Slot activation<br/>[activation.ts]"]
  node_guest["Guest broker<br/>[guest-broker.ts]"]
  node_network_policy["Network policy<br/>[network-policy.ts]"]
end

subgraph group_state_integrations["State and integrations"]
  node_youmind_store[("Youmind state<br/>[storage.py]")]
  node_bilibili_store[("Subscription state<br/>[storage.py]")]
  node_github["GitHub publisher<br/>[github.ts]"]
  node_dev_store[("Agent state<br/>[store.ts]")]
end

node_qq_user(("QQ user"))
node_chat_user(("Chat user"))

node_youmind -->|"calls"| node_youmind_client
node_youmind -->|"uses"| node_forward_bundle
node_youmind -->|"uses"| node_agent_results
node_youmind -->|"persists"| node_youmind_store
node_bilibili -->|"reads and writes"| node_bilibili_store
node_socket -->|"dispatches"| node_controller
node_controller -->|"delegates"| node_access_admin
node_controller -->|"dispatches"| node_session_service
node_controller -->|"queries"| node_dev_store
node_session_service -->|"opens sessions"| node_runtime
node_session_service -->|"updates state"| node_dev_store
node_runtime -->|"activates"| node_activation
node_runtime -->|"uses"| node_guest
node_runtime -->|"publishes"| node_github
node_runtime -->|"reads and writes"| node_dev_store
node_activation -->|"allocates guest"| node_guest
node_guest -->|"applies policy"| node_network_policy
node_launcher -->|"starts"| node_socket
node_launcher -->|"constructs"| node_controller
node_launcher -->|"constructs"| node_runtime

click node_help "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/ttd_help/registry.py"
click node_access_requests "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/access_request/service.py"
click node_bilibili "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/bilibili_subscription/service.py"
click node_statistics "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/chat_statistics/statistics.py"
click node_queries "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/_etx_query/__init__.py"
click node_server_checks "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/mc_server_checker/__init__.py"
click node_youmind "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/service.py"
click node_youmind_client "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/client.py"
click node_forward_bundle "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/forward_bundle.py"
click node_agent_results "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/results.py"
click node_youmind_store "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/storage.py"
click node_bilibili_store "https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/bilibili_subscription/storage.py"
click node_controller "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/controller.ts"
click node_socket "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/socket-server.ts"
click node_access_admin "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/access.ts"
click node_session_service "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/session-service.ts"
click node_runtime "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/agent-runtime.ts"
click node_activation "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/activation.ts"
click node_guest "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/guest-broker.ts"
click node_network_policy "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/network-policy.ts"
click node_github "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/github.ts"
click node_dev_store "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/store.ts"
click node_launcher "https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/index.ts"

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_help,node_access_requests,node_bilibili,node_statistics,node_queries,node_server_checks,node_youmind,node_youmind_client,node_forward_bundle,node_agent_results,node_qq_user,node_chat_user toneBlue
class node_controller,node_socket,node_access_admin,node_session_service,node_launcher toneAmber
class node_runtime,node_activation,node_guest,node_network_policy toneMint
class node_youmind_store,node_bilibili_store,node_github,node_dev_store toneRose
```

## Components

### Bot capabilities

- [Command help](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/ttd_help/registry.py): `src/plugins/ttd_help/registry.py`
- [Access requests](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/access_request/service.py): `src/plugins/access_request/service.py`
- [Bilibili subscriptions](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/bilibili_subscription/service.py): `src/plugins/bilibili_subscription/service.py`
- [Chat statistics](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/chat_statistics/statistics.py): `src/plugins/chat_statistics/statistics.py`
- [Game and score queries](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/_etx_query/__init__.py): `src/plugins/_etx_query/__init__.py`
- [Server checks](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/mc_server_checker/__init__.py): `src/plugins/mc_server_checker/__init__.py`
- [Youmind agent](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/service.py): `src/plugins/youmind_agent/service.py`
- [Youmind client](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/client.py): `src/plugins/youmind_agent/client.py`
- [Forward bundles](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/forward_bundle.py): `src/plugins/youmind_agent/forward_bundle.py`
- [Agent results](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/results.py): `src/plugins/youmind_agent/results.py`

### Dev control

- [Event controller](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/controller.ts): `dev-agent/src/controller.ts`
- [Socket ingress](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/socket-server.ts): `dev-agent/src/socket-server.ts`
- [Access and admin](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/access.ts): `dev-agent/src/access.ts`
- [Session service](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/session-service.ts): `dev-agent/src/session-service.ts`
- [Agent launcher](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/index.ts): `dev-agent/src/index.ts`

### Isolated execution

- [Agent runtime](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/agent-runtime.ts): `dev-agent/src/agent-runtime.ts`
- [Slot activation](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/activation.ts): `dev-agent/src/activation.ts`
- [Guest broker](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/guest-broker.ts): `dev-agent/src/guest-broker.ts`
- [Network policy](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/network-policy.ts): `dev-agent/src/network-policy.ts`

### State and integrations

- [Youmind state](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/youmind_agent/storage.py): `src/plugins/youmind_agent/storage.py`
- [Subscription state](https://github.com/trytodupe/ttd-bot/blob/main/src/plugins/bilibili_subscription/storage.py): `src/plugins/bilibili_subscription/storage.py`
- [GitHub publisher](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/github.ts): `dev-agent/src/github.ts`
- [Agent state](https://github.com/trytodupe/ttd-bot/blob/main/dev-agent/src/store.ts): `dev-agent/src/store.ts`

### Other components

- **QQ user**
- **Chat user**

## Connections

- Youmind agent → Youmind client: calls (evidence: `src/plugins/youmind_agent/service.py`)
- Youmind agent → Forward bundles: uses (evidence: `src/plugins/youmind_agent/service.py`)
- Youmind agent → Agent results: uses (evidence: `src/plugins/youmind_agent/service.py`)
- Youmind agent → Youmind state: persists (evidence: `src/plugins/youmind_agent/service.py`)
- Bilibili subscriptions → Subscription state: reads and writes (evidence: `src/plugins/bilibili_subscription/service.py`)
- Socket ingress → Event controller: dispatches (evidence: `dev-agent/src/socket-server.ts`)
- Event controller → Access and admin: delegates (evidence: `dev-agent/src/controller.ts`)
- Event controller → Session service: dispatches (evidence: `dev-agent/src/controller.ts`)
- Event controller → Agent state: queries (evidence: `dev-agent/src/controller.ts`)
- Session service → Agent runtime: opens sessions (evidence: `dev-agent/src/session-service.ts`)
- Session service → Agent state: updates state (evidence: `dev-agent/src/session-service.ts`)
- Agent runtime → Slot activation: activates (evidence: `dev-agent/src/agent-runtime.ts`)
- Agent runtime → Guest broker: uses (evidence: `dev-agent/src/agent-runtime.ts`)
- Agent runtime → GitHub publisher: publishes (evidence: `dev-agent/src/agent-runtime.ts`)
- Agent runtime → Agent state: reads and writes (evidence: `dev-agent/src/agent-runtime.ts`)
- Slot activation → Guest broker: allocates guest (evidence: `dev-agent/src/activation.ts`)
- Guest broker → Network policy: applies policy (evidence: `dev-agent/src/guest-broker.ts`)
- Agent launcher → Socket ingress: starts (evidence: `dev-agent/src/index.ts`)
- Agent launcher → Event controller: constructs (evidence: `dev-agent/src/index.ts`)
- Agent launcher → Agent runtime: constructs (evidence: `dev-agent/src/index.ts`)
