# kentico/xperience-by-kentico-kentico-migration-tool architecture

> Architecture diagram of the GitHub repository kentico/xperience-by-kentico-kentico-migration-tool, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kentico/xperience-by-kentico-kentico-migration-tool
- Repository: https://github.com/kentico/xperience-by-kentico-kentico-migration-tool

## Overview

The repository implements a CLI-driven migration tool that transfers Kentico 11/12/13 data into Xperience by Kentico. Its main workflow is configuration and source-version selection, command dispatch, source reads, transformation, target writes, and reporting. The graph preserves documented content, commerce, and customization capabilities alongside core runtime layers. Relationships are limited to those shown in excerpts, the SOURCE INDEX, or README; several implementation details are unsampled, so some documented subsystem links remain broad.

Main entry points: [`Migration.Tool.CLI/Program.cs`](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/Program.cs) (Migration CLI), [`KVA/Migration.Tool.Source/Handlers`](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/KVA/Migration.Tool.Source/Handlers) (Migration handlers), [`KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs) (Page migration), [`Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs`](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs) (Bulk copy service)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI orchestration"]
  node_cli["Migration CLI<br/>[Program.cs]"]
  node_configuration["Tool configuration"]
  node_dispatch["Command dispatch<br/>[MasterCommand.cs]"]
end

subgraph group_sources["Source data"]
  node_source11[("K11 source context<br/>[K11Context.cs]")]
  node_source12[("KX12 source context<br/>[KX12Context.cs]")]
  node_source13[("KX13 source context<br/>[KX13Context.cs]")]
  node_sourceapi["KX13 widget API"]
end

subgraph group_migration["Migration stages"]
  node_migrationhandlers["Migration handlers<br/>[Handlers]"]
  node_pages["Page migration"]
  node_contactmigration["Contact migration"]
  node_commerce["Commerce migration"]
  node_model["Source model facade<br/>[ModelFacade.cs]"]
  node_mappers["Data mappers<br/>[Mappers]"]
  node_transformations["Custom transformations"]
  node_guid["Identity mapping<br/>[GuidHelper.cs]"]
  node_pk["Primary key locator"]
end

subgraph group_target["Target integration"]
  node_bulk["Bulk copy service"]
  node_bulkrequest["Bulk copy request<br/>[BulkCopyRequest.cs]"]
  node_targetapi["XbyK target API"]
end

subgraph group_extensions["Customization and reporting"]
  node_protocol["Migration protocol<br/>[IProtocol.cs]"]
  node_handbook["Migration guidance"]
  node_result["Command results<br/>[CommandResult.cs]"]
  node_ipcmodel["Migration IPC models<br/>[Model.cs]"]
  node_reports["Console and log output<br/>[ConsoleHelper.cs]"]
end

node_operator(("Operator"))

node_operator -->|"runs"| node_cli
node_cli -->|"loads settings"| node_configuration
node_cli -->|"dispatches commands"| node_dispatch
node_dispatch -->|"handles commands"| node_migrationhandlers
node_cli -->|"selects source"| node_source11
node_cli -->|"selects source"| node_source12
node_cli -->|"selects source"| node_source13
node_migrationhandlers -.->|"reads source"| node_model
node_pages -->|"selects records"| node_model
node_pages -->|"maps pages"| node_mappers
node_migrationhandlers -->|"transforms data"| node_mappers
node_transformations -.->|"customizes mappings"| node_mappers
node_contactmigration -->|"copies contact data"| node_bulk
node_commerce -->|"migrates commerce"| node_targetapi
node_bulk -->|"uses request"| node_bulkrequest
node_bulk -->|"writes target data"| node_targetapi
node_migrationhandlers -->|"writes migrated data"| node_targetapi
node_sourceapi -.->|"provides widget data"| node_migrationhandlers
node_pages -->|"uses page metadata"| node_ipcmodel
node_pages -->|"creates stable identities"| node_guid
node_pk -->|"locates source keys"| node_model
node_migrationhandlers -->|"records migration notes"| node_protocol
node_protocol -->|"uses guidance references"| node_handbook
node_migrationhandlers -->|"returns status"| node_result
node_cli -->|"outputs logs"| node_reports

click node_cli "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/Program.cs"
click node_configuration "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/ToolConfiguration.cs"
click node_dispatch "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/MasterCommand.cs"
click node_source11 "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.K11/Context/K11Context.cs"
click node_source12 "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.KX12/Context/KX12Context.cs"
click node_source13 "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.KX13/Context/KX13Context.cs"
click node_sourceapi "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KX13.Extensions/ToolApiController.cs"
click node_migrationhandlers "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/KVA/Migration.Tool.Source/Handlers"
click node_pages "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs"
click node_contactmigration "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Core.KX13/Handlers/MigrateContactManagementCommandHandler.cs"
click node_commerce "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Core.KX13/Handlers/Base/MigrateCommerceHandlerBase.cs"
click node_model "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/ModelFacade.cs"
click node_mappers "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/KVA/Migration.Tool.Source/Mappers"
click node_transformations "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/Migration.Tool.Extensions/CommunityMigrations"
click node_bulk "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs"
click node_bulkrequest "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/BulkCopy/BulkCopyRequest.cs"
click node_targetapi "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/Migration.Tool.KXP.Api"
click node_protocol "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/MigrationProtocol/IProtocol.cs"
click node_handbook "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/MigrationProtocol/HandbookReferences.cs"
click node_result "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Abstractions/CommandResult.cs"
click node_ipcmodel "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/Ipc/Model.cs"
click node_guid "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Helpers/GuidHelper.cs"
click node_pk "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/Services/PrimaryKeyLocatorService.cs"
click node_reports "https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Helpers/ConsoleHelper.cs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_configuration,node_dispatch toneBlue
class node_source11,node_source12,node_source13,node_sourceapi toneAmber
class node_migrationhandlers,node_pages,node_contactmigration,node_commerce,node_model,node_mappers,node_transformations,node_guid,node_pk toneMint
class node_bulk,node_bulkrequest,node_targetapi toneRose
class node_protocol,node_handbook,node_result,node_ipcmodel,node_reports,node_operator toneIndigo
```

## Components

### CLI orchestration

- [Migration CLI](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.CLI/Program.cs): `Migration.Tool.CLI/Program.cs`
- [Tool configuration](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/ToolConfiguration.cs): `Migration.Tool.Common/ToolConfiguration.cs`
- [Command dispatch](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/MasterCommand.cs): `Migration.Tool.Common/Services/MasterCommand.cs`

### Source data

- [K11 source context](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.K11/Context/K11Context.cs): `Migration.Tool.K11/Context/K11Context.cs`
- [KX12 source context](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.KX12/Context/KX12Context.cs): `Migration.Tool.KX12/Context/KX12Context.cs`
- [KX13 source context](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.KX13/Context/KX13Context.cs): `Migration.Tool.KX13/Context/KX13Context.cs`
- [KX13 widget API](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KX13.Extensions/ToolApiController.cs): `KX13.Extensions/ToolApiController.cs`

### Migration stages

- [Migration handlers](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/KVA/Migration.Tool.Source/Handlers): `KVA/Migration.Tool.Source/Handlers`
- [Page migration](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs): `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`
- [Contact migration](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Core.KX13/Handlers/MigrateContactManagementCommandHandler.cs): `Migration.Tool.Core.KX13/Handlers/MigrateContactManagementCommandHandler.cs`
- [Commerce migration](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Core.KX13/Handlers/Base/MigrateCommerceHandlerBase.cs): `Migration.Tool.Core.KX13/Handlers/Base/MigrateCommerceHandlerBase.cs`
- [Source model facade](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/ModelFacade.cs): `KVA/Migration.Tool.Source/ModelFacade.cs`
- [Data mappers](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/KVA/Migration.Tool.Source/Mappers): `KVA/Migration.Tool.Source/Mappers`
- [Custom transformations](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/Migration.Tool.Extensions/CommunityMigrations): `Migration.Tool.Extensions/CommunityMigrations`
- [Identity mapping](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Helpers/GuidHelper.cs): `Migration.Tool.Common/Helpers/GuidHelper.cs`
- [Primary key locator](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/KVA/Migration.Tool.Source/Services/PrimaryKeyLocatorService.cs): `KVA/Migration.Tool.Source/Services/PrimaryKeyLocatorService.cs`

### Target integration

- [Bulk copy service](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs): `Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs`
- [Bulk copy request](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/BulkCopy/BulkCopyRequest.cs): `Migration.Tool.Common/Services/BulkCopy/BulkCopyRequest.cs`
- [XbyK target API](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/tree/master/Migration.Tool.KXP.Api): `Migration.Tool.KXP.Api`

### Customization and reporting

- [Migration protocol](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/MigrationProtocol/IProtocol.cs): `Migration.Tool.Common/MigrationProtocol/IProtocol.cs`
- [Migration guidance](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/MigrationProtocol/HandbookReferences.cs): `Migration.Tool.Common/MigrationProtocol/HandbookReferences.cs`
- [Command results](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Abstractions/CommandResult.cs): `Migration.Tool.Common/Abstractions/CommandResult.cs`
- [Migration IPC models](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Services/Ipc/Model.cs): `Migration.Tool.Common/Services/Ipc/Model.cs`
- [Console and log output](https://github.com/kentico/xperience-by-kentico-kentico-migration-tool/blob/master/Migration.Tool.Common/Helpers/ConsoleHelper.cs): `Migration.Tool.Common/Helpers/ConsoleHelper.cs`

### Other components

- **Operator**

## Connections

- Operator → Migration CLI: runs (evidence: `README.md`)
- Migration CLI → Tool configuration: loads settings (evidence: `Migration.Tool.CLI/Program.cs`)
- Migration CLI → Command dispatch: dispatches commands (evidence: `Migration.Tool.CLI/Program.cs`)
- Command dispatch → Migration handlers: handles commands (evidence: `README.md`)
- Migration CLI → K11 source context: selects source (evidence: `Migration.Tool.CLI/Program.cs`)
- Migration CLI → KX12 source context: selects source (evidence: `Migration.Tool.CLI/Program.cs`)
- Migration CLI → KX13 source context: selects source (evidence: `Migration.Tool.CLI/Program.cs`)
- Migration handlers → Source model facade: reads source (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Page migration → Source model facade: selects records (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Page migration → Data mappers: maps pages (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Migration handlers → Data mappers: transforms data (evidence: `README.md`)
- Custom transformations → Data mappers: customizes mappings
- Contact migration → Bulk copy service: copies contact data (evidence: `Migration.Tool.Core.KX13/Handlers/MigrateContactManagementCommandHandler.cs`)
- Commerce migration → XbyK target API: migrates commerce (evidence: `Migration.Tool.Core.KX13/Handlers/Base/MigrateCommerceHandlerBase.cs`)
- Bulk copy service → Bulk copy request: uses request (evidence: `Migration.Tool.Common/Services/BulkCopy/BulkDataCopyService.cs`)
- Bulk copy service → XbyK target API: writes target data (evidence: `README.md`)
- Migration handlers → XbyK target API: writes migrated data (evidence: `README.md`)
- KX13 widget API → Migration handlers: provides widget data
- Page migration → Migration IPC models: uses page metadata (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Page migration → Identity mapping: creates stable identities (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Primary key locator → Source model facade: locates source keys (evidence: `KVA/Migration.Tool.Source/Services/PrimaryKeyLocatorService.cs`)
- Migration handlers → Migration protocol: records migration notes (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Migration protocol → Migration guidance: uses guidance references (evidence: `Migration.Tool.Common/MigrationProtocol/HandbookReferences.cs`)
- Migration handlers → Command results: returns status (evidence: `KVA/Migration.Tool.Source/Handlers/MigratePagesCommandHandler.cs`)
- Migration CLI → Console and log output: outputs logs (evidence: `README.md`)
