quantum-ai-v3/docs/development/legacy-migration-guide.md

Legacy Agent Migration Guide

Overview

This guide explains how to properly convert legacy agent templates to the new Template Component Architecture without introducing technical debt or code bloat.

⚠️ The Legacy Contamination Problem

When converting legacy agents, the natural instinct is to copy existing working code. However, this leads to:

• Template Bloat: 1,000+ line templates instead of 300 lines
• Duplicate Code: Custom implementations instead of shared utilities
• Maintenance Issues: Multiple copies of the same functionality
• Architecture Violations: Inline code instead of component system

✅ Correct Migration Process

Step 1: Analyze Legacy Functionality (Don't Copy Code!)

DO: List the functional requirements

- File upload for PDF files
- Radio button selection for analysis type
- Display analysis results with formatting
- Copy, download, reset functionality

DON'T: Copy the implementation code

❌ Never copy 500+ lines of inline JavaScript
❌ Never copy 400+ lines of custom CSS
❌ Never copy custom implementations of shared utilities

Step 2: Map to Component Architecture

Legacy Approach (Wrong):

<!-- 100+ lines of custom header HTML -->
<!-- 200+ lines of custom form HTML -->
<!-- 300+ lines of custom JavaScript -->
<!-- 400+ lines of custom CSS -->

Component Approach (Right):

{% include "workflows/components/agent_header.html" %}
{% include "workflows/components/quick_agents_panel.html" %}
<!-- 50 lines of agent-specific form -->
{% include "workflows/components/processing_status.html" %}
{% include "workflows/components/results_container.html" %}

Step 3: Use Agent Template Prototype as Reference

Start with: agent_template_prototype.html (perfect UI patterns) Not with: Existing legacy agent template

The prototype shows exactly how components should work together.

Step 4: Implement Only Agent-Specific Logic

Keep from Legacy:

• ✅ Business logic requirements
• ✅ Form field definitions
• ✅ Validation rules
• ✅ API integration patterns

Replace with Components:

• ❌ Header implementation → Use agent_header.html
• ❌ Navigation panel → Use quick_agents_panel.html
• ❌ Processing display → Use processing_status.html
• ❌ Results display → Use results_container.html
• ❌ Utility functions → Use WorkflowsCore

📊 Migration Results Comparison

Aspect	Legacy Approach	Component Approach	Improvement
Template Size	1,031 lines	285 lines	72% reduction
CSS Lines	480+ lines	145 lines	70% reduction
JavaScript	500+ inline	150 external	70% reduction
Maintenance	Individual updates	Shared component updates	Automatic
Consistency	Varies per agent	Identical across agents	Perfect

🎯 Real Example: Data Analyzer Migration

Before (Legacy Contamination)

<!-- data_analyzer/templates/data_analyzer/detail.html - 928 lines -->
<script>
// 500+ lines of custom JavaScript duplicating WorkflowsCore
function copyResults() {
    // Custom implementation
}
function downloadResults() {
    // Custom implementation  
}
// ... hundreds more lines
</script>

<style>
/* 400+ lines of custom CSS duplicating agent-base.css */
.file-upload-area { /* custom styles */ }
.radio-card { /* custom styles */ }
/* ... hundreds more lines */
</style>

After (Component Architecture)

<!-- workflows/templates/workflows/data-analyzer.html - 285 lines -->
{% include "workflows/components/agent_header.html" %}
{% include "workflows/components/quick_agents_panel.html" %}

<!-- 50 lines of agent-specific form -->
<div class="form-group">
    <label>📁 Upload Data File</label>
    <input type="file" name="file" accept=".pdf">
</div>

{% include "workflows/components/processing_status.html" %}
{% include "workflows/components/results_container.html" %}

Result: 72% smaller, consistent UI, automatic utility functions.

🛡️ Prevention Guidelines

For Developers

1. Never start migration by reading legacy template code
2. Always start with agent_template_prototype.html for UI reference
3. Use component includes for all shared functionality
4. Write only agent-specific form fields and validation

For Code Reviews

1. Reject any template over 500 lines
2. Reject any inline JavaScript over 100 lines
3. Reject any custom CSS over 200 lines
4. Require component include usage

Red Flags in Pull Requests

• ❌ function copyResults() - Should use WorkflowsCore.copyResults()
• ❌ function downloadResults() - Should use WorkflowsCore.downloadResults()
• ❌ Custom toast implementations - Should use WorkflowsCore.showToast()
• ❌ Custom processing displays - Should use processing_status.html component
• ❌ Custom header implementations - Should use agent_header.html component

📚 Additional Resources

• Template Component Architecture
• Agent Template Prototype
• WorkflowsCore Documentation
• 4-Step Agent Creation Process

🎯 Key Takeaway

Legacy functionality should inspire new components, not contaminate them.

The goal is to preserve the user experience and business logic while completely replacing the implementation with clean, maintainable component architecture.