# Migration Assistant

## Package docs status

This page is generated from public package documentation in `capell-4/packages` and the package manifest checked into the source repository.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/migration-assistant` |
| Package slug | `migration-assistant` |
| Product group | Capell Operations |
| Tier | premium |
| Bundle | `operations` |
| Runtime contexts | `admin`, `console` |
| Capell version | `^4.0` |
| Source repository | `capell-app/packages` |
| Source path | `packages/migration-assistant` |
| Docs source | `packages/migration-assistant/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/4.x/packages/migration-assistant/capell.json) |

MigrationAssistant export, import, and rollback report workflows for Capell.

## At A Glance

- Package: `capell-app/migration-assistant`
- Namespace: `Capell\MigrationAssistant\`
- Surfaces: Filament admin, queue, database
- Service providers: `packages/migration-assistant/src/Providers/MigrationAssistantServiceProvider.php`
- Capell dependencies: `capell-app/admin`, `capell-app/core`
- Third-party dependencies: `lorisleiva/laravel-actions`, `spatie/laravel-package-tools`

## Why It Helps Your Capell Workflow

- Provides import workflows, source readers, mapping, preview, validation, execution state, and rollback reports for content moves.
- Helps owners de-risk migrations by showing what will change before import and what changed afterwards.
- Gives developers extension points for sources, targets, relations, row contributors, collision detection, and rollback behavior.

## Best Used With

- [WordPress Importer](../wordpress-importer/README.md)
- [Media Library](../media-library/README.md)
- [Diagnostics](../diagnostics/README.md)

## What It Adds

- MigrationAssistant export, import, and rollback report workflows for Capell.
- Admin resources: `ImportSessionResource`.
- Recovery Center page import workflow: upload, review, resolve relations, validate, queue execution, and inspect rollback evidence.

## Why It Matters

**For developers:** Separates migration work into services, actions, DTOs, jobs, events, source readers, target registries, and resolver contracts so package and flat-file data can be moved with explicit ownership rules.

**For teams:** Supports controlled migration workflows where content, media, relationships, source files, and rollback evidence can be reviewed before and after import.

## Built With

This package makes its Composer dependencies visible because they are part of the value proposition, not just plumbing. When an upstream package has a public repository, its linked preview card points readers back to the maintainers so their work gets proper credit.

**Capell packages used here**

- [Capell Admin](https://github.com/capell-app/admin)
- [Capell Core](https://github.com/capell-app/core)

**Open-source packages used here**

- [Laravel Actions](https://github.com/lorisleiva/laravel-actions) - single-purpose action classes that keep package workflows out of controllers and Filament resources.
- [Spatie Laravel Package Tools](https://github.com/spatie/laravel-package-tools) - Laravel package bootstrapping for config, migrations, commands, translations, and service provider setup.

**Linked package previews**

[![Laravel Actions GitHub preview](https://opengraph.githubassets.com/capell-readme/lorisleiva/laravel-actions)](https://github.com/lorisleiva/laravel-actions)

[![Spatie Laravel Package Tools GitHub preview](https://opengraph.githubassets.com/capell-readme/spatie/laravel-package-tools)](https://github.com/spatie/laravel-package-tools)

## Screens And Workflow

Screenshots are generated from [docs/screenshots.json](screenshots.json) during package deployment.

- Import session index or host admin surface.
- Page import upload and validation workflow.
- Import validation summary.
- Relation resolution review.
- Rollback report view.
- Package export intent screen.

## Technical Shape

- MigrationAssistantServiceProvider registers the package.
- Config file: migration-assistant.php.
- Migrations create import_rollback_dashboard-dashboard_reports and import_sessions, including generic import target columns.
- Jobs execute import plans.
- Events report import completed or failed.
- Services cover package reading, writing, CSV/XML reading, mapping, validation, relation resolution, media ingest, preview, and rollback reporting.
- WordPress WXR support is intentionally provided by the separate `capell-app/wordpress-importer` package, which registers a source reader with MigrationAssistant.

## Code Map

| Area      | Path                                         | Purpose                                                             |
| --------- | -------------------------------------------- | ------------------------------------------------------------------- |
| Actions   | `packages/migration-assistant/src/Actions`   | Domain operations. Test these directly where possible.              |
| Data      | `packages/migration-assistant/src/Data`      | Structured payloads, form state, view models, and integration data. |
| Enums     | `packages/migration-assistant/src/Enums`     | Persisted states and Filament option values.                        |
| Models    | `packages/migration-assistant/src/Models`    | Eloquent records owned by the package.                              |
| Filament  | `packages/migration-assistant/src/Filament`  | Admin resources, pages, widgets, and settings UI.                   |
| Jobs      | `packages/migration-assistant/src/Jobs`      | Queued work and async side effects.                                 |
| Providers | `packages/migration-assistant/src/Providers` | Registration, extension hooks, routes, migrations, and resources.   |
| Resources | `packages/migration-assistant/resources`     | Views, translations, assets, and package resources.                 |
| Config    | `packages/migration-assistant/config`        | Package configuration and publishable config.                       |
| Database  | `packages/migration-assistant/database`      | Migrations, seeders, and settings migrations.                       |
| Tests     | `packages/migration-assistant/tests`         | Package-level Pest coverage.                                        |

## Admin Surface

- Resources: `ImportSessionResource`.
- Pages: `ImportPagesPage`, `ImportSitesPage`, `ListImportSessions`, `ViewImportSession`.

## Runtime Surface

- Jobs: `ExecuteImportPlanJob`.

## Data And Persistence

- import_rollback_dashboard-dashboard_reports stores the import session, created model ids, source filename/checksum, summary counts, executing user/time, and manual rollback instructions.
- import_sessions stores import kind, generic target type/id, status, manifest, decisions, validation state, and result summary.
- Retention and deletion rules should be verified against the host application policy.

- Models: `ImportRollbackReport`, `ImportSession`.
- Migrations: `2026_05_10_190859_01_create_import_sessions_table.php`, `2026_05_10_190859_02_create_import_rollback_dashboard-dashboard_reports_table.php`, `2026_05_18_000001_add_target_columns_to_import_sessions_table.php`.
- Config: `packages/migration-assistant/config/migration-assistant.php`.
- Data objects live in `src/Data/`; use them for payloads, form state, and view models.

## Extension Points

- Contracts: `ImportSessionSubNavigationExtender`, `ImportSourceReader`, `MigrationAssistantContextResolver`, `MigrationAssistantRowContributor`, `PageCollisionDetector`, `PageImportTargetResolver`.
- Events: `ImportCompleted`, `ImportFailed`.
- Listeners: `SendImportSessionNotifications`.
- Register Capell extension points, routes, migrations, settings, render hooks, and resources from service providers.

## Install Impact

- Adds import_rollback_dashboard-dashboard_reports and import_sessions tables.
- Adds migration-assistant queue configuration.
- Uses disk and path config for imports, exports, and working files.
- May require queue workers for long-running imports.
- No public routes are registered by this package.

## Install And Setup

- Install with `composer require capell-app/migration-assistant` in the host Capell application.
- Run migrations through the host application package install flow.
- In this repository, verify package changes with `vendor/bin/pest`; do not use `php artisan`.

## Admin And Access

- None proven in this package directory.

- Policy: OwnershipMap (packages/migration-assistant/src/Policy/OwnershipMap.php)

## Common Pitfalls

- Configure MIGRATOR_QUEUE and MIGRATOR_DISK before large imports.
- Check upload and package size limits before importing client archives.
- Run queue workers before testing async import jobs.
- Review relation resolution before applying imported data.

## Docs

- [docs index](README.md)
- [credits-and-acknowledgements.md](credits-and-acknowledgements.md)
- [extension-points.md](extension-points.md)
- [import-export-workflow.md](import-export-workflow.md)
- [migration-assistant.md](migration-assistant.md)
- [overview.md](overview.md)

## Testing

Run package tests from the repository root:

```bash
vendor/bin/pest packages/migration-assistant/tests --configuration=phpunit.xml
```

## Maintenance Notes

- Put behaviour changes in `src/Actions/`; UI classes, commands, and controllers should call actions instead of owning domain logic.
- Use package `Data` classes at boundaries instead of passing anonymous arrays between layers.
- Use backed enums for persisted values and enum labels for Filament options.