polylith-migrate-isolate-base-and-big-component

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_NS
• INITIAL_BASE_NAME
• Verification commands.

From migration/<PROJECT>/manifest.md:

• Entrypoints list.

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

• Update bases to import only from component APIs:

  from <TARGET_TOP_NS>.<INITIAL_BASE_NAME> import ...
  

5. Update pyproject.toml

• Add the new component to [tool.polylith.bricks]:

  [tool.polylith.bricks]
  "../../bases/<TARGET_TOP_NS>/<base>" = "<TARGET_TOP_NS>/<base>"
  "../../components/<TARGET_TOP_NS>/<INITIAL_BASE_NAME>" = "<TARGET_TOP_NS>/<INITIAL_BASE_NAME>"
  

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.

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.