Imported from RobertoBorges/migration-copilot (packages/migration-cli/templates/skills/business-logic-mapping/SKILL.md). Install upstream with npx skills add RobertoBorges/migration-copilot --skill business-logic-mapping. Copyright stays with the author.

Business Logic Mapping Skill

Use this skill to discover, map, track, and verify business logic preservation during application migration. This ensures that all business rules, calculations, validations, workflows, and media assets from the legacy application are correctly implemented in the modernized version.

When to Use This Skill

• Migrating .NET Framework to .NET 10+ applications
• Migrating Java EE to Spring Boot applications
• Any migration where business logic preservation is critical
• When you need to track what logic has been migrated vs. what remains

Business Logic Discovery

Step 1: Identify Business Logic Locations

Scan the legacy application for business logic in these common locations:

.NET Applications

Java Applications

Step 2: Categorize Business Logic Types

Business Logic Mapping Document

Create a reports/Business-Logic-Mapping.md file to track all business logic:

# Business Logic Mapping Report

**Application:** [Application Name]
**Generated:** [Date/Time]
**Migration:** [Source Framework] → [Target Framework]

## Executive Summary
- **Total Business Logic Items:** [Count]
- **Migrated:** [Count] ([Percentage]%)
- **In Progress:** [Count]
- **Pending:** [Count]
- **Blocked:** [Count]

## Business Logic Inventory

### Calculations

| ID | Name | Source Location | Target Location | Status | Verified |
|----|------|-----------------|-----------------|--------|----------|
| BL-001 | Tax Calculation | `OrderService.CalculateTax()` | `Services/TaxCalculator.cs` | ✅ Migrated | ✅ Yes |
| BL-002 | Discount Engine | `PricingHelper.ApplyDiscount()` | `Services/PricingService.cs` | 🔄 In Progress | ⬜ No |
| BL-003 | Shipping Cost | `ShippingCalculator.GetRate()` | Pending | ⬜ Pending | ⬜ No |

### Validations

| ID | Name | Source Location | Target Location | Status | Verified |
|----|------|-----------------|-----------------|--------|----------|
| BL-010 | Credit Limit Check | `CustomerValidator.CheckCredit()` | `Validators/CreditValidator.cs` | ✅ Migrated | ✅ Yes |
| BL-011 | Age Verification | `OrderValidator.VerifyAge()` | `Validators/AgeValidator.cs` | ✅ Migrated | ⬜ No |

### Workflows

| ID | Name | Source Location | Target Location | Status | Verified |
|----|------|-----------------|-----------------|--------|----------|
| BL-020 | Order Processing | `OrderWorkflow.Process()` | `Workflows/OrderStateMachine.cs` | 🔄 In Progress | ⬜ No |
| BL-021 | Approval Chain | `ApprovalService.Submit()` | Pending | ⬜ Pending | ⬜ No |

### Transformations

| ID | Name | Source Location | Target Location | Status | Verified |
|----|------|-----------------|-----------------|--------|----------|
| BL-030 | Report Aggregation | `ReportHelper.Aggregate()` | `Services/ReportingService.cs` | ✅ Migrated | ✅ Yes |

### Integrations

| ID | Name | Source Location | Target Location | Status | Verified |
|----|------|-----------------|-----------------|--------|----------|
| BL-040 | Payment Gateway | `PaymentService.Process()` | `Services/PaymentService.cs` | 🔄 In Progress | ⬜ No |

## Media and Static Assets

| Asset Type | Source Path | Target Path | Status |
|------------|-------------|-------------|--------|
| Images | `/Content/images/` | `/wwwroot/images/` | ✅ Copied |
| CSS | `/Content/css/` | `/wwwroot/css/` | ✅ Copied |
| JavaScript | `/Scripts/` | `/wwwroot/js/` | ✅ Copied |
| Documents | `/App_Data/docs/` | `/wwwroot/docs/` | ✅ Copied |
| Uploads | `/Uploads/` | Azure Blob Storage | 🔄 In Progress |

## Migration Notes

### Preserved As-Is
- [List items that required no changes]

### Modified During Migration
- [List items that required adaptation with explanation]

### Architectural Changes
- [List items that required redesign with justification]

## Verification Checklist
- [ ] All calculations produce same results as legacy
- [ ] All validations enforce same rules
- [ ] All workflows follow same process flows
- [ ] All integrations maintain same behavior
- [ ] All media assets accessible in new application

Business Logic Patterns: .NET Framework → .NET 10

Service Layer Mapping

// =============================================================================
// LEGACY: .NET Framework Service
// =============================================================================
public class OrderService
{
    private readonly OrderRepository _orderRepository;
    
    public decimal CalculateTotal(Order order)
    {
        var subtotal = order.Items.Sum(i => i.Price * i.Quantity);
        var tax = subtotal * 0.08m; // 8% tax
        var discount = GetCustomerDiscount(order.CustomerId);
        return subtotal + tax - discount;
    }
    
