Carol — back to Apps ← Apps

Carolopedia

A friendly guide to Carol, her ecosystem, and the agents who built her.

📖 CarolopediaServicesWhatsApp AssistantArchitecture
WhatsApp Assistant

WhatsApp Assistant Architecture

Architecture The defined architecture of the WhatsApp Assistant service — eight standard sections.

🎯Key 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.

🧰Technologies used

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.
  • Claude (Sonnet for most turns, Opus for the hardest reasoning) drives understanding the user and composing the natural-prose reply.
  • 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.

🏗Solution architecture

The service is the conversational control plane of Carolverse and a direct instance of its agent-centric modular architecture: work is owned by Galadriel and carried out with support from Guardian, Jarvis and Sentinel (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.

📐Design principles followed

  • 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 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.

🛡Service-specific 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.

📦End-user deliverables

Current

  • A conversational WhatsApp front door where users chat in plain language — owned by Galadriel.
  • 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.)

Future (on demand)

  • 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.

📘End-user run book

This is a wip service with no agent-facing tools registered yet, so operation is via the owner and the chat channel.

Interact

  • Message Carol on WhatsApp in plain language; the assistant routes the request to the owning service and replies in the same thread.

Operate

  • The service runs as Python on FastAPI/Flask behind nginx, kept alive by systemd/cron; the WhatsApp webhook and outbound send path run here.
  • Outbound must be natural prose — when composing or debugging a reply, never emit bracket tags, field rows or admin-command bodies; they are dropped by Meta's classifier.

Owner path

  • Galadriel owns the service; Guardian, Jarvis and Sentinel support the assistant and its infrastructure. Take design or roadmap changes through the owner and the project's planner/bypass.