duckbugio/flock

1. Monorepo split into platform-agnostic core and channel adapters.

The central architecture is in core/, which contains the Claude-driven agent orchestration, workspace management, polling, git/PR integration, voice handling, and shared chat logic. adapters/telegram/ and adapters/vk/ are thin transport-specific front ends that translate a chat platform’s events into the core’s internal chat/service model. The repo is set up so new transports can be added under adapters/<name>/ without changing the core.

2. Two runnable bot entrypoints.

cmd/flock-telegram and cmd/duck-vk are the deployable binaries. Each wires configuration, the adapter, and the shared core together. The Telegram path is the primary product and is packaged with Docker, Compose, and Ansible deployment assets under adapters/telegram/deploy/.

3. Core control plane: chat service plus orchestration pipeline.

core/chat/ is the main request lifecycle: it accepts incoming chat events, applies guardrails, manages the outbox/progress/nudge behavior, chunks and routes messages, and coordinates agent work. core/dispatch/ and core/poller/ drive event routing and background polling loops, while core/session/ keeps per-chat state. This is the boundary where a human message becomes either a normal answer or a multi-step development run.

4. Claude Code execution is isolated behind a dedicated runner layer.

core/claude/ wraps the Claude Code CLI, including streaming/tailing, JSONL decoding, MCP support, and tests with fake transcripts. This layer is the bridge from orchestration into actual model execution. The README’s “Claude dev team” is implemented as subagents in core/agents/, with the pipeline roles planner → coder → tester → reviewer → arbiter.

5. Per-chat workspace isolation is a first-class subsystem.

core/workspace/ creates and manages isolated directories per chat, matching the repo’s model of /workspace/chat_<id>. The bot uses these workspaces to ensure that different chats cannot see each other’s files and can run in parallel up to a concurrency limit. core/gitsetup/ complements this by preparing repos/branches for agent work and PR creation.

6. Transport adapters focus on message shape, rich content, and platform-specific constraints.

adapters/telegram/ contains Telegram-specific command handling, message formatting, rich text transport, upload/voice helpers, and the bot bootstrap. adapters/vk/ contains the equivalent VK logic: long polling, API calls, mention detection, payload handling, and media upload. The core chat layer stays transport-neutral; each adapter maps platform events into the core and maps responses back into the platform’s formatting rules.

7. Media and voice are separate processing paths, not just text extensions.

core/voice/ handles transcription and voice-provider abstraction, with adapters/telegram/voice.go and adapters/vk/voice.go integrating platform uploads/attachments. This means voice messages enter the system through a dedicated decode/transcribe path before they become normal chat commands or prompts. The README notes multiple providers, including remote APIs and local mode.

8. Git host integration is asynchronous and poll-based.

The system supports Gitea/GitHub/GitLab-style flows through core/ghstar/, core/poller/, and likely the git-related utilities around the bot’s run lifecycle. A key design choice is that PR review comments are handled by outbound polling instead of inbound webhooks, so the bot can operate even when the git host cannot reach it. This matches the architecture’s “chat triggers work, poller closes the loop” model.

9. Guardrails and cost/rate controls sit inside the core, not the adapter.

core/ratelimit/, core/cost/, core/pending/, core/nudge/, and core/chat/guards.go enforce safety, throttling, and run bookkeeping. These are the boundaries that keep the agent from looping forever, spamming replies, or running uncontrolled. The arbiter role in the team is the semantic loop-breaker; these packages are the operational guardrails.

10. Shared internal utilities support safe file and config handling.

internal/atomicfile/ provides atomic writes, internal/fsutil/ handles upload/file utilities, and internal/config/ centralizes environment/config parsing. These are low-level support packages used across the bot and deployment paths to keep state changes safe and consistent.

11. Deployment is image-first, with optional orchestration sidecars.

The Telegram adapter ships with its own Dockerfile, docker-compose.yml, and Ansible role/playbook templates. The default deployment runs as a prebuilt container, with optional sidecars for Docker-in-Docker CI tooling and Caddy for webhook/TLS ingress. This makes runtime packaging part of the adapter boundary rather than the core application logic.

12. Testing is broad and component-level.

Most subsystems have focused unit tests beside the code, and core/claude/ includes integration-style fixtures for CLI transcript decoding. That suggests the architecture is built around deterministic orchestration and adapter translation, with tests validating message routing, workspace behavior, and external integration wrappers rather than only end-to-end bot runs.

13. Conceptual data flow for diagramming.

A user message enters a transport adapter, is normalized into a core chat event, passes through session/guard/rate-limit logic, and is either answered directly or routed into the Claude team pipeline. If it becomes a development task, the core creates/uses an isolated workspace, runs Claude Code subagents, writes files, tests, and git operations, then posts progress back through the adapter. Background pollers later bring PR review comments back into the originating chat.

14. Primary architectural boundaries to draw.

The most important boundaries are: transport vs. core, chat orchestration vs. Claude execution, per-chat workspace isolation vs. shared deployment secrets, and synchronous chat handling vs. asynchronous polling/background reconciliation. These are the lines that define how the system stays multi-tenant, multi-transport, and safe to run on one server.