# nkdagility/azure-devops-migration-tools architecture

> Architecture diagram of the GitHub repository nkdagility/azure-devops-migration-tools, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nkdagility/azure-devops-migration-tools
- Repository: https://github.com/nkdagility/azure-devops-migration-tools

## Overview

##### Project’s Main Components
- Migration Tools Host/CLI – Your entry point (for example, MigrationTools.ConsoleCore, MigrationTools.Host, and related commands) that takes user configuration/commands.
- Migration Engine – The core engine (found in MigrationTools/MigrationEngine.cs) orchestrates the migration workflow by coordinating between various modules.
- Clients & Endpoints – Multiple “client” libraries and endpoint implementations (in directories such as MigrationTools.Clients.AzureDevops.Rest, MigrationTools.Clients.TfsObjectModel, and MigrationTools.Clients.FileSystem) that interact with external services (Azure DevOps Services, TFS, FileSystem endpoints).
- Processors – Modules responsible for performing tasks on work items (e.g., TfsWorkItemMigrationProcessor, WorkItemTrackingProcessor, and various processor enrichers under MigrationTools/Processors and MigrationTools/EndpointEnrichers). They encapsulate the business logic to transform and migrate data.
- Tools & Enrichers – Additional utilities (such as FieldMappingTool, StringManipulatorTool, WorkItemTypeMappingTool, and corresponding options and infrastructure) that support configuration and data transformation during migration.
- Telemetry & Logging – Components like the MigrationTools.Telemetery that hook into Application Insights, OpenTelemetry, and Elmah.io for metrics, logging, and exception tracking.
- Configuration & Options Parsing – Modules that handle reading and validating configuration files, including the Options and Configuration directories.
- Testing & Documentation – Separate, well-organized tests (unit, integration) and an extensive documentation layer (docs folder). Although these might be omitted in the high-level production system model, they are important for understanding interactions and dependencies.

##### Relationships and Interactions
- The Host/CLI will parse configurations from JSON files (and maybe command-line arguments) and then invoke the Migration Engine.
- The Migration Engine acts as a central orchestrator. It coordinates with client adapters (for Azure DevOps, TFS, etc.) by selecting the appropriate endpoints based on configuration.
- Endpoints abstract the external systems. They expose functionalities to query and update work item data, test plans, and pipelines.
- Processors apply business logic on the data received from endpoints. They might also call enrichers or utilize additional helper tools to perform field mapping or data conversions.
- Telemetry components are “fan‑out” systems that log migration metrics and errors, sending this data to external services.
- Dependency injection through ServiceCollectionExtensions (seen in various projects) ties these components together, ensuring that logging, configuration, and the client libraries are easily interchangeable.

##### Architectural Patterns and Principles
- Modular & Layered Architecture – The code is clearly divided into separate modules (clients, endpoints, processors, tools, etc.) that interact via defined interfaces, making the system extensible.
- Use of Dependency Injection – The ServiceCollectionExtensions in different parts of the code show that components are loosely coupled and easily testable.
- Adapter Pattern – The various client implementations (such as REST adapters versus TFS Object Model clients) act as adapters to abstract the external migration targets.
- Pipeline/Chain of Responsibility – The migration workflow (especially within processors and enrichers) can be seen as a sequential process where data flows through several stages.
- Logging and telemetry as cross-cutting concerns integrated across components.

##### Relevant Technologies and Frameworks
- .NET/C# as the primary language with project files (csproj) across multiple solutions.
- Azure DevOps APIs, TFS APIs, and possibly file system interactions for non-Azure endpoints.
- OpenTelemetry for metrics collection and Application Insights/Elmah.io as external monitoring tools.
- Various build and deployment tools triggered via PowerShell scripts (build scripts, pipelines YAML).

##### Specific Elements
– Host/CLI (MigrationTools.Host, MigrationTools.ConsoleCore)
– Migration Engine (MigrationTools/MigrationEngine)
– Clients/Endpoints (Azure DevOps, TFS Object Model, File System)
– Processors & Enrichers (Work Item Processors, Test Plans, Pipelines)
– Tools & Utilities (Field Mapping, String Manipulator tools)
– Telemetry/Logging (MigrationTools.Telemetery, Application Insights, Elmah.io)
– Configuration/Options layer
– The control flow from the Host to the Engine.
– Data flow between the Engine and the Clients/Endpoints.
– Interactions from Processors to Tools and Enrichers.
– Communication from various components to the Telemetry system.
– Core business logic components (e.g., Engine and Processors)
– Infrastructure components (CLI, configuration, telemetry)
– External integrations (Azure DevOps, TFS, telemetry services)
- Notes or callouts for key design patterns (adapter pattern, dependency injection).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Interface Layer"
        Config["Configuration & Options"]:::infra
        ConsoleCore["ConsoleCore"]:::interface
        ConsoleFull["ConsoleFull"]:::interface
        Host["Migration Tools Host/CLI"]:::interface
    end

    ConsoleCore --> Host
    ConsoleFull --> Host
    Config --> Host

    Host -->|"initiates"| Engine["Migration Engine"]:::core

    subgraph "Integration Layer"
        subgraph "Clients & Endpoints"
            AD["Azure DevOps (REST) Client"]:::external
            TFS["TFS Object Model Client"]:::external
            FS["File System Client"]:::external
        end
        subgraph "Processors & Tools"
            Proc["Processors"]:::core
            Tools["Tools & Utilities"]:::util
            Enr["Enrichers"]:::util
        end
        Tel["Telemetry & Logging"]:::infra
    end

    Engine -->|"orchestrates"| AD
    Engine -->|"orchestrates"| TFS
    Engine -->|"orchestrates"| FS
    Engine -->|"triggers"| Proc
    Proc -->|"uses"| Tools
    Proc -->|"uses"| Enr

    AD -->|"logs"| Tel
    TFS -->|"logs"| Tel
    FS -->|"logs"| Tel
    Proc -->|"logs"| Tel
    Tools -->|"logs"| Tel
    Enr -->|"logs"| Tel

    classDef interface fill:#AED6F1,stroke:#2874A6,stroke-width:2px;
    classDef core fill:#ABEBC6,stroke:#27AE60,stroke-width:2px;
    classDef external fill:#F9E79F,stroke:#D4AC0D,stroke-width:2px;
    classDef infra fill:#F5CBA7,stroke:#D35400,stroke-width:2px;
    classDef util fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;

    click ConsoleCore "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.ConsoleCore"
    click ConsoleFull "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.ConsoleFull"
    click Host "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.Host"
    click Engine "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools/MigrationEngine.cs"
    click Config "https://github.com/nkdagility/azure-devops-migration-tools/tree/main/src/MigrationTools/Options"
    click AD "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.Clients.AzureDevops.Rest"
    click TFS "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.Clients.TfsObjectModel"
    click FS "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.Clients.FileSystem"
    click Proc "https://github.com/nkdagility/azure-devops-migration-tools/tree/main/src/MigrationTools/Processors"
    click Tools "https://github.com/nkdagility/azure-devops-migration-tools/tree/main/src/MigrationTools/Tools"
    click Enr "https://github.com/nkdagility/azure-devops-migration-tools/tree/main/src/MigrationTools/EndpointEnrichers"
    click Tel "https://github.com/nkdagility/azure-devops-migration-tools/blob/main/src/MigrationTools.Telemetery"
    click Tools "https://github.com/nkdagility/azure-devops-migration-tools/tree/main/src/MigrationTools.Clients.TfsObjectModel/Tools/FieldMappingTool"
```
