📖Summary

The WhatsApp Assistant service is built following the [agent-centric modular architecture](/dev/carolopedia/wiki/architecture) of Carolverse. It leverages agile principles to build and run software using distinct agent identities, each carrying out a specific activity. It is the conversational front door of Carolverse: Carol on WhatsApp, where a user chats in plain language to get things done, hands off tasks, and reaches every other service — and it also runs the infrastructure that keeps that assistant live.

📖Functional considerations

This is the user-facing surface of Carolverse and the layer everything else runs on, so its architecture must guarantee:

- **One conversational entry point.** A user reaches every other service through natural chat, without knowing which service or agent does the work.
- **Natural-prose replies only.** WhatsApp outbound must read like ordinary conversation — structured or transactional-looking messages (bracket tags, field rows, admin-command bodies) are silently dropped by Meta's classifier even when the API accepts them. Formatting must never leak into a reply.
- **Reliable task hand-off.** A request stated in chat is turned into the right action on the right downstream service and the outcome is reported back in the same thread.
- **Always-on plumbing.** The machines, networking and uptime that keep the assistant reachable are part of this service (it absorbed the former Infrastructure service), so liveness is a first-class concern, not an afterthought.
- **Still being built.** This is a work-in-progress service; the conversational and infrastructure layers exist, but the blocks, droids and agent-facing tools are not yet modelled in the registry.

📖Solution architecture

The service is the **conversational control plane** of Carolverse and a direct instance of its [agent-centric modular architecture](/dev/carolopedia/wiki/architecture): work is owned by [Galadriel](/dev/carolopedia/wiki/agent/agt-013) and carried out with support from [Guardian](/dev/carolopedia/wiki/agent/agt-014), [Jarvis](/dev/carolopedia/wiki/agent/agt-017) and [Sentinel](/dev/carolopedia/wiki/agent/agt-027) (see the service's team above).

- **Inbound understanding.** A chat message is parsed for intent, then routed to the downstream service that owns the capability.
- **A single outbound voice.** Every reply leaves through one path that enforces natural prose, so Meta's classifier never drops a message.
- **A router, not a doer.** For most requests this service hands the task to another service and relays the result — it is the front door, not the worker.
- **Infrastructure underneath.** The same service owns the machines, networking and uptime that keep the assistant reachable — the responsibilities absorbed from the former Infrastructure service.

The block-level decomposition is not yet modelled in the registry; this is a `wip` service.

📖Technologies

Grounded in the shared Carolverse stack; only the parts that apply here:

- **Python 3** services on **FastAPI** / **Flask** behind **nginx** handle the WhatsApp webhook and outbound send path.
- **SQLite (WAL)** datastores hold conversation and task state; the **registry** and **design store** are the binding sources of truth.
- Understanding the user and composing the natural-prose reply runs on Carol's chat lane, read from the registry when this page renders: **{{chat_lane}}**. Cookbook 1077 puts every chat session on the chat lane and lets that lane outrank any per-worker pin.
- **systemd** / **cron** keep the assistant and its infrastructure watchers running.
- **Meta WhatsApp Business** messaging is the channel — with the documented constraint that its content classifier drops anything that looks structured or transactional.

📖Design principles

- **Natural prose is the contract.** Outbound stays conversational; structure never leaks into a WhatsApp reply.
- **One front door.** The user speaks to one assistant and reaches the whole of Carolverse through it.
- **Route, don't reimplement.** Hand work to the owning service rather than duplicate it here.
- **Single source of truth.** State and identity come from the live registry and design store — the shared principle on the [Carolverse Architecture](/dev/carolopedia/wiki/architecture) page.
- **Agent-centric modular architecture.** Each responsibility has an accountable agent.
- **Liveness is a feature.** Because this service also runs the infrastructure, staying reachable is part of the product, not a side concern.

📖Success criteria

- A user can **get things done by chat alone** — state a need in plain language and reach any other service.
- **No dropped replies** — every outbound message reads as natural prose and is delivered, never silently rejected by Meta's classifier.
- **Tasks hand off cleanly** — a chat request reaches the right service and its outcome is reported back in the same thread.
- **The assistant stays reachable** — the machines, networking and uptime behind it hold up.

📖Policies

- **WhatsApp outbound must be natural prose.** No bracket tags, field-row layouts or admin-command bodies — Meta's classifier drops them even when the API returns a message id.
- **Route through the owning service.** Downstream work is handed to the service that owns it, not reimplemented in the chat layer.
- **Owner equals the accountable agent**, and the owner is an agent id, never a human.
- **Sources of truth are read, not hand-edited** — identity and state come from the registry and design store.
- General Carolverse governance applies; changes ship via the project's planner or an approved bypass, which skips the planner but not the standards.

📖What it delivers today

- A conversational WhatsApp front door where users chat in plain language — owned by [Galadriel](/dev/carolopedia/wiki/agent/agt-013).
- Task hand-off and result relay to the other Carolverse services from inside one chat thread.
- A natural-prose outbound path that keeps replies within Meta's content rules.
- The infrastructure — machines, networking and uptime — that keeps the assistant live, supported by Guardian, Jarvis and Sentinel.

*(Blocks and named droids for this service are not yet modelled in the registry.)*

📖What it will deliver

- Model the service's **blocks and droids** in the registry so the conversational and infrastructure layers are observable like other services.
- A **per-intent router** that maps chat requests to downstream services more explicitly.
- **Agent-facing tools** for the assistant (none are registered yet).
- Tighter **uptime monitoring** of the assistant's own infrastructure, surfaced on a monitor.