Carolopedia

A public encyclopedia of Carolverse.

๐Ÿ“– Carolopedia โ€บ Guides โ€บ Migration architectureGuide page

Migration architecture

The operating runbook is not published.

๐Ÿ“–Summary

The Migration service is built following the [agent-centric modular architecture](/dev/carolopedia/wiki/architecture) of Carolverse. It leverages agile principles to migrate an existing external project into Carol-compliant modular shape using distinct agent identities, each carrying out a specific stage of the Extract โ†’ Audit โ†’ Refactor pipeline.

๐Ÿ“–Functional considerations

This is the on-ramp for outside code into Carolverse, so its architecture is shaped by what it must guarantee end-to-end:

- **Registration before work.** A migration is never started without an explicit git URL; [Noah](/dev/carolopedia/wiki/agent/agt-031)'s pipeline only touches a source that the user has named, slugged, and pointed at a real repo. - **Reproducible workspace.** Each migration clones into its own isolated working directory on the VM, so the source under change is pinned and the pipeline reruns deterministically. - **A staged, observable pipeline.** Extract โ†’ Audit โ†’ Refactor runs as ordered stages with a recorded `current_stage`, so status is a pure function of how far the project has progressed. - **Hand-off, not lock-in.** When Refactor completes, the service stops at a roadmap rather than silently shipping changes โ€” Leo synthesises the plan and files initiatives for another team to execute. - **Subscription-scoped.** The service is external/revenue, so access is gated to subscribed users and surfaced through the subscribed-services listing.

๐Ÿ“–Solution architecture

The service is a **staged pipeline** โ€” register โ†’ clone โ†’ Extract โ†’ Audit โ†’ Refactor โ†’ roadmap โ€” wired together by a small control plane. It is a direct instance of Carolverse's [agent-centric modular architecture](/dev/carolopedia/wiki/architecture): each stage is owned by an agent and carried out by that agent's droids (see the service's team above).

- **A single intake call.** Carol calls `register_migration`, which creates the migrations row and auto-clones the source โ€” one entry point, so every migration starts the same way. - **An owned pipeline.** [Noah](/dev/carolopedia/wiki/agent/agt-031) owns the Extract โ†’ Audit โ†’ Refactor stages; [Gimli](/dev/carolopedia/wiki/agent/agt-032) and [Thorin](/dev/carolopedia/wiki/agent/agt-033) support the pipeline and the roadmap surface. - **Roadmap synthesis as the terminal stage.** When Refactor finishes, Leo (Head of Strategy) reads the refactor outputs and synthesises the migration roadmap. - **A clean hand-off to the builder.** Leo files initiatives through his Initiative Filer into the [Build Initiatives](/dev/carolopedia/wiki/service/build-initiatives) service, where Elrond's team ships them โ€” migration plans, Build Initiatives executes.

๐Ÿ“–Technologies

- **Python 3** service on **FastAPI** / **Flask**, served by **uvicorn/gunicorn** behind **nginx**. - **SQLite (WAL)** datastore โ€” a `migrations` table holds one row per registered migration with its stage and timestamps. - The AI stages โ€” Extract, Audit and Refactor reason over the source โ€” run on the service's own lane, read from the registry when this page renders: **{{service_lane}}**. - **systemd** / **cron** schedule the recurring pipeline droids that advance a migration through its stages. - The **registry** and the **design store** are the binding sources of truth that define what "Carol-compliant modular shape" means and that the synthesised roadmap is measured against.

๐Ÿ“–Design principles

- **Single source of truth.** "Carol-compliant modular shape" is defined by the live registry and design store, never hand-copied โ€” the shared principle described on the [Carolverse Architecture](/dev/carolopedia/wiki/architecture) page. - **Agent-centric modular architecture.** Every pipeline stage has an accountable agent and a doing droid. - **Plan, then build elsewhere.** The service produces a roadmap and hands execution to [Build Initiatives](/dev/carolopedia/wiki/service/build-initiatives) rather than shipping changes itself. - **Explicit consent before action.** No migration begins without a user-supplied git URL. - **Observability first.** A migration's stage is always queryable, so progress is never a guess.

๐Ÿ“–Success criteria

- A subscribed user can register a migration and have the source auto-cloned without operator help. - Each migration moves through **Extract โ†’ Audit โ†’ Refactor** with a queryable `current_stage` at every point. - On Refactor completion, **Leo produces a roadmap** and files initiatives into Build Initiatives for Elrond's team. - **No migration starts without an explicit git URL.**
- Status (`get_migration_status`) always reflects the true stage, last-touched time, and counts.

๐Ÿ“–Policies

- **Never register a migration without an explicit git URL** supplied by the user. - **Subscription-gated.** Only subscribed users may invoke the service; access is surfaced through the subscribed-services listing. - **The service plans, it does not ship.** Execution of the roadmap routes through Build Initiatives and Elrond's team โ€” migration droids do not directly land changes. - **Every stage is tagged to an agent and its droid** โ€” Extract, Audit, and Refactor are owned, not anonymous. - **Roadmap initiatives are filed through Leo's Initiative Filer**, not hand-inserted.

๐Ÿ“–What it delivers today

- Register an existing project for migration and auto-clone its source repo โ€” [Noah](/dev/carolopedia/wiki/agent/agt-031), via `register_migration`. - Run the **Extract โ†’ Audit โ†’ Refactor** pipeline over the cloned source โ€” [Noah](/dev/carolopedia/wiki/agent/agt-031) with [Gimli](/dev/carolopedia/wiki/agent/agt-032) and [Thorin](/dev/carolopedia/wiki/agent/agt-033) supporting. - A **Migration Roadmap** surface at `/dev/migration/` to watch a migration's progress โ€” [Thorin](/dev/carolopedia/wiki/agent/agt-033). - Roadmap synthesis on Refactor completion plus initiative filing into Build Initiatives โ€” Leo via his *Initiative Filer*. - Query a migration's current stage, last-touched time, and counts โ€” via `get_migration_status`. - **The handover Migration owns (design 587, cookbook 1476)** โ€” H2: hands Blueprint the graded as-is (extracted requirements with evidence, findings citing standards) and the proposal placing every capability, as the migration row at *handoff* โ€” the flip that wakes Leo. A stage with no rows fails; a refusal is never a result.

๐Ÿ“–What it will deliver

- Per-stage progress and diffs on the Migration Roadmap, not just the current stage. - Multi-language Extract/Audit coverage beyond the primary source language captured at registration. - Automatic re-scan when the source repo changes upstream. - Tighter feedback from shipped Build Initiatives back into the roadmap, so a migration shows what has actually landed.

Source: Services Catalogue ยท Public information reflected here.