# bredrumb/tomoribot architecture

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

- Interactive diagram: https://gitdiagram.com/bredrumb/tomoribot
- Repository: https://github.com/bredrumb/tomoribot

## Overview

TomoriBot is a self-hosted Discord AI assistant and role-play system. Its principal workflow starts with a Discord message, builds a turn and context, invokes a configured model (and optionally tools), then responds in Discord. Separate branches cover slash-command configuration, personas and memory, media generation and transcription, web/MCP tools, and scheduled work. The graph uses documented capabilities and paths from the tree; sampled excerpts do not establish every runtime connection, so uncertain wiring is omitted.

Main entry points: [`src/tools/toolRegistry.ts`](https://github.com/bredrumb/tomoribot/blob/main/src/tools/toolRegistry.ts) (Tool registry), [`src/utils/db/repositories`](https://github.com/bredrumb/tomoribot/tree/main/src/utils/db/repositories) (Personas and memory), [`src/commands/respond.ts`](https://github.com/bredrumb/tomoribot/blob/main/src/commands/respond.ts) (Slash commands), [`src/utils/chat/contextPipelineIntent.ts`](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/contextPipelineIntent.ts) (Context builder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discord["Discord interface"]
  node_message_entry["Message handler<br/>[tomoriChat.ts]"]
  node_commands["Slash commands<br/>[respond.ts]"]
end

subgraph group_conversation["Conversation runtime"]
  node_chat_turn["Turn admission<br/>[admission.ts]"]
  node_context["Context builder"]
  node_turn_planner["Turn planning<br/>[turnPlanner.ts]"]
  node_tool_loop["Tool execution loop<br/>[toolLoop.ts]"]
  node_response["Response emitter<br/>[responseEmitter.ts]"]
end

subgraph group_capabilities["AI and tools"]
  node_provider["Model providers"]
  node_tool_registry["Tool registry<br/>[toolRegistry.ts]"]
  node_web_search["Web search<br/>[dispatcher.ts]"]
  node_fetch_url["URL fetching<br/>[dispatcher.ts]"]
  node_mcp_tools["MCP servers"]
end

subgraph group_state["Personas and state"]
  node_command_ops["Configuration operations"]
  node_persona_memory["Personas and memory"]
  node_scheduled["Scheduled work"]
end

subgraph group_media["Multimodal"]
  node_media_commands["Media commands"]
  node_media_tools["Media tools"]
  node_audio["Audio services"]
  node_avatar_storage["Avatar storage<br/>[avatarStorage.ts]"]
end

node_discord_user(("Discord user"))
node_discord_platform(("Discord"))
node_model_service(("Model APIs"))
node_database[("PostgreSQL")]
node_inference_servers["Local inference servers"]

node_discord_user -->|"sends message"| node_discord_platform
node_discord_platform -->|"delivers event"| node_message_entry
node_discord_platform -->|"delivers command"| node_commands
node_message_entry -->|"starts turn"| node_chat_turn
node_chat_turn -->|"builds context"| node_context
node_context -->|"loads context"| node_persona_memory
node_context -->|"provides context"| node_turn_planner
node_turn_planner -->|"requests generation"| node_provider
node_provider -->|"calls model"| node_model_service
node_provider -->|"dispatches tool calls"| node_tool_loop
node_tool_loop -->|"resolves tools"| node_tool_registry
node_tool_registry -->|"dispatches search"| node_web_search
node_tool_registry -->|"dispatches fetch"| node_fetch_url
node_tool_registry -.->|"dispatches MCP"| node_mcp_tools
node_tool_loop -->|"updates memory"| node_persona_memory
node_turn_planner -->|"provides result"| node_response
node_response -->|"sends reply"| node_discord_platform
node_commands -->|"invokes operations"| node_command_ops
node_command_ops -->|"reads and writes"| node_persona_memory
node_persona_memory -->|"queries and persists"| node_database
node_scheduled -->|"updates state"| node_persona_memory
node_commands -->|"invokes generation"| node_media_commands
node_tool_registry -->|"dispatches media"| node_media_tools
node_media_commands -.->|"requests inference"| node_inference_servers
node_media_tools -->|"uses audio services"| node_audio
node_audio -.->|"requests inference"| node_inference_servers
node_command_ops -.->|"stores persona assets"| node_avatar_storage

click node_message_entry "https://github.com/bredrumb/tomoribot/blob/main/src/events/messageCreate/tomoriChat.ts"
click node_commands "https://github.com/bredrumb/tomoribot/blob/main/src/commands/respond.ts"
click node_chat_turn "https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/admission.ts"
click node_context "https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/contextPipelineIntent.ts"
click node_turn_planner "https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/turnPlanner.ts"
click node_tool_loop "https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/toolLoop.ts"
click node_response "https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/responseEmitter.ts"
click node_provider "https://github.com/bredrumb/tomoribot/tree/main/src/providers"
click node_tool_registry "https://github.com/bredrumb/tomoribot/blob/main/src/tools/toolRegistry.ts"
click node_web_search "https://github.com/bredrumb/tomoribot/blob/main/src/tools/webSearch/dispatcher.ts"
click node_fetch_url "https://github.com/bredrumb/tomoribot/blob/main/src/tools/fetchUrl/dispatcher.ts"
click node_mcp_tools "https://github.com/bredrumb/tomoribot/tree/main/src/tools/mcpServers"
click node_command_ops "https://github.com/bredrumb/tomoribot/tree/main/src/commands"
click node_persona_memory "https://github.com/bredrumb/tomoribot/tree/main/src/utils/db/repositories"
click node_scheduled "https://github.com/bredrumb/tomoribot/blob/main/src/timers/scheduledWorkCoordinator.ts"
click node_media_commands "https://github.com/bredrumb/tomoribot/tree/main/src/commands/generate"
click node_media_tools "https://github.com/bredrumb/tomoribot/tree/main/src/tools/functionCalls"
click node_audio "https://github.com/bredrumb/tomoribot/tree/main/src/utils/audio"
click node_inference_servers "https://github.com/bredrumb/tomoribot/tree/main/servers"
click node_avatar_storage "https://github.com/bredrumb/tomoribot/blob/main/src/utils/storage/avatarStorage.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_message_entry,node_commands,node_discord_user toneBlue
class node_chat_turn,node_context,node_turn_planner,node_tool_loop,node_response,node_database toneAmber
class node_provider,node_tool_registry,node_web_search,node_fetch_url,node_mcp_tools,node_model_service,node_inference_servers toneMint
class node_command_ops,node_persona_memory,node_scheduled toneRose
class node_media_commands,node_media_tools,node_audio,node_avatar_storage,node_discord_platform toneIndigo
```

## Components

### Discord interface

- [Message handler](https://github.com/bredrumb/tomoribot/blob/main/src/events/messageCreate/tomoriChat.ts): `src/events/messageCreate/tomoriChat.ts`
- [Slash commands](https://github.com/bredrumb/tomoribot/blob/main/src/commands/respond.ts): `src/commands/respond.ts`

### Conversation runtime

- [Turn admission](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/admission.ts): `src/utils/chat/admission.ts`
- [Context builder](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/contextPipelineIntent.ts): `src/utils/chat/contextPipelineIntent.ts`
- [Turn planning](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/turnPlanner.ts): `src/utils/chat/turnPlanner.ts`
- [Tool execution loop](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/toolLoop.ts): `src/utils/chat/toolLoop.ts`
- [Response emitter](https://github.com/bredrumb/tomoribot/blob/main/src/utils/chat/responseEmitter.ts): `src/utils/chat/responseEmitter.ts`

### AI and tools

- [Model providers](https://github.com/bredrumb/tomoribot/tree/main/src/providers): `src/providers`
- [Tool registry](https://github.com/bredrumb/tomoribot/blob/main/src/tools/toolRegistry.ts): `src/tools/toolRegistry.ts`
- [Web search](https://github.com/bredrumb/tomoribot/blob/main/src/tools/webSearch/dispatcher.ts): `src/tools/webSearch/dispatcher.ts`
- [URL fetching](https://github.com/bredrumb/tomoribot/blob/main/src/tools/fetchUrl/dispatcher.ts): `src/tools/fetchUrl/dispatcher.ts`
- [MCP servers](https://github.com/bredrumb/tomoribot/tree/main/src/tools/mcpServers): `src/tools/mcpServers`

### Personas and state

- [Configuration operations](https://github.com/bredrumb/tomoribot/tree/main/src/commands): `src/commands`
- [Personas and memory](https://github.com/bredrumb/tomoribot/tree/main/src/utils/db/repositories): `src/utils/db/repositories`
- [Scheduled work](https://github.com/bredrumb/tomoribot/blob/main/src/timers/scheduledWorkCoordinator.ts): `src/timers/scheduledWorkCoordinator.ts`

### Multimodal

- [Media commands](https://github.com/bredrumb/tomoribot/tree/main/src/commands/generate): `src/commands/generate`
- [Media tools](https://github.com/bredrumb/tomoribot/tree/main/src/tools/functionCalls): `src/tools/functionCalls`
- [Audio services](https://github.com/bredrumb/tomoribot/tree/main/src/utils/audio): `src/utils/audio`
- [Avatar storage](https://github.com/bredrumb/tomoribot/blob/main/src/utils/storage/avatarStorage.ts): `src/utils/storage/avatarStorage.ts`

### Other components

- **Discord user**
- **Discord**
- **Model APIs**
- **PostgreSQL**
- [Local inference servers](https://github.com/bredrumb/tomoribot/tree/main/servers): `servers`

## Connections

- Discord user → Discord: sends message
- Discord → Message handler: delivers event
- Discord → Slash commands: delivers command
- Message handler → Turn admission: starts turn
- Turn admission → Context builder: builds context
- Context builder → Personas and memory: loads context
- Context builder → Turn planning: provides context
- Turn planning → Model providers: requests generation
- Model providers → Model APIs: calls model
- Model providers → Tool execution loop: dispatches tool calls
- Tool execution loop → Tool registry: resolves tools
- Tool registry → Web search: dispatches search
- Tool registry → URL fetching: dispatches fetch
- Tool registry → MCP servers: dispatches MCP
- Tool execution loop → Personas and memory: updates memory
- Turn planning → Response emitter: provides result
- Response emitter → Discord: sends reply
- Slash commands → Configuration operations: invokes operations
- Configuration operations → Personas and memory: reads and writes
- Personas and memory → PostgreSQL: queries and persists
- Scheduled work → Personas and memory: updates state
- Slash commands → Media commands: invokes generation
- Tool registry → Media tools: dispatches media
- Media commands → Local inference servers: requests inference
- Media tools → Audio services: uses audio services
- Audio services → Local inference servers: requests inference
- Configuration operations → Avatar storage: stores persona assets