Documentation

how-to/orchestrate-ui-migration.md

title: Legacy AssetTrak UI Migration and Refactor Guide

About

This document provides detailed information regarding the UI migration process.
Workflows and guidelines for coordinating multiple agents and managing the migration process are included.

Orchestration Workflow

Phase 1: Initial Analysis

Step 1.1: Launch Frontend + Backend Analysis

Use the ui-page-migration-specialist agent to analyze both frontend and backend:

Launch ui-page-migration-specialist with:
- Page name/path
- Request comprehensive analysis of:
  - Frontend patterns (permissions, API client, response handling)
  - Backend patterns (service layer, DataProviders, EF Core vs Dapper)
  - Full dependency analysis

Step 1.2: Review the Analysis Report

Wait for the agent's complete report and extract these key sections:

  • Backend Status: Fully Aligned / Mixed Pattern / Non-Aligned
  • Frontend Status: What patterns need updating
  • Complexity Assessment: Simple / Moderate / Complex
  • Recommended Approach: Agent's suggestions

Phase 2: Decision Point - Backend Complexity

Based on the backend status from Step 1.2:

Scenario A: Backend is "Fully Aligned with Dynaplex"

✅ Backend uses EF Core, DbContext, no DataProviders
→ DECISION: Frontend-only migration
→ NEXT: Skip to Phase 3 (Frontend Execution)

Scenario B: Backend is "Mixed Pattern"

⚠️ Backend uses BOTH EF Core AND Dapper/DataProviders
→ DECISION NEEDED: Ask user
→ QUESTION: "Backend uses mixed patterns (EF Core + Dapper). Options:
   A. Migrate backend first, then frontend
   B. Migrate frontend only (leave backend mixed for now)
   C. Full migration (both together)"
→ NEXT: Based on user choice, proceed accordingly

Scenario C: Backend is "Non-Aligned"

❌ Backend uses Dapper/raw SQL/DataProviders exclusively
→ DECISION: Backend migration required
→ NEXT: Proceed to Phase 2.1 (Backend Deep Dive)

Step 2.1: Deep Backend Analysis (Only if Scenario B or C)

Launch database-migrations skill agent for detailed backend analysis:

Launch database-migrations skill with:
- Component name (e.g., "catalog")
- Service name (e.g., "ItemsService")
- Request:
  - Full DataProvider inventory
  - Legacy pattern analysis (Dapper, raw SQL, EntLib)
  - Migration complexity assessment
  - Conversion plan with priorities

Step 2.2: Review Backend Migration Plan

Extract from database-migrations skill report:

  • DataProvider inventory: Which classes, how many methods
  • Migration complexity: Simple / Moderate / Complex / Full Rewrite
  • Recommended approach: Incremental vs full migration
  • Estimated scope: Number of files/methods to convert

Step 2.3: User Decision on Scope

If backend needs significant work, ask user:

AskUserQuestion:
"Backend migration analysis complete. Recommended approach: [from agent]

Options:
A. Migrate backend now (estimated [X] DataProviders, [Y] methods)
B. Migrate frontend only, defer backend work
C. Incremental: Migrate one DataProvider at a time alongside frontend

Which approach do you prefer?"

Phase 3: Execution - Based on Decisions

Path 3A: Frontend Only Migration

1. ui-page-migration-specialist completes frontend migration
   - Permission system (menu → hierarchical)
   - API client (singleton → factory)
   - Response handling (wrapper → status codes)
   - Remove legacy UI patterns

2. Report: Frontend migration complete, backend unchanged

→ NEXT: Phase 4 (Validation & Reporting)

Path 3B: Backend First, Then Frontend

1. database-migrations skill executes backend migration:
   - Convert DataProviders to EF Core
   - Update service layer
   - Remove Dapper dependencies
   - Test backend changes

2. AFTER backend complete:
   - Regenerate Kiota API clients
   - ui-page-migration-specialist executes frontend migration

3. Report: Full-stack migration complete

→ NEXT: Phase 4 (Validation & Reporting)

Path 3C: Coordinated Full Migration

1. BACKEND: database-migrations skill starts backend work

2. FRONTEND: ui-page-migration-specialist starts frontend work
   (can work in parallel for independent changes)

3. COORDINATION POINTS:
   - If backend changes API contracts → regenerate Kiota → update frontend
   - Ensure frontend changes align with backend changes

4. Report: Full-stack migration complete

→ NEXT: Phase 4 (Validation & Reporting)

Path 3D: Incremental Migration (One Piece at a Time)

For each DataProvider or feature area:
1. database-migrations skill: Convert one DataProvider
2. Test backend changes
3. ui-page-migration-specialist: Update related frontend
4. Test integration
5. Repeat for next DataProvider

Report after each iteration, ask if user wants to continue

