# Migration Guide: Legacy Tools to Unified Platform

This guide documents how the standalone QC tools were consolidated into the unified HM QC Platform (v1.0.0).

## What Was Consolidated

| Source | Destination | Status |
|--------|------------|--------|
| `hm_qc/` (standalone CLI tool) | `modules/hm_qc/` | Complete |
| `hm_qc_video/hm_video_ai_qc_tool/` | `modules/video_qc/` | Complete |
| Reporting Dashboard (in this repo) | `modules/reporting/` | Complete |
| Test files, results, cheat sheets | `reference/` (gitignored) | Complete |
| Censorship training images | `data/supporting/censorship_trainset/` (gitignored) | Complete |

## File Mapping: hm_qc (Image/PDF QC)

### Checks
| Original Path | New Path |
|--------------|----------|
| `hm_qc/checks/HM_parse.py` | `modules/hm_qc/checks/legacy/HM_parse.py` |
| `hm_qc/checks/HM_filename_parse.py` | `modules/hm_qc/checks/legacy/HM_filename_parse.py` |
| `hm_qc/checks/HM_imprint_check.py` | `modules/hm_qc/checks/legacy/HM_imprint_check.py` |
| `hm_qc/checks/HM_language_validate.py` | `modules/hm_qc/checks/legacy/HM_language_validate.py` |
| `hm_qc/checks/HM_price_currency_check.py` | `modules/hm_qc/checks/legacy/HM_price_currency_check.py` |
| `hm_qc/checks/HM_censorship.py` | `modules/hm_qc/checks/legacy/HM_censorship.py` |
| `hm_qc/checks/HM_image_parse.py` | `modules/hm_qc/checks/legacy/HM_image_parse.py` |
| `hm_qc/checks/HM_image_filename_parse.py` | `modules/hm_qc/checks/legacy/HM_image_filename_parse.py` |
| `hm_qc/checks/HM_image_dimension_check.py` | `modules/hm_qc/checks/legacy/HM_image_dimension_check.py` |
| `hm_qc/checks/html_reporter.py` | `modules/hm_qc/checks/legacy/html_reporter.py` |
| `hm_qc/checks/analyze_with_gpt.py` | `modules/hm_qc/checks/legacy/analyze_with_gpt.py` |
| `hm_qc/checks/unzip_and_verify_check.py` | `modules/hm_qc/checks/legacy/ford/unzip_and_verify_check.py` |
| `hm_qc/checks/image_resolution_check.py` | `modules/hm_qc/checks/legacy/ford/image_resolution_check.py` |
| `hm_qc/checks/file_size_check.py` | `modules/hm_qc/checks/legacy/ford/file_size_check.py` |
| `hm_qc/checks/colour_existence_check.py` | `modules/hm_qc/checks/legacy/ford/colour_existence_check.py` |
| `hm_qc/checks/image_linking_check.py` | `modules/hm_qc/checks/legacy/ford/image_linking_check.py` |
| `hm_qc/checks/missing_images_check.py` | `modules/hm_qc/checks/legacy/ford/missing_images_check.py` |
| `hm_qc/checks/special_requirements_mec_bau.py` | `modules/hm_qc/checks/legacy/ford/special_requirements_mec_bau.py` |
| `hm_qc/checks/business_data_check.py` | `modules/hm_qc/checks/legacy/ford/business_data_check.py` |

### Other Files
| Original Path | New Path |
|--------------|----------|
| `hm_qc/qc_module.py` | `modules/hm_qc/legacy_orchestrator.py` |
| `hm_qc/config.py` | `modules/hm_qc/legacy_config.py` |
| `hm_qc/profiles/*.json` | `modules/hm_qc/profiles/legacy/` |
| `hm_qc/launchers/*.py` | `modules/hm_qc/launchers/` |
| `hm_qc/utils/*` | `modules/hm_qc/utils/` |
| `hm_qc/supporting/censorship_trainset/` | `data/supporting/censorship_trainset/` |
| `hm_qc/README.md` | `modules/hm_qc/legacy_README.md` |
| `hm_qc/DEV_SETUP.md` | `modules/hm_qc/legacy_DEV_SETUP.md` |
| `hm_qc/CLAUDE.md` | `modules/hm_qc/legacy_CLAUDE.md` |

