wetqv/snapmatch

Purpose and entry points

SnapMatch is a local desktop control plane for a Telegram AI bot. It combines bot operation, model routing, MCP tool use, voice transcription, persistent message history, and a secretary workflow. main.py is the application entry point; it starts the PyQt6 administration UI and bot/server lifecycle. Configuration is loaded from config/settings.py, with a user-created local config.json.

Desktop administration and lifecycle

The PyQt6 GUI is the primary operator interface, centered on gui/admin_dashboard.py and the modular admin panel under gui/admin_panel/. It exposes settings, user management, message history, voice settings, secretary controls, MCP configuration, and server start/stop control. gui/admin_panel/server_control.py forms the important boundary between UI actions and bot runtime state.

Telegram ingestion and command surface

Telegram updates enter through handler modules in bot/handlers/, separating commands, menus, regular messages, and stateful interactions:

• bot/handlers/command_handlers.py

• bot/handlers/message_handlers.py

• bot/handlers/menu_handlers.py

Handlers delegate rather than directly implementing model/database logic. Queue and active-task management (bot/handlers/queue_manager.py, bot/handlers/active_tasks_registry.py) protect the runtime from concurrent or long-running user requests.

AI request pipeline and model providers

The main response path is service-oriented: incoming text/media is normalized, context is assembled, a model request is built, and a selected configured model is invoked. Core stages are represented by:

• bot/handlers/services/message_processor.py

• bot/handlers/services/request_processor.py

• bot/handlers/services/model_request_builder.py

• bot/handlers/services/model_client_manager.py

Configured model backends include OpenAI-compatible endpoints, OpenRouter, Groq, and local compatible services. Prompt/context boundaries are managed in prompt_manager.py and context_manager.py, allowing user/history context to be isolated from provider-client behavior.

MCP tool integration

MCP is an explicit tool-execution subsystem rather than ad hoc model output handling. bot/handlers/services/mcp_registry.py registers/discovers servers and tools, mcp_runtime.py executes them, and mcp_permissions.py applies access controls. MCP configuration and persistence are surfaced through:

• bot/handlers/services/mcp_runtime.py

• bot/handlers/services/mcp_permissions.py

• utils/database/mcp_db.py

• gui/admin_panel/mcp_tab.py

The included examples/mcp/simple_snapmatch_mcp.py defines the expected external MCP-server integration model.

Secretary and deferred-response workflow

Secretary mode is a separate intake, debounce, queue-policy, and response pipeline for incoming communications. Its orchestration spans:

• bot/handlers/secretary_runtime.py

• bot/handlers/services/secretary_intake.py

• bot/handlers/services/secretary_queue_policy.py

• bot/handlers/services/secretary_response.py

This separates assistant-style direct replies from managed/deferred secretary processing, with durable secretary data in utils/database/secretary_db.py.

Persistence, media, and local services

All operational data is local: database access is centralized through utils/database/database_manager.py, with specialized stores for users, messages, MCP, and secretary state. utils/encryption.py protects sensitive local material. Voice handling in utils/voice_processor.py integrates Vosk, OpenAI Whisper, or Groq; packaged deployments may use FFmpeg. Image and rich Telegram output processing are isolated in bot/handlers/services/image_processor.py and rich_message_sender.py.

Packaging and deployment

The application is packaged as a desktop executable, not deployed as a hosted web service. PyInstaller uses snapmatch.spec; Windows installer construction uses SnapMatch_Installer.iss. Linux Debian packaging is driven by packaging/linux/build_deb.sh and release automation by .github/workflows/release-build.yml.