6.5 KiB
Messaging Service boundary and transport design
Status: Approved
Revision: 1
Date: 2026-09-19
Beads issue: archie-core-8cda.6.1
Parent: service-decomposition.md
Prerequisites: Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)
This document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behaviour, channel invariants, and deletion criteria required by archie-core-8cda.6 and its child tasks.
Decision
The Messaging Service (cmd/archie-messaging, composed via internal/app/archiemessaging) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via messaging.ChatContract.
It is a peer service to the UI Service and the daemon:
- It serves external chat participants across configured communication platforms.
- It consumes Gateway's
messaging.ChatContractexclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions. - It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.
Boundary and Ownership
| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |
|---|---|---|---|
| Channel transports | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway ChatContract |
Direct LLM providers, model runtimes, tokenizer libraries |
| Turn dispatch | Inbound message packaging, typing indicators, live streaming updates | ChatContract.Route, ChatContract.Stream |
gateway.Router, runtime.Runtime, agent prompt builders |
| Sessions & History | Platform-to-session key mapping, conversation thread ID translation | ChatContract.GetSession, RecentMessages, RecentTurns |
store implementations, SessionStore database handles |
| Control & Actions | Platform command parsing (/status, /tasks, /cancel, /stop, /persona) |
ChatContract.Snapshot, ApplyTaskAction, Cancel, SetPersona |
daemon.Daemon, workflow execution engine, worktree operations |
| Task Approvals | Channel interactive keyboards, approval callbacks | ChatContract.ApplyTaskAction |
Direct task status mutations, forge comment posters |
| Configuration | Platform bot tokens, allowed sender/user IDs, webhook listen ports | [chat.*] channel configs, Gateway target/token |
config.Holder, forge tokens, repo configs, agent container specs |
| Readiness | Messaging process liveness, channel connectivity, Gateway probe | Gateway ChatContract.Snapshot |
Internal daemon subsystem probes |
Target Service Shape
- Binary entry point:
cmd/archie-messaging/main.goparses CLI flags (-config,-config-overlay,-gateway-target,-gateway-token) and hands execution tointernal/app/archiemessaging.Run. - Application composition:
internal/app/archiemessaging/wires:- Config loading scoped strictly to
[chat.*]and[services.gateway]. - Secret resolution for channel credentials (e.g. Telegram bot token).
- Gateway gRPC client (
internal/infrastructure/gatewayrpc.Client). - Channel lifecycle managers (
internal/channels/status). - Channel instances (
internal/channels/telegram,email,webhook).
- Config loading scoped strictly to
- Turn and Stream Execution:
- Channels adapt inbound platform messages to
messaging.Inbound. - Streaming channels (Telegram) consume
ChatContract.Stream(ctx, inbound)which returns<-chan messaging.ChatEvent, mappingstarted,delta,tool,media,done, anderrorevents directly to live message frames. - Non-streaming channels (email, synchronous webhooks) consume
ChatContract.Route(ctx, inbound).
- Channels adapt inbound platform messages to
Load-Bearing Channel Invariants
The Messaging Service preserves existing invariants defined in AGENTS.md and channel documentation:
- Telegram long-polling: Must call
dropPendingUpdates(ctx, b)beforeb.Start(ctx)and on/restart. - Telegram command menus: Must register command menus simultaneously to
default,all_private_chats, andall_group_chatsviacommands.goto prevent menu shadowing. - No UI detour: Turns and task actions route directly to Gateway's
ChatContract; no HTTP request may ever be sent toarchie-uiorinternal/webui. - Sender Confinement: Telegram sender checks against
allowed_user_idsmust continue to fail closed before initiating any turn dispatch.
Configuration Ownership
cmd/archie-messaging reads only:
[services.gateway].targetand[services.gateway].target_token(or CLI flags).[chat.telegram](token, allowed user IDs).[chat.email](IMAP/SMTP host, ports, credentials).[chat.webhook](listen address, secret).[secrets](for resolving token secret references).
It does not read or decode [forge], [repos], [models], [providers], [runners], [containers], or [nats].
Deletion Gate and Verification
The extraction is guarded by cmd/archie-messaging/architecture_test.go, verifying that go list -deps ./cmd/archie-messaging links zero banned runtime packages:
modernc.org/sqlite,github.com/jackc/pgx,internal/infrastructure/postgresandinternal/infrastructure/legacyread(State Store)internal/daemon,internal/app/archied,internal/container,internal/worktree(Daemon runtime)internal/domain/workflow,internal/agentexec,internal/taskrun(Workflow engine)internal/forge,internal/forgerpc(Forge client)internal/gatewayruntime (onlyinternal/domain/messagingandinternal/infrastructure/gatewayrpcare permitted)internal/webui(Dashboard)