Architecture

Clawbolt is a FastAPI backend with a Telegram messaging interface and a custom tool-calling agent loop built on any-llm.

Request flow

Contractor sends a Telegram message
        |
        v
  Telegram webhook  -->  Media pipeline (photos, voice, docs)
        |                        |
        v                        v
  Agent loop (any-llm)  <--  Processed context
        |
        v
  Tool execution (memory, estimates, file upload)
        |
        v
  Reply sent via Telegram

1. Webhook: Telegram sends an update to /api/webhooks/telegram
2. Media pipeline: Photos, voice notes, and documents are downloaded and processed (transcription, image analysis)
3. Agent loop: The LLM receives the message plus conversation history and available tools, then decides what to do
4. Tool execution: The agent calls tools (save a fact, generate an estimate, upload a file, etc.)
5. Reply: The agent’s response is sent back via Telegram

Tech stack

• Python 3.11+ with FastAPI and async throughout
• SQLAlchemy 2.0 with mapped_column style and Pydantic v2 schemas
• any-llm for LLM provider abstraction (swap between OpenAI, Anthropic, etc.)
• python-telegram-bot for the Telegram Bot API
• faster-whisper for voice memo transcription
• ReportLab for PDF estimate generation
• PostgreSQL in production, in-memory SQLite for tests

Agent tools

The agent has access to these tool groups:

Tool group	Tools	Purpose
Memory	save_fact, recall_facts, forget_fact	Persistent key-value memory for pricing, clients, jobs
Messaging	send_reply, send_media_reply	Send text or media messages back to the contractor
Estimates	generate_estimate	Create professional PDF estimates with line items
Profile	view_profile, update_profile	View/update contractor profile
Checklist	add_checklist_item, list_checklist_items, remove_checklist_item	Reminder checklists
Files	upload_to_storage, organize_file	Store and organize files in cloud storage

Tool selection is context-aware: the registry picks relevant tools based on message keywords and context, with a fallback to all tools for ambiguous messages.

Key design patterns

Channel abstraction

The MessagingService protocol defines a channel-agnostic interface. The current implementation is Telegram, but the protocol enables adding other channels without modifying the agent loop.

Storage abstraction

The StorageBackend ABC allows swapping between local filesystem, Dropbox, and Google Drive. Each contractor’s files are organized in per-client folders.

Auth plugin infrastructure

Authentication uses a plugin system with an ABC base, dynamic import loader, and dependency injection. The open-source version is single-tenant. Premium adds multi-tenant auth via plugin.

Every model and endpoint uses user_id scoping from day one, so multi-tenancy is a configuration change rather than an architectural one.

Deterministic heartbeat

The heartbeat system separates cheap deterministic checks (database queries) from expensive LLM calls. LLM is only invoked when actionable flags are found, keeping costs low.

Data models

Model	Purpose
Contractor	User profile, heartbeat settings, relationships to all entities
Client	Client records (name, phone, email, address, notes)
Memory	Key-value facts with category and confidence
Conversation	Message thread per contractor
Message	Inbound/outbound text, media URLs, tool interactions
Estimate	Estimates with line items, PDF URL, lifecycle status
MediaFile	Processed media with storage URLs
HeartbeatChecklistItem	Scheduled reminder items