## File Mapping: hm_qc_video (Video QC)

### Checks
| Original Path | New Path |
|--------------|----------|
| `hm_video_ai_qc_tool/checks/video_parse.py` | `modules/video_qc/checks/legacy/video_parse.py` |
| `hm_video_ai_qc_tool/checks/video_filename_parse.py` | `modules/video_qc/checks/legacy/video_filename_parse.py` |
| `hm_video_ai_qc_tool/checks/video_technical_check.py` | `modules/video_qc/checks/legacy/video_technical_check.py` |
| `hm_video_ai_qc_tool/checks/video_dimension_check.py` | `modules/video_qc/checks/legacy/video_dimension_check.py` |
| `hm_video_ai_qc_tool/checks/video_duration_check.py` | `modules/video_qc/checks/legacy/video_duration_check.py` |
| `hm_video_ai_qc_tool/checks/video_censorship.py` | `modules/video_qc/checks/legacy/video_censorship.py` |
| `hm_video_ai_qc_tool/checks/analyze_with_gpt.py` | `modules/video_qc/checks/legacy/analyze_with_gpt.py` |

### Other Files
| Original Path | New Path |
|--------------|----------|
| `hm_video_ai_qc_tool/qc_module.py` | `modules/video_qc/legacy_orchestrator.py` |
| `hm_video_ai_qc_tool/config.py` | `modules/video_qc/legacy_config.py` |
| `hm_video_ai_qc_tool/profiles/HM_video.json` | `modules/video_qc/profiles/legacy/HM_video.json` |
| `hm_video_ai_qc_tool/launchers/*.py` | `modules/video_qc/launchers/` |
| `hm_video_ai_qc_tool/utils/*.py` | `modules/video_qc/utils/` |
| `hm_video_ai_qc_tool/web/` (entire app) | `modules/video_qc/legacy_web/` |
| `hm_video_ai_qc_tool/README.md` | `modules/video_qc/legacy_README.md` |

## Architecture: Legacy vs New

### Legacy Check Pattern (`checks/legacy/`)
```python
def run_check(config, context, check_id):
    """Each check is a function that receives config, context, and check_id."""
    results = []
    # ... perform check ...
    results.append({"status": "pass", "message": "..."})
    return results
```

### New Check Pattern (`checks/`)
```python
class MyCheck(BaseCheck):
    """Each check is a class that inherits from BaseCheck."""
    name = "my_check"

    def execute(self, file_path, profile):
        # ... perform check ...
        return CheckResult(score=95, issues=[])
```

### Profile Mapping
| Legacy (JSON) | New (YAML) |
|--------------|------------|
| `profiles/legacy/HM.json` | `profiles/profiles.yaml` (HM section) |
| `profiles/legacy/HM_image.json` | `profiles/profiles.yaml` (HM Image section) |
| `profiles/legacy/ford_bnp.json` | `profiles/profiles.yaml` (Ford section) |
| `profiles/legacy/HM_video.json` | `modules/video_qc/profiles/profiles.yaml` |

## What Was NOT Copied

The following were intentionally excluded from the consolidation:
- `.git/` directories (separate repo histories)
- `venv/` directories (virtual environments)
- `__pycache__/` directories
- `.DS_Store` files
- `.claude/` directories (Claude Code settings)
- `reports/` and `tmp/` (working data)
- `web/uploads/` from video tool (uploaded test videos)
- `.env` files (contain secrets)

## Backup

A full backup of the original `HM_QC_Bitbucket/` directory (including all `.git` histories) was created before consolidation:

```
~/Desktop/HM_QC_Bitbucket_backup_20260225_113155.tar.gz (3.5 GB)
```

---

## Reporting Module: Box Folder Migration (v2.0 to v2.1)

The Reporting module underwent its own migration when the Box.com folder structure changed. Key details:

- **Old folder ID**: `303321539397` (flat structure)
- **New folder ID**: `133295752718` (CAMPAIGNS/{CampaignNumber}/QC/ hierarchy)
- **Environment variable**: `BOX_REPORT_FOLDER_ID=133295752718`
- **Service account**: `AutomationUser_2239684_XmNAVhQUsB@boxdevedition.com` needs access to CAMPAIGNS folder