    private decimal GetCustomerDiscount(int customerId)
    {
        // Business rule: VIP customers get 10% discount
        var customer = _customerRepository.GetById(customerId);
        return customer.IsVip ? subtotal * 0.10m : 0;
    }
}

// =============================================================================
// MODERN: .NET 10 Service (Preserve same logic, modernize patterns)
// =============================================================================
public interface IOrderCalculationService
{
    decimal CalculateTotal(Order order);
}

public class OrderCalculationService : IOrderCalculationService
{
    private readonly ICustomerRepository _customerRepository;
    private readonly IOptions<TaxSettings> _taxSettings;
    private readonly ILogger<OrderCalculationService> _logger;

    public OrderCalculationService(
        ICustomerRepository customerRepository,
        IOptions<TaxSettings> taxSettings,
        ILogger<OrderCalculationService> logger)
    {
        _customerRepository = customerRepository;
        _taxSettings = taxSettings;
        _logger = logger;
    }

    public decimal CalculateTotal(Order order)
    {
        // PRESERVED: Same calculation logic
        var subtotal = order.Items.Sum(i => i.Price * i.Quantity);
        var tax = subtotal * _taxSettings.Value.DefaultRate; // Externalized config
        var discount = GetCustomerDiscount(order.CustomerId, subtotal);
        
        _logger.LogDebug("Order total calculated: Subtotal={Subtotal}, Tax={Tax}, Discount={Discount}", 
            subtotal, tax, discount);
        
        return subtotal + tax - discount;
    }
    
    private decimal GetCustomerDiscount(int customerId, decimal subtotal)
    {
        // PRESERVED: Same business rule - VIP customers get 10% discount
        var customer = _customerRepository.GetById(customerId);
        return customer?.IsVip == true ? subtotal * 0.10m : 0;
    }
}

Validation Logic Mapping

// =============================================================================
// LEGACY: .NET Framework Validator
// =============================================================================
public class OrderValidator
{
    public ValidationResult Validate(Order order)
    {
        var errors = new List<string>();
        
        // Business Rule: Minimum order amount
        if (order.Total < 10.00m)
            errors.Add("Minimum order amount is $10.00");
        
        // Business Rule: Maximum items per order
        if (order.Items.Count > 100)
            errors.Add("Maximum 100 items per order");
        
        // Business Rule: Customer credit check
        if (!HasSufficientCredit(order.CustomerId, order.Total))
            errors.Add("Insufficient credit limit");
        
        return new ValidationResult(errors);
    }
}

// =============================================================================
// MODERN: .NET 10 with FluentValidation (Same rules, modern pattern)
// =============================================================================
public class OrderValidator : AbstractValidator<Order>
{
    private readonly ICustomerCreditService _creditService;

    public OrderValidator(ICustomerCreditService creditService)
    {
        _creditService = creditService;

        // PRESERVED: Minimum order amount
        RuleFor(x => x.Total)
            .GreaterThanOrEqualTo(10.00m)
            .WithMessage("Minimum order amount is $10.00");

        // PRESERVED: Maximum items per order
        RuleFor(x => x.Items.Count)
            .LessThanOrEqualTo(100)
            .WithMessage("Maximum 100 items per order");

        // PRESERVED: Customer credit check
        RuleFor(x => x)
            .MustAsync(async (order, cancellation) => 
                await _creditService.HasSufficientCreditAsync(order.CustomerId, order.Total))
            .WithMessage("Insufficient credit limit");
    }
}

Business Logic Patterns: Java EE → Spring Boot

EJB to Spring Service

// =============================================================================
// LEGACY: Java EE EJB
// =============================================================================
@Stateless
public class InvoiceServiceBean implements InvoiceService {
    
    @EJB
    private CustomerDAO customerDAO;
    
    @EJB
    private TaxCalculator taxCalculator;
    
    public Invoice generateInvoice(Order order) {
        // Business logic: Calculate invoice with tax
        BigDecimal subtotal = calculateSubtotal(order);
        BigDecimal tax = taxCalculator.calculate(subtotal, order.getState());
        BigDecimal total = subtotal.add(tax);
        
        // Business rule: Apply early payment discount
        if (order.getPaymentTerms().equals("NET10")) {
            total = applyEarlyPaymentDiscount(total, new BigDecimal("0.02"));
        }
        
        return new Invoice(order.getId(), subtotal, tax, total);
    }
    
    private BigDecimal applyEarlyPaymentDiscount(BigDecimal amount, BigDecimal rate) {
        return amount.multiply(BigDecimal.ONE.subtract(rate));
    }
}

// =============================================================================
// MODERN: Spring Boot Service (Same logic preserved)
// =============================================================================
@Service
@Transactional
public class InvoiceService {
    
