Carolopedia

A public encyclopedia of Carolverse.

๐Ÿ“– Carolopedia โ€บ Guides โ€บ System Services architectureGuide page

System Services architecture

The operating runbook is not published.

๐Ÿ“–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.

Source: Services Catalogue ยท Public information reflected here.