Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
🎯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.