    private final CustomerRepository customerRepository;
    private final TaxCalculationService taxCalculator;
    private final Logger log = LoggerFactory.getLogger(InvoiceService.class);
    
    public InvoiceService(CustomerRepository customerRepository, 
                          TaxCalculationService taxCalculator) {
        this.customerRepository = customerRepository;
        this.taxCalculator = taxCalculator;
    }
    
    public Invoice generateInvoice(Order order) {
        // PRESERVED: Same calculation logic
        BigDecimal subtotal = calculateSubtotal(order);
        BigDecimal tax = taxCalculator.calculate(subtotal, order.getState());
        BigDecimal total = subtotal.add(tax);
        
        // PRESERVED: Same business rule - early payment discount
        if ("NET10".equals(order.getPaymentTerms())) {
            total = applyEarlyPaymentDiscount(total, new BigDecimal("0.02"));
            log.debug("Applied 2% early payment discount for order {}", order.getId());
        }
        
        return new Invoice(order.getId(), subtotal, tax, total);
    }
    
    private BigDecimal applyEarlyPaymentDiscount(BigDecimal amount, BigDecimal rate) {
        // PRESERVED: Exact same calculation
        return amount.multiply(BigDecimal.ONE.subtract(rate));
    }
}

Media and Asset Preservation

Asset Types to Track

Asset Migration Checklist

## Asset Migration Verification

### Static Files
- [ ] All images copied to wwwroot/images
- [ ] All CSS files copied and paths updated
- [ ] All JavaScript files copied and bundle references updated
- [ ] Favicon and icons present
- [ ] Fonts copied and CSS @font-face paths updated

### Dynamic Content
- [ ] Upload directory strategy defined (local vs. Azure Blob)
- [ ] Existing uploads migrated or migration plan in place
- [ ] Image processing libraries updated (System.Drawing → ImageSharp)

### Templates
- [ ] Email templates preserved and tested
- [ ] PDF generation templates migrated
- [ ] Report templates converted or alternative chosen

### Configuration Files
- [ ] XML configs transformed to JSON
- [ ] Resource files (.resx) migrated
- [ ] Localization files preserved

Verification Strategies

Unit Test Generation for Business Logic

For each business logic item, generate a verification test:

// Test to verify business logic preservation
[Fact]
public void CalculateTotal_WithVipCustomer_AppliesTenPercentDiscount()
{
    // Arrange - Same inputs as legacy system test
    var order = new Order
    {
        CustomerId = 123, // VIP customer
        Items = new List<OrderItem>
        {
            new() { Price = 100m, Quantity = 1 }
        }
    };
    
    // Act
    var total = _orderService.CalculateTotal(order);
    
    // Assert - Must match legacy system output
    // Subtotal: 100, Tax (8%): 8, Discount (10%): 10, Total: 98
    Assert.Equal(98.00m, total);
}

Comparison Testing

// Run same input through legacy and modern systems, compare outputs
[Theory]
[MemberData(nameof(GetLegacyTestCases))]
public void ModernSystem_ProducesSameOutput_AsLegacy(
    TestInput input, 
    LegacyOutput expectedOutput)
{
    // Act
    var modernOutput = _modernService.Process(input);
    
    // Assert - Outputs must match
    Assert.Equal(expectedOutput.Result, modernOutput.Result);
    Assert.Equal(expectedOutput.SideEffects, modernOutput.SideEffects);
}

Tracking During Migration

Status Codes

Update Protocol

After each migration session, update the Business-Logic-Mapping.md:

1. Mark completed items with status change
2. Add new discoveries to the inventory
3. Document any modifications with justification
4. Update verification status after testing
5. Note blockers with required decisions

Integration with Migration Phases

Phase 1 (Assessment)

• Create initial Business-Logic-Mapping.md
• Identify all business logic locations
• Categorize by type and complexity
• Estimate migration effort per item

Phase 2 (Code Migration)

• Reference mapping during migration
• Update status as items are migrated
• Preserve logic exactly unless documented
• Generate verification tests

Phase 3+ (Infrastructure/Deploy)

• Verify media assets are accessible
• Confirm cloud storage for uploads
• Test integrations end-to-end

Templates and Examples

See the examples directory for:

Report Template

• Business-Logic-Mapping-Template.md - Copy to reports/ and fill in during migration

.NET Code Conversion Examples

• controller-example.cs - .NET Framework MVC to .NET 10 controller
• service-example.cs - .NET Framework service to .NET 10 with caching and logging
• model-example.cs - EF6 entity to EF Core with business methods

Java Code Conversion Examples

• controller-example.java - Java EE JAX-RS to Spring Boot REST controller
• service-example.java - EJB to Spring Boot service with business logic preservation
• model-example.java - Java EE JPA to Spring Boot JPA entity with business methods