📖Summary

The System Services service is built following the [agent-centric modular architecture](/dev/carolopedia/wiki/architecture) of Carolverse. It is the shared internal platform — roughly 47 reusable code building blocks (the AI phone line, the WhatsApp post office, the registry readers, the bypass engine, the watchers) that every agent and droid calls in-process instead of reinventing them, owned and tended by [Radagast](/dev/carolopedia/wiki/agent/agt-029).

📖Functional considerations

This is the DRY backbone of Carolverse — almost every other service imports it — so its architecture is shaped by what shared code must guarantee:

- **One implementation, many callers.** A capability lives in exactly one place; agents and droids reuse it rather than each writing their own copy that can drift.
- **Called in-process, not over the wire.** These building blocks have no agent-facing tools or endpoints of their own; they are imported and invoked by the services that own a user-facing surface, so they must be stable and side-effect-honest.
- **Stable contracts.** Because a change here ripples to every caller, the surfaces (function signatures, the registry/design readers) must stay backward-compatible or migrate every caller together.
- **Correct under concurrency.** Shared readers and writers are hit by many droids at once, so access to the SQLite (WAL) stores stays single-writer-safe.
- **Five legible categories.** The ~47 services are grouped into five broad categories, each its own block with its own page, so a developer can find the right building block instead of duplicating one.

📖Solution architecture

System Services is a **shared library**, not a pipeline: a set of reusable modules grouped into five broad categories (each a block with its own page — see the service page above). It is a direct instance of Carolverse's [agent-centric modular architecture](/dev/carolopedia/wiki/architecture), but inverted — instead of exposing tools to users, every building block is **called in-process** by the agent/droid that owns a user-facing surface.

- **Single implementation per capability.** Each category (the AI phone line, the WhatsApp post office, the registry readers, the bypass engine, the watchers) is the one place that capability lives.
- **Readers over the sources of truth.** The registry and design-store readers are the sanctioned way every caller reads org state, so counts and narratives stay consistent.
- **Accountable ownership.** [Radagast](/dev/carolopedia/wiki/agent/agt-029) owns the platform; each block is maintained as a unit, and changes propagate to all callers together.

📖Technologies

- **Python 3** modules imported in-process by other Carol services running on **FastAPI** / **Flask** behind **nginx**.
- **SQLite (WAL)** datastores; the shared readers front the **registry** and the **design store**, the two binding sources of truth.
- **systemd** and **cron** schedule the watcher services so the building blocks that must run on a timer are observable.
- The AI building blocks, such as the AI phone line, run on the service's own lane, read from the registry when this page renders: **{{service_lane}}**.
- **Git** holds the shared code under change.

📖Design principles

- **Don't repeat yourself.** A capability is written once and reused, never re-implemented per caller.
- **Single source of truth.** The registry and design-store readers are the only sanctioned path to org state — the shared principle on the [Carolverse Architecture](/dev/carolopedia/wiki/architecture) page.
- **Stable, backward-compatible contracts.** A shared surface changes only with all callers migrated together.
- **Agent-centric modular architecture.** The platform has an accountable owner; each building block is a maintained unit.
- **Observability first.** The watcher building blocks run on a timer and surface their state rather than running silently.

📖Success criteria

- A common capability is implemented **exactly once** and reused, with no drifting copies across services.
- Callers read org state **only** through the shared registry/design readers, so counts and narratives agree everywhere.
- A change to a shared building block lands **without breaking its callers** — contracts stay compatible or migrate together.
- The shared SQLite stores stay **write-safe under concurrent droids**.
- Every building block has a **clear owning category** and page, so developers reuse rather than duplicate.

📖Policies

- **Reuse, don't reinvent.** A capability that belongs here must live here and be imported, not copied into a caller.
- **No agent-facing tools of its own.** The building blocks are called in-process; they do not expose their own endpoints or user surfaces.
- **Changes route through the owner.** [Radagast](/dev/carolopedia/wiki/agent/agt-029) owns the platform; shared-contract changes are accountable to that owner.
- **Bypass skips the planner, not the standards** — a change to shared code still follows the template checklist, review and observability of an autonomous run.
- **Read state through the sanctioned readers**, never by hand-querying the underlying stores.

📖What it delivers today

- The **AI phone line** — the shared building block for Carol's voice/phone capability, backed by the service's own lane: **{{service_lane}}**.
- The **WhatsApp post office** — the shared send/receive plumbing every messaging service reuses.
- The **registry readers** and design-store readers — the sanctioned in-process way to read the two sources of truth.
- The **bypass engine** — the shared machinery that runs an operator-driven (bypass) change through the same standards as an autonomous one.
- The **watchers** — the shared, scheduled monitoring building blocks.
- All ~47 services grouped into **five broad categories**, each a block with its own page, owned by [Radagast](/dev/carolopedia/wiki/agent/agt-029).

📖What it will deliver

- Consolidate any remaining duplicated helpers across services into the shared library so there is one implementation per capability.
- Publish clearer per-category contracts and versioning so callers can depend on stable surfaces.
- Broaden observability of the watcher building blocks so each scheduled run is auditable.