| name | polylith-migrate-isolate-base-and-big-component |
| description | [Internal sub-skill of `polylith-migrate-orchestrator`. Do not load directly — load `polylith-migrate-orchestrator` first, which drives all phases.] Shrink the temporary migration base into thin base(s) + one big component. Bases contain only entrypoints/wiring, while the big component contains everything else. |
Skill: polylith-migrate-isolate-base-and-big-component
Goal
Shrink the temporary migration base into thin base(s) + one big component:
- Bases: Contain only entrypoints/wiring (e.g., FastAPI endpoints, CLI wiring, consumer wiring).
- Big Component: Contains all other code.
⚠ Base vs component naming (read first). A base and a component cannot share
the same brick name — both would resolve to the Python package <TARGET_TOP_NS>.<name>
and collide. So the big component takes INITIAL_BASE_NAME
(<TARGET_TOP_NS>.<INITIAL_BASE_NAME>) and each base is renamed to a distinct,
entrypoint-specific name (the <base> used in step 5 — e.g. <INITIAL_BASE_NAME>_api,
<INITIAL_BASE_NAME>_handler). This is why the temporary base must be renamed when
the component claims its name.
Multiple entrypoints → multiple thin bases. A real service often has several
deployable entrypoints (an HTTP API + one or more queue consumers + scheduled jobs).
Create one thin base per entrypoint (e.g. <x>_api, <x>_handler, <x>_jobs),
each exposing only its run/wiring function and importing logic from components. Do
not force them into a single base. (Shared startup wiring — init_db,
init_logging, … — goes into a small shared component, not duplicated per base; see
polylith-migrate-distribute-wiring.)
Inputs
From migration/<PROJECT>/state.md:
TARGET_TOP_NSINITIAL_BASE_NAME- Verification commands.
From migration/<PROJECT>/manifest.md:
All inputs from state.md are assumed to satisfy the validation rules in polylith-migrate-discover (### Validation rules). Validate before proceeding.
Steps
1. Create the Big Component
- Create
components/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>/.
- ⚠ If the temporary base currently occupies
bases/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>/, rename the base(s) first — they must not keep the same name as the big component (see the naming callout above). Create one renamed thin base per entrypoint (<base> in step 5), and update the project's run scripts / Dockerfile to point at the new base name(s).
2. Move Non-Entrypoint Code
- Move non-entrypoint code from the base(s) to the big component.
3. Define Public API
- Define a minimal public API in
components/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>/__init__.py.
4. Update Bases
5. Update pyproject.toml
6. Update manifest.md
- Reflect the new structure in
migration/<PROJECT>/manifest.md.
7. FastAPI Guidance
| Stays in Base | Moves to Big Component |
|---|
app = FastAPI(...) | Domain/business logic |
| Middleware, router registration | Persistence/repositories |
| Route handlers (endpoints) | External integrations |
| Startup/shutdown/lifespan wiring | Reusable parsing/validation |
Verify
RUN_TEST_CMD succeeds.- If set,
RUN_LINT_CMD and RUN_TYPECHECK_CMD succeed.
- Run
POLY_CMD_PREFIX check to validate the workspace structure.
- Run
POLY_CMD_PREFIX sync to synchronize the [tool.polylith.bricks] table with actual imports.
Common failure modes
| Symptom | Likely cause | Remediation |
|---|
| Circular import: base imports from component, component imports back from base | Some "non-entrypoint" code was moved but still references base-only helpers (e.g. the FastAPI app instance). | Move the helper down into the component, or invert the dependency by passing the needed value as a function argument. The base's app instance must never be imported by a component. |
poly check / import error: base and big component both named <INITIAL_BASE_NAME> | The base wasn't renamed when the component claimed INITIAL_BASE_NAME — two bricks now map to <TARGET_TOP_NS>.<INITIAL_BASE_NAME>. | Rename the base to an entrypoint-specific name (<INITIAL_BASE_NAME>_api, _handler, …), update [tool.polylith.bricks] and the run scripts, then POLY_CMD_PREFIX sync. |
ImportError: cannot import name '<x>' from '<TARGET_TOP_NS>.<INITIAL_BASE_NAME>' | The big component's __init__.py doesn't re-export <x>. Code that previously reached into submodules now needs the public API. | Add from <TARGET_TOP_NS>.<INITIAL_BASE_NAME>.<submodule> import <x> to the component's __init__.py, or have the caller import the submodule directly (and accept the brick-interface violation that poly deps --interface will flag). |
| Base file becomes near-empty after the split | Good — that's the goal. But check: is there any wiring left, or did you accidentally move the entrypoint itself? | If the entrypoint (e.g., app = FastAPI(...)) ended up in the component, move it back to the base. The base must own the entrypoint object. |
poly check flags the component as not used by any project | The base's imports go to the wrong namespace (e.g., from <ORIG_TOP_NS>...) so the import graph doesn't reach the component. | Update base imports to from <TARGET_TOP_NS>.<INITIAL_BASE_NAME> import … and re-run POLY_CMD_PREFIX sync. |
| Tests for moved code now fail to find fixtures | conftest.py was left in the base or moved to the wrong scope. | Move test fixtures alongside the code they cover; usually that's under test/components/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>/. |
| Verification fails and you can't quickly diagnose | Phase commit not yet made. | git reset --hard HEAD to roll back to the previous phase's commit and consult the user. |
Commit
After verification passes, commit this phase to the migration branch:
git add -A && git commit -m "migrate(<PROJECT>): phase <N> — isolate-base-and-big-component"
Substitute <PROJECT>, <N>, and <phase-name> from state.md and the orchestrator's phase table. Do not proceed to the next phase without a clean commit — the per-phase commit is the rollback point for the next phase's failure-mode tables.
