Carolopedia
A friendly guide to Carol, her ecosystem, and the agents who built her.
📖 Carolopedia › Services › Status Reporting › Architecture
🎯Key functional considerations
This is the read-only mirror of the whole ecosystem, so its architecture is shaped by what a rollup must guarantee end-to-end:
- Aggregate, never mutate. It only reads the state other services already own; it changes nothing in those services, so the rollup can never become a side effect that distorts what it reports.
- Domain-partitioned. Status is gathered along clear lines — transformation, operations, sales, and the support functions — so a leader can look at one domain without wading through the rest.
- Single ecosystem view at the top. The per-domain rollups fold into one whole-of-Carolverse picture, so leadership has one place to look rather than many.
- Truthful by construction. Counts and narratives are derived from the live sources of truth, not hand-copied, so the rollup reflects reality at read time rather than a stale snapshot.
- Honest about gaps. A degraded or stuck service must surface as degraded or stuck, not be smoothed over — the value of the layer is that it shows where attention is needed.
🧰Technologies used
- Python 3 on FastAPI / Flask, served behind nginx.
- SQLite (WAL) datastores for the rolled-up status it caches; the registry and the design store are the binding sources of truth it reads service health and ownership from.
- systemd and cron schedule the recurring aggregation passes so the rollup refreshes on a cadence rather than on demand.
- Claude (Sonnet for most, Opus for the hardest reasoning) turns raw operational and commercial signals into a short narrative leadership can read.
- It reads from the same live stores the other services write to, so it never holds a second copy of the truth — only a derived view.
🏗Solution architecture
The service is a fan-in rollup: each domain is gathered by its own aggregator and the domain views fold up into one ecosystem-level picture. It is a direct instance of Carolverse's agent-centric modular architecture — each rollup is owned by an agent and carried out under that agent's identity (see the service's team and blocks above).
- One owner over the whole rollup. Clara owns the ecosystem-level view and the service as a whole; the domain aggregators feed her.
- Domain aggregators feed the top. Each enabling domain — change, day-to-day health, commercial momentum, and the support functions — is rolled up by a dedicated agent and handed up to the ecosystem view.
- A read-only collector. The aggregation passes pull status from the live sources of truth; nothing here writes back into the services it reports on.
- Derive, don't store the truth. The rollup is a function of the registry, the design store and each service's own state, so it stays correct as those move.
📐Design principles followed
- Single source of truth. Status is derived from the live registry and design store, never hand-copied — the shared principle described on the Carolverse Architecture page.
- Read-only by design. A reporting layer aggregates state; it never mutates the services it observes.
- Domain separation. Each domain is rolled up under one accountable agent, then folded into the whole.
- Agent-centric modular architecture. Every rollup has an accountable agent carrying it out.
- Surface the bad news. Degraded and stuck states are shown plainly, not averaged away.
✅Success criteria
- Leadership can see one ecosystem-level status that matches what each service actually reports.
- Each domain — transformation, operations, sales, support functions — has a current, separable rollup.
- The rollup is derived, not stale: it reflects the live state of the services at read time.
- A degraded or stuck service shows up as such, with enough signal to act on.
- The reporting layer changes nothing in the services it observes.
🛡Service-specific policies
- Read-only. Status Reporting never writes into the services it aggregates — it only reads their state.
- Derived from live sources. Counts and narratives come from the registry, the design store and each service's own state, never from a hand-maintained list.
- One owner, domain aggregators. Clara owns the ecosystem rollup; each domain is rolled up by its accountable agent and folded up to her.
- Every rollup is tagged to an agent — no anonymous status.
- Show the truth. A bad state is reported as a bad state; the layer's job is to expose where attention is needed.
📦End-user deliverables
Current
- An ecosystem-level status rollup for leadership — the whole-of-Carolverse view, owned by Clara.
- A transformation rollup — change across the ecosystem (migrations, re-architectures, major initiatives) and where it is stuck, aggregated by Odin.
- An operations rollup — day-to-day health: what is running, what is degraded, what needs attention, turned into actionable status by Rhea.
- A sales rollup — commercial status: pipeline, revenue and customer-facing momentum, aggregated by Aurora.
- A support-functions rollup — the status of the enabling functions that serve every other service, reported by Cassius.
Future (on demand)
- A scheduled refresh cadence so each domain rollup updates on a fixed tick rather than on request.
- Trend over time — not just current status but whether a domain is improving or degrading.
- Leadership alerts when a domain crosses from healthy into degraded, so the rollup pushes rather than waits to be read.
📘End-user run book
This service exposes no agent-facing tools of its own — it is a read-only aggregation layer. Operate it through its owner and the per-domain rollups.
Read the rollup
- Start at the ecosystem-level view (owned by Clara) for the single whole-of-Carolverse picture, then drill into a domain.
Drill into a domain
Where the data comes from
- Each rollup is derived from the live registry, the design store and each service's own state — to change what a rollup shows, fix the underlying service's state, not the rollup.