# Change Request: CR-001

> Created: 2026-03-16
> Status: Approved
> Classification: Modification to FEATURE-038-C
> Related Feature: FEATURE-038-C (Enhanced Deliverable Viewer)
> Also Affects: FEATURE-043-A (Link Interception & Preview Modal)

## Request Details

**Requestor:** Human (UIUX Feedback-20260316-113736)
**Date Received:** 2026-03-16
**Priority:** Medium

## Description

Add .docx and .msg file content preview to the deliverable preview modal and folder view. Currently, these binary file types show "Binary file — cannot preview" when users attempt to preview them. The user uploaded both .docx and .msg files to a workflow and expects to see their content in the preview.

Server-side conversion approach:
- **.docx** files: Use `mammoth` library to convert Word documents to clean HTML (headings, lists, tables, images, bold/italic supported)
- **.msg** files: Use `extract-msg` library to extract Outlook email data (from, to, cc, date, subject, body) and render as structured HTML

## Business Justification

1. The system already accepts .docx and .msg uploads (KB and workflow file uploads) but cannot display their content
2. These are the two most common business document formats (Word documents and Outlook emails)
3. Forcing users to download-and-open externally undermines the preview feature's value proposition
4. Server-side conversion is lightweight and keeps the frontend thin

## Impact Analysis

### Classification

**Type:** Modification to FEATURE-038-C (Enhanced Deliverable Viewer)

**Reasoning:**
- MODIFICATION scoring: +6 (existing data model +2, same users +1, extends workflow +2, reuses UI +1)
- NEW_FEATURE scoring: +0 (no new screens, APIs, data models, or system boundaries)
- The CR extends the existing preview pipeline to handle two additional file formats via server-side conversion
- The existing `showPreview()` method in `deliverable-viewer.js` and `/api/ideas/file` endpoint are the natural extension points

### Comparison Matrix

| Aspect | CR Requirement | Existing Feature(s) |
|--------|---------------|---------------------|
| Users | Workflow users previewing uploaded docs | Same workflow users |
| Workflow | Preview .docx/.msg → see content | Preview text/md/html → see content; binary → "cannot preview" |
| Data Model | No change (files already stored as-is) | Files stored on disk |
| UI Elements | Same preview modal, extended content rendering (HTML iframe) | Preview modal with text/md/html/image/pdf support |
| API Endpoints | Extend existing `/api/ideas/file` with conversion layer | `/api/ideas/file` returns text or 415 for binary |

### Conflict Analysis

**Conflicts Found:** Yes (6 expected, 3 unexpected — all low/medium severity, no blockers)

| # | Type | Affected Feature | Severity | Classification | Description |
|---|------|-----------------|----------|----------------|-------------|
| 1 | Spec | FEATURE-038-C | Medium | Expected | AC-038-C.15 states "Binary files are not previewed — show 'Binary file' message". CR extends preview to .docx/.msg, contradicting this AC. Spec must be updated. |
| 2 | Spec | FEATURE-043-A | Medium | Expected | AC-043-A.6 lists binary files showing "Cannot preview" message. Out-of-Scope says "binary files show message only". Spec must carve out .docx/.msg as convertible exceptions. |
| 3 | Spec | FEATURE-038-C | Low | Expected | Out-of-Scope "Image/binary preview — text-based only" needs scope extension note for convertible binary formats. |
| 4 | Design | FEATURE-038-C | Low | Expected | `ideas_routes.py` returns 415 for any non-UTF-8 file. Must add conversion logic before the UnicodeDecodeError catch. |
| 5 | Design | FEATURE-043-A | Low | Expected | `main_routes.py` lists .docx in binary_extensions → served raw. Must add conversion path. |
| 6 | Frontend | Both | Medium | Expected | `deliverable-viewer.js:214-215` catches 415 and shows error. Must add .docx/.msg detection before generic fetch. |
| 7 | Dependency | N/A | Low | Unexpected | `extract-msg` has transitive deps (olefile, compressed-rtf). Pin versions and verify with `uv lock`. |
| 8 | Dependency | N/A | Low | Unexpected | NFR-038-C.3 says "No additional JS libraries". CR is server-side Python only — not violated but should be noted. |
| 9 | Design | FEATURE-043-A | Low | Unexpected | BR-043-A.3 lists .csv/.json as "binary" — consider fixing this inconsistency while updating binary detection. |

