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'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.

• 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.
• Git clones the source repo into a per-migration working directory under /home/caroladmin/dev/migrations/<slug>/.
• Claude drives the AI stages — Extract, Audit, and Refactor reason over the source; Sonnet for most work, Opus for the hardest analysis.
• 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.

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: 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 owns the Extract → Audit → Refactor stages; Gimli and Thorin 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 service, where Elrond's team ships them — migration plans, Build Initiatives executes.

• 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 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 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.

• 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.

• 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.

Current

• Register an existing project for migration and auto-clone its source repo — Noah, via register_migration.
• Run the Extract → Audit → Refactor pipeline over the cloned source — Noah with Gimli and Thorin supporting.
• A Migration Roadmap surface at /dev/migration/ to watch a migration's progress — Thorin.
• 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.

Future (on demand)

• 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.

Agent-facing tools

• register_migration — register a new migration (name, slug, git URL, target Carol version, source language); creates the migrations row and auto-clones the source.
• get_migration_status — given a slug, return the migration's current stage, last-touched time, and counts.
• list_my_subscribed_services — list the services the user is subscribed to, so the user can confirm Migration access.

Register a migration

1. Gather a short name, a lowercase no-space slug, the source git URL, the target Carol version (default current), and the primary source language(s).
2. Call register_migration with them — the row is created and the repo is cloned into /home/caroladmin/dev/migrations/<slug>/.
3. Confirm to the user and point them at Thorin's Migration Roadmap at /dev/migration/ to watch progress.

Track and hand off

• Call get_migration_status(slug) to see the current stage.
• When Refactor completes, Leo synthesises the roadmap and files initiatives for Elrond's team — follow those in the Build Initiatives service.