How sanctumos/broca works
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: telegram_bot/message_handler.py Telegram bot · users.py User operations · porter_vernal_webchat/message_handler.py Porter web chat · q_vernal_webchat/message_handler.py Q web chat
Components 28
Message runtime
- Application
main.py - Queue processor
runtime/core/queue.py - Agent processing
runtime/core/agent.py - Active turns
runtime/core/active_turn.py - Message model
runtime/core/message.py - Image handling
runtime/core/image_handling.py - Letta client
runtime/core/letta_client.py
Platform plugins
- Plugin manager
runtime/core/plugin.py - Plugin interface
plugins/__init__.py - Telegram bot
plugins/telegram_bot/message_handler.py - Porter web chat
plugins/porter_vernal_webchat/message_handler.py - Q web chat
plugins/q_vernal_webchat/message_handler.py
Persistence
- Connection pool
database/pool.py - Database models
database/models.py - Message operations
database/operations/messages.py - Queue operations
database/operations/queue.py - User operations
database/operations/users.py - SQLite database
Administration
- Admin CLI
cli/btool.py - Settings CLI
cli/settings.py
Shared services
- Configuration
common/config.py - Retry handling
common/retry.py
Other components
- Operator
- Telegram user
- Web chat user
- Letta service
- Telegram
- Web chat API
Connections 48
- Operator → Application: starts
README.md - Application → Plugin manager: initializes
main.py - Application → Queue processor: initializes
main.py - Application → Agent processing: initializes
main.py - Application → Connection pool: initializes
main.py - Plugin manager → Plugin interface: manages
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
README.md - Telegram → Telegram bot: delivers message
- Web chat user → Web chat API: sends message
README.md - Web chat API → Porter web chat: delivers message
- Web chat API → Q web chat: delivers message
- Telegram bot → Message model: uses
plugins/telegram_bot/message_handler.py - Telegram bot → Image handling: uses
plugins/telegram_bot/message_handler.py - Telegram bot → User operations: gets profile
plugins/telegram_bot/message_handler.py - Telegram bot → Message operations: stores message
plugins/telegram_bot/message_handler.py - Telegram bot → Queue operations: queues message
plugins/telegram_bot/message_handler.py - Telegram bot → Agent processing: uses
plugins/telegram_bot/message_handler.py - Porter web chat → Message model: uses
plugins/porter_vernal_webchat/message_handler.py - Porter web chat → User operations: gets profile
plugins/porter_vernal_webchat/message_handler.py - Porter web chat → Message operations: stores message
plugins/porter_vernal_webchat/message_handler.py - Porter web chat → Queue operations: queues message
plugins/porter_vernal_webchat/message_handler.py - Porter web chat → Agent processing: uses
plugins/porter_vernal_webchat/message_handler.py - Q web chat → Message model: uses
plugins/q_vernal_webchat/message_handler.py - Q web chat → User operations: gets profile
plugins/q_vernal_webchat/message_handler.py - Q web chat → Message operations: stores message
plugins/q_vernal_webchat/message_handler.py - Q web chat → Queue operations: queues message
plugins/q_vernal_webchat/message_handler.py - Q web chat → Active turns: uses
plugins/q_vernal_webchat/message_handler.py - Queue processor → Message operations: reads and updates
runtime/core/queue.py - Queue processor → Queue operations: dequeues
runtime/core/queue.py - Queue processor → User operations: reads users
runtime/core/queue.py - Queue processor → Active turns: uses
runtime/core/queue.py - Queue processor → Letta client: uses
runtime/core/queue.py - Agent processing → Letta client: calls
runtime/core/agent.py - Agent processing → Active turns: uses
- Letta client → Letta service: calls API
runtime/core/letta_client.py - User operations → Letta client: creates identities
database/operations/users.py - Message operations → Connection pool: uses connections
database/operations/messages.py - Queue operations → Connection pool: uses connections
database/operations/queue.py - User operations → Connection pool: uses connections
database/operations/users.py - Message operations → Database models: uses models
database/operations/messages.py - Queue operations → Database models: uses models
database/operations/queue.py - User operations → Database models: uses models
database/operations/users.py - Connection pool → SQLite database: opens connections
- Admin CLI → Queue operations: manages queue
- Admin CLI → User operations: manages users