**Unexpected Conflict Resolution:**
- #7: Run `uv add mammoth extract-msg && uv lock` to verify no resolver conflicts
- #8: Documented — conversion is server-side Python, no frontend library additions
- #9: Defer to separate spec-fix or include minor correction in this CR scope

**Mitigation Strategy:**
- Update AC-038-C.15 to distinguish "truly binary" from "convertible binary" formats
- Update AC-043-A.6 similarly
- Sanitize mammoth HTML output with beautifulsoup4 (already a dependency)
- Add file size guard (10MB) for conversion to prevent memory exhaustion

### Affected Components

| Component | Impact Level | Details |
|-----------|--------------|---------|
| ideas_routes.py | Medium | Add conversion logic before UnicodeDecodeError catch for .docx/.msg |
| deliverable-viewer.js | Medium | Detect .docx/.msg extensions, render converted HTML in iframe |
| main_routes.py | Low | Update binary_extensions handling for .docx/.msg |
| pyproject.toml | Low | Add mammoth and extract-msg dependencies |
| FEATURE-038-C spec | Medium | Update AC-038-C.15, BR-038-C.3, Out-of-Scope |
| FEATURE-043-A spec | Low | Update AC-043-A.6 |

### Dependencies

- `mammoth` (PyPI) — .docx to HTML conversion
- `extract-msg` (PyPI) — .msg email extraction
- `beautifulsoup4` (already installed) — HTML sanitization

## Proposed Approach

1. **Backend:** Add a file conversion layer in `ideas_routes.py` that intercepts .docx/.msg before the UTF-8 decode:
   - `.docx` → `mammoth.convert_to_html()` → sanitize with BeautifulSoup → return as HTML
   - `.msg` → `extract_msg.openMsg()` → extract fields → render as structured HTML template → return
   - Return with `Content-Type: text/html` and a flag indicating converted content
2. **Frontend:** In `showPreview()`, detect converted HTML response and render in sandboxed iframe (existing HTML rendering path)
3. **Error handling:** If conversion fails, fall back gracefully to "Preview unavailable for this file type"
4. **Size guard:** Skip conversion for files > 10MB

## Mockup Impact

**UI/UX Change:** Minimal — content appears where "Binary file — cannot preview" currently shows
**Existing Mockups Referenced:** None applicable (no mockups in FEATURE-038-C folder)
**Updated Mockup(s):** Not needed — the change is content-level (showing converted HTML instead of error message), not layout-level

## Approval

- [x] Classification approved (DAO — confidence 0.92)
- [x] Conflict analysis reviewed (DAO — all conflicts classified, mitigations documented)
- [x] Approach approved (DAO — server-side conversion confirmed as correct architecture)
- [x] Ready for execution

## Execution

**Classification Result:** modification
**Conflicts Resolution:** all_expected (unexpected conflicts mitigated)

**Actions Taken:**
- [x] CR document created in feature folder
- [x] Conflict analysis completed and documented
- [x] Specification Version History updated with CR link
- [ ] [Deferred to refinement] AC-038-C.15 and BR-038-C.3 updates
- [ ] [Deferred to refinement] FEATURE-043-A AC-043-A.6 update
- [x] Next task type set: x-ipe-task-based-feature-refinement

## Links

- Feature Specification: [specification.md](./specification.md)
- FEATURE-043-A Specification: [specification.md](../../EPIC-043/FEATURE-043-A/specification.md)
- UIUX Feedback: [Feedback-20260316-113736](../../../uiux-feedback/Feedback-20260316-113736/feedback.md)

---

## Change History

| Date | Change | By |
|------|--------|----|
| 2026-03-16 | CR created — .docx/.msg preview support | Cipher 🔐 (Agent) |