→ NEXT: Phase 4 after all iterations (or user stops)

Phase 4: Validation & Reporting

Step 4.1: Pattern Validation (Optional but Recommended)

Ask user if they want validation:

"Migration complete. Run pattern validation? (pattern-enforcer checks code compliance)"
- If yes: Launch pattern-enforcer agent
- If no: Skip to 4.2

Step 4.2: Generate Consolidated Report

Create a comprehensive report combining all agent outputs:

# Migration Report: [Page Name]

## Summary
- ✅ Frontend: [Status]
- ✅ Backend: [Status]
- ⏱️ Agents Used: [List]

## What Changed

### Frontend
[Summary from ui-page-migration-specialist]
- Files modified: [Count]
- Patterns updated: [List]

### Backend
[Summary from database-migrations skill, if applicable]
- DataProviders removed: [Count]
- Methods converted: [Count]
- Patterns updated: [List]

## Files Modified
[Complete list organized by category]

## Next Steps
1. [Testing recommendations]
2. [Kiota regeneration if needed]
3. [Any follow-up work]

## Known Issues / Follow-up
[Any deferred work or issues encountered]

Step 4.3: Final User Check

Ask user:

"Migration complete!

Would you like me to:
A. Commit the changes (I'll create a detailed commit message)
B. Review specific files before committing
C. Leave uncommitted for you to review

Or is there anything else you'd like me to address?"

Decision Trees Reference

When to Involve Which Agent

Situation Agent to Use Why
Analyze page (always first) ui-page-migration-specialist Full-stack analysis expert
Backend has Dapper/DataProviders database-migrations skill Legacy → EF Core conversion expert
Architectural uncertainty dynaplex-architect High-level design decisions
Validate completed work pattern-enforcer Quick pattern compliance check
Comprehensive code review code-reviewer-dynaplex Thorough review of changes
Documentation needed documentation-guardian Component docs and README

Migration Complexity Assessment

Backend Status Frontend Complexity Overall Approach
Fully Aligned Simple Quick win - frontend only
Fully Aligned Complex Frontend focus, may need multiple iterations
Mixed Pattern Simple Recommend backend cleanup + frontend
Mixed Pattern Complex Incremental or user choice
Non-Aligned Any Backend required, then frontend

Key Principles

  1. Always start with ui-page-migration-specialist - It's the entry point for analysis
  2. Check backend thoroughly - Don't assume it's aligned without checking DataProviders
  3. Ask user for major decisions - Don't assume scope or approach
  4. Report after each phase - Keep user informed of progress
  5. Coordinate agents, don't overlap - Each agent has specific expertise
  6. Consolidate reports - User gets one comprehensive summary
  7. Offer next steps - Always provide clear path forward

Common Patterns

Pattern 1: Simple Page (Backend Already Aligned)

1. ui-page-migration-specialist analyzes + migrates frontend
2. Report results
3. Done ✅

Pattern 2: Complex Backend (Items Page Scenario)

1. ui-page-migration-specialist analyzes → finds DataProviders
2. database-migrations skill analyzes backend in detail
3. Ask user: backend first or frontend only?
4. Execute based on user choice
5. Consolidate reports
6. Done ✅

Pattern 3: Incremental Multi-Page Migration

For each page:
1. ui-page-migration-specialist analyzes
2. If backend needed: database-migrations skill handles
3. Complete page migration
4. Brief report
5. Ask: "Continue with next page?"
Repeat until user says stop

Error Handling

If an agent encounters errors:

  1. Capture the error from agent report
  2. Assess severity: Blocker vs Warning
  3. If blocker:
    • Report to user immediately
    • Ask for guidance or clarification
    • May need to involve troubleshooter agent
  4. If warning:
    • Note in final report
    • Continue with migration
    • Flag for user review

Success Criteria

Migration is complete when:

  • ✅ All agents have finished their work
  • ✅ User questions have been answered
  • ✅ Consolidated report generated
  • ✅ User is satisfied with results
  • ✅ Next steps are clear

Usage Example

User: "Migrate the items page"

You (Managing Agent):

  1. Invoke this skill to get workflow
  2. Launch ui-page-migration-specialist for items page
  3. Review its report → finds backend uses DataProviders + Dapper
  4. Launch database-migrations skill for backend analysis
  5. Ask user which approach they prefer
  6. Execute migrations based on user choice
  7. Generate consolidated report
  8. Offer to commit or review

Result: Comprehensive, managed migration with clear orchestration

Maintaining This Orchestrator

When updating this skill:

  • Keep workflow linear and clear
  • Add decision points, don't remove them
  • Update agent names if they change
  • Add new patterns as they're discovered
  • Keep it focused on orchestration, not technical details

The specialist agents handle the HOW, this skill handles the WHEN and WHICH.