# sanctumos/broca architecture

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

- Interactive diagram: https://gitdiagram.com/sanctumos/broca
- Repository: https://github.com/sanctumos/broca

## Overview

Sanctum: Broca 3 is a CLI-first middleware bridge between Letta and communication platforms. A typical message arrives through a platform plugin, is normalized and associated with a user, then enters persistent message/queue storage; the runtime processes queued work through the agent and returns platform-formatted output. The graph also includes documented administrative CLI capabilities and the shared persistence/configuration layers. Some plugin and runtime wiring is supported by README statements or SOURCE INDEX references rather than complete excerpts; unsampled details are not inferred.

Main entry points: [`plugins/telegram_bot/message_handler.py`](https://github.com/sanctumos/broca/blob/main/plugins/telegram_bot/message_handler.py) (Telegram bot), [`database/operations/users.py`](https://github.com/sanctumos/broca/blob/main/database/operations/users.py) (User operations), [`plugins/porter_vernal_webchat/message_handler.py`](https://github.com/sanctumos/broca/blob/main/plugins/porter_vernal_webchat/message_handler.py) (Porter web chat), [`plugins/q_vernal_webchat/message_handler.py`](https://github.com/sanctumos/broca/blob/main/plugins/q_vernal_webchat/message_handler.py) (Q web chat)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Message runtime"]
  node_main["Application<br/>[main.py]"]
  node_queue_runtime["Queue processor<br/>[queue.py]"]
  node_agent_runtime["Agent processing<br/>[agent.py]"]
  node_active_turn["Active turns<br/>[active_turn.py]"]
  node_message_format["Message model<br/>[message.py]"]
  node_image_handling["Image handling<br/>[image_handling.py]"]
  node_letta_client["Letta client<br/>[letta_client.py]"]
end

subgraph group_plugins["Platform plugins"]
  node_plugin_manager["Plugin manager<br/>[plugin.py]"]
  node_plugin_interface["Plugin interface<br/>[__init__.py]"]
  node_telegram_plugin["Telegram bot<br/>[message_handler.py]"]
  node_porter_webchat["Porter web chat<br/>[message_handler.py]"]
  node_q_webchat["Q web chat<br/>[message_handler.py]"]
end

subgraph group_storage["Persistence"]
  node_db_pool["Connection pool<br/>[pool.py]"]
  node_db_models["Database models<br/>[models.py]"]
  node_db_messages["Message operations<br/>[messages.py]"]
  node_db_queue["Queue operations<br/>[queue.py]"]
  node_db_users["User operations<br/>[users.py]"]
  node_database[("SQLite database")]
end

subgraph group_admin["Administration"]
  node_cli["Admin CLI<br/>[btool.py]"]
  node_cli_settings["Settings CLI<br/>[settings.py]"]
end

subgraph group_shared["Shared services"]
  node_config["Configuration<br/>[config.py]"]
  node_retry["Retry handling<br/>[retry.py]"]
end

node_operator(("Operator"))
node_telegram_user(("Telegram user"))
node_webchat_user(("Web chat user"))
node_letta_service["Letta service"]
node_telegram_service["Telegram"]
node_webchat_service["Web chat API"]

node_operator -->|"starts"| node_main
node_main -->|"initializes"| node_plugin_manager
node_main -->|"initializes"| node_queue_runtime
node_main -->|"initializes"| node_agent_runtime
node_main -->|"initializes"| node_db_pool
node_plugin_manager -->|"manages"| node_plugin_interface
node_plugin_manager -.->|"routes to"| node_telegram_plugin
node_plugin_manager -.->|"routes to"| node_porter_webchat
node_plugin_manager -.->|"routes to"| node_q_webchat
node_telegram_user -->|"sends message"| node_telegram_service
node_telegram_service -.->|"delivers message"| node_telegram_plugin
node_webchat_user -->|"sends message"| node_webchat_service
node_webchat_service -.->|"delivers message"| node_porter_webchat
node_webchat_service -.->|"delivers message"| node_q_webchat
node_telegram_plugin -->|"uses"| node_message_format
node_telegram_plugin -->|"uses"| node_image_handling
node_telegram_plugin -->|"gets profile"| node_db_users
node_telegram_plugin -->|"stores message"| node_db_messages
node_telegram_plugin -->|"queues message"| node_db_queue
node_telegram_plugin -->|"uses"| node_agent_runtime
node_porter_webchat -->|"uses"| node_message_format
node_porter_webchat -->|"gets profile"| node_db_users
node_porter_webchat -->|"stores message"| node_db_messages
node_porter_webchat -->|"queues message"| node_db_queue
node_porter_webchat -->|"uses"| node_agent_runtime
node_q_webchat -->|"uses"| node_message_format
node_q_webchat -->|"gets profile"| node_db_users
node_q_webchat -->|"stores message"| node_db_messages
node_q_webchat -->|"queues message"| node_db_queue
node_q_webchat -->|"uses"| node_active_turn
node_queue_runtime -->|"reads and updates"| node_db_messages
node_queue_runtime -->|"dequeues"| node_db_queue
node_queue_runtime -->|"reads users"| node_db_users
node_queue_runtime -->|"uses"| node_active_turn
node_queue_runtime -->|"uses"| node_letta_client
node_agent_runtime -->|"calls"| node_letta_client
node_agent_runtime -.->|"uses"| node_active_turn
node_letta_client -->|"calls API"| node_letta_service
node_db_users -->|"creates identities"| node_letta_client
node_db_messages -->|"uses connections"| node_db_pool
node_db_queue -->|"uses connections"| node_db_pool
node_db_users -->|"uses connections"| node_db_pool
node_db_messages -->|"uses models"| node_db_models
node_db_queue -->|"uses models"| node_db_models
node_db_users -->|"uses models"| node_db_models
node_db_pool -.->|"opens connections"| node_database
node_cli -.->|"manages queue"| node_db_queue
node_cli -.->|"manages users"| node_db_users

click node_main "https://github.com/sanctumos/broca/blob/main/main.py"
click node_queue_runtime "https://github.com/sanctumos/broca/blob/main/runtime/core/queue.py"
click node_agent_runtime "https://github.com/sanctumos/broca/blob/main/runtime/core/agent.py"
click node_active_turn "https://github.com/sanctumos/broca/blob/main/runtime/core/active_turn.py"
click node_message_format "https://github.com/sanctumos/broca/blob/main/runtime/core/message.py"
click node_image_handling "https://github.com/sanctumos/broca/blob/main/runtime/core/image_handling.py"
click node_letta_client "https://github.com/sanctumos/broca/blob/main/runtime/core/letta_client.py"
click node_plugin_manager "https://github.com/sanctumos/broca/blob/main/runtime/core/plugin.py"
click node_plugin_interface "https://github.com/sanctumos/broca/blob/main/plugins/__init__.py"
click node_telegram_plugin "https://github.com/sanctumos/broca/blob/main/plugins/telegram_bot/message_handler.py"
click node_porter_webchat "https://github.com/sanctumos/broca/blob/main/plugins/porter_vernal_webchat/message_handler.py"
click node_q_webchat "https://github.com/sanctumos/broca/blob/main/plugins/q_vernal_webchat/message_handler.py"
click node_db_pool "https://github.com/sanctumos/broca/blob/main/database/pool.py"
click node_db_models "https://github.com/sanctumos/broca/blob/main/database/models.py"
click node_db_messages "https://github.com/sanctumos/broca/blob/main/database/operations/messages.py"
click node_db_queue "https://github.com/sanctumos/broca/blob/main/database/operations/queue.py"
click node_db_users "https://github.com/sanctumos/broca/blob/main/database/operations/users.py"
click node_cli "https://github.com/sanctumos/broca/blob/main/cli/btool.py"
click node_cli_settings "https://github.com/sanctumos/broca/blob/main/cli/settings.py"
click node_config "https://github.com/sanctumos/broca/blob/main/common/config.py"
click node_retry "https://github.com/sanctumos/broca/blob/main/common/retry.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_main,node_queue_runtime,node_agent_runtime,node_active_turn,node_message_format,node_image_handling,node_letta_client,node_telegram_user,node_webchat_user toneBlue
class node_plugin_manager,node_plugin_interface,node_telegram_plugin,node_porter_webchat,node_q_webchat toneAmber
class node_db_pool,node_db_models,node_db_messages,node_db_queue,node_db_users,node_database,node_webchat_service toneMint
class node_cli,node_cli_settings toneRose
class node_config,node_retry,node_operator,node_letta_service,node_telegram_service toneIndigo
```

## Components

### Message runtime

- [Application](https://github.com/sanctumos/broca/blob/main/main.py): `main.py`
- [Queue processor](https://github.com/sanctumos/broca/blob/main/runtime/core/queue.py): `runtime/core/queue.py`
- [Agent processing](https://github.com/sanctumos/broca/blob/main/runtime/core/agent.py): `runtime/core/agent.py`
- [Active turns](https://github.com/sanctumos/broca/blob/main/runtime/core/active_turn.py): `runtime/core/active_turn.py`
- [Message model](https://github.com/sanctumos/broca/blob/main/runtime/core/message.py): `runtime/core/message.py`
- [Image handling](https://github.com/sanctumos/broca/blob/main/runtime/core/image_handling.py): `runtime/core/image_handling.py`
- [Letta client](https://github.com/sanctumos/broca/blob/main/runtime/core/letta_client.py): `runtime/core/letta_client.py`

### Platform plugins

- [Plugin manager](https://github.com/sanctumos/broca/blob/main/runtime/core/plugin.py): `runtime/core/plugin.py`
- [Plugin interface](https://github.com/sanctumos/broca/blob/main/plugins/__init__.py): `plugins/__init__.py`
- [Telegram bot](https://github.com/sanctumos/broca/blob/main/plugins/telegram_bot/message_handler.py): `plugins/telegram_bot/message_handler.py`
- [Porter web chat](https://github.com/sanctumos/broca/blob/main/plugins/porter_vernal_webchat/message_handler.py): `plugins/porter_vernal_webchat/message_handler.py`
- [Q web chat](https://github.com/sanctumos/broca/blob/main/plugins/q_vernal_webchat/message_handler.py): `plugins/q_vernal_webchat/message_handler.py`

### Persistence

- [Connection pool](https://github.com/sanctumos/broca/blob/main/database/pool.py): `database/pool.py`
- [Database models](https://github.com/sanctumos/broca/blob/main/database/models.py): `database/models.py`
- [Message operations](https://github.com/sanctumos/broca/blob/main/database/operations/messages.py): `database/operations/messages.py`
- [Queue operations](https://github.com/sanctumos/broca/blob/main/database/operations/queue.py): `database/operations/queue.py`
- [User operations](https://github.com/sanctumos/broca/blob/main/database/operations/users.py): `database/operations/users.py`
- **SQLite database**

### Administration

- [Admin CLI](https://github.com/sanctumos/broca/blob/main/cli/btool.py): `cli/btool.py`
- [Settings CLI](https://github.com/sanctumos/broca/blob/main/cli/settings.py): `cli/settings.py`

### Shared services

- [Configuration](https://github.com/sanctumos/broca/blob/main/common/config.py): `common/config.py`
- [Retry handling](https://github.com/sanctumos/broca/blob/main/common/retry.py): `common/retry.py`

### Other components

- **Operator**
- **Telegram user**
- **Web chat user**
- **Letta service**
- **Telegram**
- **Web chat API**

## Connections

- Operator → Application: starts (evidence: `README.md`)
- Application → Plugin manager: initializes (evidence: `main.py`)
- Application → Queue processor: initializes (evidence: `main.py`)
- Application → Agent processing: initializes (evidence: `main.py`)
- Application → Connection pool: initializes (evidence: `main.py`)
- Plugin manager → Plugin interface: manages (evidence: `runtime/core/plugin.py`)
- Plugin manager → Telegram bot: routes to
- Plugin manager → Porter web chat: routes to
- Plugin manager → Q web chat: routes to
- Telegram user → Telegram: sends message (evidence: `README.md`)
- Telegram → Telegram bot: delivers message
- Web chat user → Web chat API: sends message (evidence: `README.md`)
- Web chat API → Porter web chat: delivers message
- Web chat API → Q web chat: delivers message
- Telegram bot → Message model: uses (evidence: `plugins/telegram_bot/message_handler.py`)
- Telegram bot → Image handling: uses (evidence: `plugins/telegram_bot/message_handler.py`)
- Telegram bot → User operations: gets profile (evidence: `plugins/telegram_bot/message_handler.py`)
- Telegram bot → Message operations: stores message (evidence: `plugins/telegram_bot/message_handler.py`)
- Telegram bot → Queue operations: queues message (evidence: `plugins/telegram_bot/message_handler.py`)
- Telegram bot → Agent processing: uses (evidence: `plugins/telegram_bot/message_handler.py`)
- Porter web chat → Message model: uses (evidence: `plugins/porter_vernal_webchat/message_handler.py`)
- Porter web chat → User operations: gets profile (evidence: `plugins/porter_vernal_webchat/message_handler.py`)
- Porter web chat → Message operations: stores message (evidence: `plugins/porter_vernal_webchat/message_handler.py`)
- Porter web chat → Queue operations: queues message (evidence: `plugins/porter_vernal_webchat/message_handler.py`)
- Porter web chat → Agent processing: uses (evidence: `plugins/porter_vernal_webchat/message_handler.py`)
- Q web chat → Message model: uses (evidence: `plugins/q_vernal_webchat/message_handler.py`)
- Q web chat → User operations: gets profile (evidence: `plugins/q_vernal_webchat/message_handler.py`)
- Q web chat → Message operations: stores message (evidence: `plugins/q_vernal_webchat/message_handler.py`)
- Q web chat → Queue operations: queues message (evidence: `plugins/q_vernal_webchat/message_handler.py`)
- Q web chat → Active turns: uses (evidence: `plugins/q_vernal_webchat/message_handler.py`)
- Queue processor → Message operations: reads and updates (evidence: `runtime/core/queue.py`)
- Queue processor → Queue operations: dequeues (evidence: `runtime/core/queue.py`)
- Queue processor → User operations: reads users (evidence: `runtime/core/queue.py`)
- Queue processor → Active turns: uses (evidence: `runtime/core/queue.py`)
- Queue processor → Letta client: uses (evidence: `runtime/core/queue.py`)
- Agent processing → Letta client: calls (evidence: `runtime/core/agent.py`)
- Agent processing → Active turns: uses
- Letta client → Letta service: calls API (evidence: `runtime/core/letta_client.py`)
- User operations → Letta client: creates identities (evidence: `database/operations/users.py`)
- Message operations → Connection pool: uses connections (evidence: `database/operations/messages.py`)
- Queue operations → Connection pool: uses connections (evidence: `database/operations/queue.py`)
- User operations → Connection pool: uses connections (evidence: `database/operations/users.py`)
- Message operations → Database models: uses models (evidence: `database/operations/messages.py`)
- Queue operations → Database models: uses models (evidence: `database/operations/queue.py`)
- User operations → Database models: uses models (evidence: `database/operations/users.py`)
- Connection pool → SQLite database: opens connections
- Admin CLI → Queue operations: manages queue
- Admin CLI → User operations: manages users
